• Andre Artus (20/30) Aug 16 2013 The text describing Sections in Documentation Generator page
• H. S. Teoh (14/38) Aug 23 2013 Sorry for the late reply, it's kinda hard keeping up with this
• Andre Artus (20/63) Aug 24 2013 I think the description/explanation of a section name should be
• Andre Artus (19/19) Aug 24 2013 I have been racking my brain to find a suitable replacement for

"Andre Artus" <andre.artus gmail.com> writes:

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).

I propose the following change:

 "A section is a block of text that is given special meaning by 
 the document
 generator based on either position or a{n} [predefined?]
 (identifier|name|label|keyword). Details of each kind of 
 section follow"

Of course the bracketed parts need to be cleared up, it's of 
little use as I wrote it above.

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

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

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)?

"H. S. Teoh" <hsteoh quickfur.ath.cx> writes:

Sorry for the late reply, it's kinda hard keeping up with this
high-volume mailing list. :)


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 ':'.


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

Yes.


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

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


 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)?

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


T

-- 
Long, long ago, the ancient Chinese invented a device that lets them see
through walls. It was called the "window".

"Andre Artus" <andre.artus gmail.com> writes:

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.

"Andre Artus" <andre.artus gmail.com> writes:

I have been racking my brain to find a suitable replacement for 
the section description, I would appreciate your critique.

"A section is a block of text that is processed by the document 
generator. There are only two unlabeled sections, summary and 
description, all other sections are identified by a label (or 
name). A section label starts with the first non-blank 
character[1] on a line and continues until terminated by a colon 
(:).

Details of each kind of section follow"


1. This is technically not true, as the first non-blank character 
could be an asterisk. As far as  I can see the section labels 
follow the same rules as other identifiers. But, according to the 
description above the following,

/**

*/


][|"-- which seems questionable to me.

I think we should tighten up the rules regarding section labels.