Feature Request - Raw HTML in ddoc comments

Bill Baxter dnewsgroup at billbaxter.com
Sat Mar 1 14:07:30 PST 2008


Janice Caron wrote:
> On 01/03/2008, Bill Baxter <dnewsgroup at billbaxter.com> wrote:
>> DMD is at fault here. DMD should /not/ pass HTML
>>
>>> through unchanged. It should sanitize the input, in order specifically
>>  > to prevent it from being interpreted as markup in the output format.
>>
>> But DDoc doesn't know anything about the output format.
> 
> I didn't say the ddoc format was at fault, I said DMD was at fault.
> 
> It is the translation tool which is at fault. A tool which translates
> DDOC into HTML must, by definition, know about HTML - just as a tool
> which translates DDOC into PDF must know about PDF.
> 
> In this case, the translation tool happens to be DMD.
> 
> 
>>  Fixing this by escaping all HTML syntax is not really a fix.  What if I
>>  type some raw LaTeX in my input?  It'll probably be treated like text
>>  for HTML output, but be interpreted as code if I output LaTeX.
> 
> The correct behavior would be for any DDOC->HTML translation tool to
> escape HTML, and for any DDOC->LaTeX translation tool to escape LaTeX.
> This has nothing whatsoever to do with DDOC format. The problem is in
> the translation tools.
> 
> To make an analogy, if I write a tool that translates any source
> format into XML,then I **MUST** escape anything < and & and ", because
> otherwise the resulting document will not be well formed, and will be
> invalid. This will not have been the fault of the source format, it
> will have been a bug in my application!
> 
> 
>>  Like Adam said, the only way to really fix it is to teach DDoc
> 
> I don't understand what you mean here. So far as I am aware, DDOC is a
> markup language, not an application. It is therefore not possible to
> "teach" it anything. I say, leave DDOC alone - just do a better job of
> translating it.

By DDoc I mean the system that generates documentation from comments in 
D code.

DDoc is not in and of itself a DDoc comment->HTML translation tool. 
DDoc is a macro processing system, that, with the right set of macros, 
can be made to generate HTML.  But the macro processor itself has no 
clue what HTML is.  That's Walter's whole idea with DDoc -- put _all_ 
the output-specific knowledge in the macros.  It does come with a 
built-in set of HTML macros, because not being able to generate anything 
by default would make it pretty lame.

At least that's the theory of DDoc as I understand it.  Examination of 
dmd/src/doc.c reveals a slightly different picture where some knowledge 
of HTML specifcs *are* actually embedded in the processing logic (see 
function "highlightText").  I'm not sure what the purpose of that is, 
but any HTML-specific scanning in the ddoc processor is probably a bug.

"Whether the final presentation form is an HTML web page, a man page, a 
PDF file, etc. is not specified as part of the D Programming Language."
   -- http://www.digitalmars.com/d/1.0/ddoc.html

--bb



More information about the Digitalmars-d mailing list