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.
