www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.bugs - [Issue 2060] New: some ddoc design typos

reply d-bugmail puremagic.com writes:
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 digitalmars.com
        ReportedBy: terranium 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.


--
Apr 30 2008
next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=2060






1. Ooh... or DDOC_COMMENT macro is used here?


--
Apr 30 2008
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=2060








I just posted a request for comments and proposals on the DNG.  In short, the
use of DDOC need to be much more semantic, and generated DDOC output should
never be passed back to the doc engine as raw output.  While this will increase
the complexity of the typical .ddoc script, as well as require several new
standard macros, the result will be richer output.  This will also open the
door for XML-based documentation, which is a handy way to move beyond DDOC's
limitations.

http://www.digitalmars.com/webnews/newsgroups.php?art_group=digitalmars.D&article_id=70806


--
Apr 30 2008
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=2060






UPD:

1. DDOC_COMMENT is used.
4. I was wrong here

5. In module-level copyright section <, > and & are not replaced with entities.

6. In all sections if valid opening or closing tag is encountered, it's passed
unchanged to the output. This breaks xml output, while html doesn't suffer for
this behavior. This is a consequence of ddoc engine being html-oriented.

Workaround: developer must be aware of the documentation output format and use
<, > and & carefully.


--
May 01 2008
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=2060






Test cases.

5.
/++
Copyright: me < & > you
+/
module foo.bar;

6.
///Summary for </html> Foo ends html document
class Foo{}


--
May 01 2008
prev sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=2060






The <!-- ... --> comment is generated by DDOC_COMMENT, which can be overridden
by the user. The other suggestions are good.


--
May 11 2008