(X)HTML/XML in DDoc

[Idan Arye]

On Friday, 17 May 2013 at 01:01:36 UTC, Borden wrote:
> On Thursday, 16 May 2013 at 21:36:03 UTC, Craig Dillabaugh 
> wrote:
>> Can you provide a reference for the claim that the next
>> incarnation of TeX is going to be XML based?  I did a quick 
>> search and
>> couldn't turn up anything.  Perhaps it was some sort of April 
>> fool's joke
>> :o)
>
> You're right. I fell for it. I think I was referring to his 
> announcement of iTeX, which any idiot should have noticed was a 
> joke. I'm no idiot, I'm apparently far more gullible :-P

If you think about it, HTML can be considered the XML based 
successor of TeX(some flexibility of thought required)



Anyways, the main problem I see with DDoc macros is that they 
don't have any computational power behind them - they put 
arguments inside fixed patterns and that's it. This might be OK 
for simple usage(like formatting and generating links), but they 
are often being used for more complex things, where they miss the 
purpose of one-source-format-compilable-to-many-target-formats.

Tables were already given as example. In the dlang.org source 
code(which is also used by the Phobos documentation) they are 
implemented by replicating the HTML tables syntax, so you need to 
write:

     $(TABLE caption
         $(TR $(TH header1) $(TH header2))
         $(TR $(TD data11)  $(TD data12))
         $(TR $(TD data21)  $(TD data22))
         $(TR $(TD data31)  $(TD data32))
     )

This works for HTML tables, but it does not work for LaTeX 
tables, since the cells are separated(by &), not delimited, so 
there is no way to define the TD macro to produce correct results 
for all cells. It'll also not work for ASCII tables - since you 
can't pad the cells and you can't determine the width of a column 
using DDoc macros.


My suggestion is to leave the macros for simple notations, and 
for the more complex ones use custom sections + scripting.

For example, the `std.algorithm` documentation has a Cheat Sheet 
table, where each function has an example of it's usage. This 
documentation is written as a big table at the head of the source 
file. This is bad, since a function's documentation in the source 
code should be concentrated near it's declaration.

But, if we had custom sections + scripting, we could add a custom 
section named `CheatSheet` and in the DDoc comment of each 
function we could add this section, and a script would collect 
all the data from these custom sections and add make a single 
table out of it.