DDoc and logically structured HTML

Stewart Gordon smjg_1998 at yahoo.com
Sat Mar 10 17:08:20 PST 2012


The default macros built into DDoc leave something to be desired in terms of HTML 
structure, for example:

- presentational <font>, <big> and <small> tags, rather than CSS equivalents
- presentational details coded directly into the macros called by DDoc, rather than 
delegated to CSS classes
- <br><br> to separate paragraphs, rather than <p></p> to enclose them.

By redefining a lot of the macros in a .ddoc file, one can do better.  However, there 
remain a number of limitations:

(a) No way to make a paragraph of the DDoc source a paragraph in the generated HTML unless 
it's specified to be something else, such as a list or a table.  While one could wrap the 
actual paragraphs in $(P ... ) and define DDOC_BLANKLINE to be empty, this undermines the 
first two of DDoc's goals (looks good as embedded documentation, and is easy and natural 
to write).

(b) No macro to be seen that corresponds to the whole block of named sections.  So I can't 
(for example) wrap them all in a <dl>.  Meanwhile I've made do with a <dl> containing a 
single <dt> and <dd> for each named section.

(c) No way to user-define sections - you can change the markup generated for the standard 
sections, but for everything else there's just DDOC_SECTION and DDOC_SECTION_H, precluding 
any distinctive highlighting of certain sections.

There are probably others I thought of earlier, but I can't think what they are at the 
moment.  But as you see, DDoc falls short of what ought to be another of its goals: to 
support the generation of logically structured output.

Has anybody else got further with getting logical HTML out of DDoc?  Have you been using 
DDoc to generate some internal format and then some other program to turn it into HTML, or 
what?


But some improvements to DDoc could certainly make things better.

Dealing with (a) admittedly isn't as simple as it may seem at first.  While you could have 
a DDOC_PARAGRAPH macro for this, there are subtleties in determining what is and isn't a 
paragraph.

(b) is straightforward - just create and use a DDOC_NAMED_SECTIONS macro.

As for (c), well, maybe we could have it so that

Custom_Section:
     blah blah blah

first looks for a macro called DDOC_Custom_Section and, if it's present, uses it.  Or if 
no such macro is present, just use DDOC_SECTION.


I don't know how far we can go short of a doclet system like JavaDoc has.  Nor even how 
exactly a doclet system would work under a language that compiles to native code....

Stewart.


More information about the Digitalmars-d mailing list