Re: Comments on Learning Manual 3 -- Fundamental concepts

[John Mandereau]

2008/8/11 Graham Percival <address@hidden>:
> On Sat, 9 Aug 2008 23:54:44 +0200
> "Valentin Villenave" <address@hidden> wrote:
>> Actually, this is a Johnism (I don't know why he keeps asking us to
>> remove parentheses).
>
> Parentheses are discouraged in highly formal writing, but they add
> clarity and the docs aren't extremely formal, so let's use them.

It's true that I excessively want to remove parentheses everywhere,
and I agree parentheses are useful and add clarity for short phrases.
However, using parentheses to enclose long phrases or even full
sentences is poor in formal writing, in this case long dashes or
footnotes are preferable.  Our docs should follow formal writing,
especially in NR, even if we can be more tolerant in LM.  BTW good
references for French typography discourage use of parentheses too, so
I'm not very tolerant in this respect in French translations.


>> What I have in mind when commenting an .itely file is that comments
>> may be useful for the next documentation team (when the guys will
>> start their own Grand Documentation Project in 10 years).
>> In this specific case, theoretically doc writers are aware that the
>> engraver is not used anymore...

I'm afraid that some innocent docs writer is tempted to change back to
Dynamic_engraver will check the Internals Reference first and see that
this engraver is longer used in any context, although it still exists;
that's why I left this comment in my commit, which doesn't cost much.

Cheers,
John