Feature Request - Raw HTML in ddoc comments

Roberto Mariottini rmariottini at mail.com
Mon Mar 3 00:30:18 PST 2008


Walter Bright wrote:
> Janice Caron wrote:
>> On 01/03/2008, Walter Bright <newshound1 at digitalmars.com> wrote:
>>> Janice Caron wrote:
>>>  > In general, any tool which converts SRC -> DST needs to escape all
>>>  > characters which would be considered markup in DST.
>>>
>>> That is not possible, because ddoc cannot escape every markup in every
>>>  possible output format past, present, and future. ddoc is output
>>>  agnostic - the output is controlled by the macro expansion text.
>>
>> I don't know what "macro expansion text" means.
> 
> Given the macro:
>     FOO= bar $0 def
> the source:
>     $(FOO abc)
> expands to:
>     bar abc def
> 
> It's simple text replacement. Ddoc can use a default set of macro 
> definitions, or the user can supply one.

I don't think this will make Ddoc sufficiently portable across output 
formats.
The source code will be filled with macros to escape character sequences 
in any supported output format, and become impossible to maintain.

For example, now Ddoc generates HTML, so the user defines the macro 
$(LT) to generate a literal '<' on the output, $(AMP) to generate a 
literal '&' and so on.
Then the user wants to generate TeX output (provided that the base set 
of macros to generate TeX output is available), so she has to add other 
macros to escape TeX output, such as $(BACKSLASH), $(LBRACE) and so on.
Then the user needs to generate RTF, so she adds a full other set of 
macros, then another set for troff, and so on.
At the end the source code is filled of $(AMP), $(BACKSLASH), $(DOT), 
$(LBRACE) that add nothing to the formatting of the output document, but 
are used only to escape output.

Ddoc must provide a way to define escaping of characters for every 
particular output format. I don't know how, but some way must be found.

Otherwise programmers will stop to write documentation.

Ciao
-- 
Roberto Mariottini, http://www.mariottini.net/roberto/
SuperbCalc, a free tape calculator: 
http://www.mariottini.net/roberto/superbcalc/



More information about the Digitalmars-d mailing list