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