On Tue, Jun 14, 2011 at 10:58:31PM +0100, Stuart Henderson wrote:
> >
> > so i'm not fussed. i'll leave it to stuart to decide whether the example
> > is actually needed or not. i suppose if it is different to the shell, it
> > will confuse people.
>
> I think it needs to be mentioned explicitly as, although it's something
> people coming from a programming background might expect, it's completely
> alien to people who only edit configuration files and common scripting
> languages.
>
> You're right about it getting copied to other places, there are 9
> copies in tree and I'd rather not come up with an example for each,
> so I would be happier to have it in the text rather than as an
> example if it can be done clearly, but I haven't managed it...
>
so i suggest you just go with wording similar to that which i proposed,
which does cover the case we're talking about. i think florian's tweak
("including comments") was definitely an improvement.
i don;t think marco's suggestion will help though - i think without any
clear context or examples, the sentence is likely to confuse more people
than help. i know i wouldn;t have understood it exactly without having
had this conversation.
remember this issue (such that it is) is only going to effect a very
small number of people. we just need to make sure that if they read the
man page carefully, they come to the conclusion that we want them to.
jmc
