[Issue 2060] New: some ddoc design typos

[d-bugmail at puremagic.com]

http://d.puremagic.com/issues/show_bug.cgi?id=2060

           Summary: some ddoc design typos
           Product: D
           Version: 2.012
          Platform: PC
               URL: http://www.digitalmars.com/d/2.0/ddoc.html
        OS/Version: Windows
            Status: NEW
          Severity: enhancement
          Priority: P2
         Component: DMD
        AssignedTo: bugzilla at digitalmars.com
        ReportedBy: terranium at yandex.ru


1. ddoc is html-oriented. Because $(BODY) macro contains comment <!-- Generated
by Ddoc from file.d -->
AFAIK this is the only place where source file name and generator's name are
contained and this comment is atomic (hard to parse) and intranslatable. This
information should be provided in macros, separated from $(BODY) and .ddoc
template should give credits to the generator.
One more issue here. In delineated code examples <, > and & are replaced with
corresponding entity references. Well... this one just helps a lot in
generating xml documentation :) I'm affraid this breaks documentation a little
when generating to plain text. Although here can be workaround: one can
generate plain text documentation from xml one.

2. ddoc is display-oriented. Well... not ddoc itself, it's rather its
specification where "Basic Formatting Macros" are listed. This tends to be
percieved as built-in macros while they are private macros for internal use in
default .ddoc template, so they should not be exposed as standard. More
meaningful formatting macros should be used. In terms of html Phrase Elements (
http://www.w3.org/TR/html401/struct/text.html#h-9.2.1 ) should be used instead
of Font Style Elements (
http://www.w3.org/TR/html401/present/graphics.html#h-15.2 ). BTW you already
did this for member lists marking them up by dl/dt/dd instead of table or ul.
WCAG 1.0: http://www.w3.org/TR/WCAG10-HTML-TECHS/#text
WCAG 2.0:
Using semantic elements to mark up structure
http://www.w3.org/TR/2007/WD-WCAG20-TECHS-20071211/G115.html "The objective of
this technique is to mark up the structure of the Web content using the
appropriate semantic elements. In other words, the elements are used according
to their meaning, not because of the way they appear visually."
Understanding Success Criterion 1.3.1
http://www.w3.org/TR/2007/WD-UNDERSTANDING-WCAG20-20071211/content-structure-separation-programmatic.html
"The intent of this Success Criterion is to ensure that information and
relationships that are implied by visual or auditory formatting are preserved
when the presentation format changes. For example, the presentation format
changes when the content is read by a screen reader or when a user style sheet
is substituted for the style sheet provided by the author."

3. Formatting of custom sections. Default declaration of DDOC_SECTION_H is
DDOC_SECTION_H = $(B $0)$(BR)$(BR)
But $0 sould not contain trailing colon, which is provided by ddoc engine and
is hard to remove, this colon sould be moved to DDOC_SECTION_H macro
DDOC_SECTION_H = $(B $0:)$(BR)$(BR)
so its apperance could be customizable.
Ideal variant is for DDOC_SECTION macro to have 2 parameters: $0 for section
title and $1 for section body, this will provide higher customizability for
section formatting, for example, for xml output
DDOC_SECTION = <section name="$0">$1</section>

4. It seems like ddoc forces DDOC_BLANKLINE after DDOC_SECTION_H.
DDOC_BLANKLINE can't be made empty because this will change its meaning and
break existing code relying on DDOC_BLANKLINE macro.


--