[dox] Text describing Sections in Documentation Generator page needs improvement

[Andre Artus]

On Friday, 23 August 2013 at 21:41:01 UTC, H. S. Teoh wrote:
> Sorry for the late reply, it's kinda hard keeping up with this
> high-volume mailing list. :)

Tell me about it :)

> On Sat, Aug 17, 2013 at 12:08:06AM +0200, Andre Artus wrote:
>> The text describing Sections in Documentation Generator page
>> (http://dlang.org/ddoc.html) needs improvement.
>> 
>> It reads:
>> 
>> >Sections
>> 
>> >The document comment is a series of Sections. A Section is a 
>> >name
>> >that is the first non-blank character on a line
>> >immediately followed by a ':'. This name forms the section
>> >name. The section name is not case sensitive.
>> 
>> 
>> My issues with this are the following.
>> 
>> 1. A section is not a name. It ~has~ a name (except when it
>> doesn't).
>
> Yeah, it should say that the document comment is divided into 
> sections, and section names consist of a sequence of non-blank 
> characters followed a ':'.

I think the description/explanation of a section name should be 
done separately from the description of sections. As far as I 
understand it there are only 2 section types that are sans name 
(summary and description), but bringing in names as part of the 
section description muddies the waters a bit (in my opinion).


> [...]
>> 2. A name can be more than one character. I believe all the 
>> standard sections have names longer than 1 character.

> HST
> Yes.

>> 3. Some sections do not end their identifiers with a colon 
>> (':') to
>> wit "Escapes=".

> HST
> Oh? I don't think that's a section, that looks like a macro 
> definition.

A^2
It's kind of a section for text substitutions, each substitution 
pair can be seen as an parameter-less macro, but I think 
"Escapes=" still denotes a section, similar to the "Macros:" 
section.

I'm not quite clear on how "Escapes=", "Macros:", and embedded 
HTML serves the goal of decoupling the content from the 
presentation (e.g. PDF, LaTex,...). I would think that escape 
sequences would be configuration for the [output] generator.


>> 4. The wording leaves the impression that arbitrary named 
>> sections are
>> possible, is this the case? Or are the named sections 
>> predefined (i.e.
>> those listed as standard and special sections)?

> HST
> Arbitrary names are possible. The predefined names may have 
> special interpretations.

A^2
If one wants to add a new named section (not predefined), do you 
need to create a macro expansion for it, or how does it work? It 
would probably be good to add some guidance for that.