Cross referencing in Ddoc

[H. S. Teoh]

On Wed, Jan 01, 2014 at 06:41:50PM -0800, Andrei Alexandrescu wrote:
> On 1/1/14 4:56 AM, Jacob Carlborg wrote:
[...]
> >I'm considering it to be a sort of tag, just with a different syntax.
> >Who said tags need to have an end tag. A less verbose a minimal
> >reliance on tags would be Markdown or similar. Creating a list in
> >Markdown is simple as:
> >
> >* this
> >* is
> >* a
> >* list
> >* in Markdown
> 
> I prefer ddoc to markdown for its flexibility. Ddoc is an almost
> pure macro expansion system with minimal syntax. Markdown defines a
> bunch of syntax but has (last time I looked) is weak on macro
> capability.

Well, ddoc was designed to be a macro system, so from that POV, it's
pretty good at what it was intended to do. Whether it's the best system
for *generating documentation*, though, is a matter of opinion. Markdown
has the advantage of having very close visual appearance in the input as
compared to the output -- a stated goal of ddoc, but obviously the
unified macro syntax was a higher priority in ddoc's case. For example,
using `backticks` to write code snippets is definitely more readable
than writing $(D backticks), among many other things. But that does
introduce more syntax, which makes parsing more involved and also
requires learning more syntax. So, it's a trade-off.


> Case in point: markdown lists will be styled one way. With DDoc
> macros one can define any style of lists needed. (We've defined
> BOOKTABLE in addition to a couple of other TABLEs, which works
> beautifully in HTML and LaTeX; not sure how can be done in Markdown.

Styling is an orthogonal issue. Markdown was designed to translate to
HTML, so you'd just write CSS stylesheets to customize the output. Ddoc,
OTOH, was designed to be a generic macro system, so obviously it's
better at doing macro-based stuff.


> >If there's a specific macro that would indicate a category then it
> >would be easy to generate a table like that.
> >
> >/// $(CATEGORY searching)
> >void foo ()
> 
> The issue is with writing text out of order, something DDoc is not
> very apt at. Would be nice to improve on that (we do some of it with
> javascript).
[...]

The limitation of macro systems is that, fundamentally speaking, no
semantics are assigned to macros. A macro is just an arbitrary name that
gets recursively substituted with some pre-specified pattern.  The macro
engine doesn't know what any of the macros "mean", and therefore has no
concept of things like cross-referencing, categorization, etc., which
are all higher-level, logical concepts, that are required in order to
move data around.

There are, of course, ways of simulating this with macros, such as with
a global top-level macro that takes an arbitrary number of arguments and
can permute them at will, but this is ultimately just a hack. Macro
systems simply don't provide enough expressive power to build
abstractions like "this block of text is a `declaration` with
`identifier` as key, so add `identifier` to the index structure in the
output". Postprocessing is the only way to reliably add this kind of
semantics to it.

But postprocessing also removes some of the advantage of ddoc: if you
translate everything down to HTML tags, the postprocessor will have to
reparse the HTML and resynthesize information on where sections
begin/end, what constitutes a declaration, etc., which may not be
reliable. So now you have to use an intermediate format (like docbook)
that still captures some of the original structure, so that the
postprocessor can reliably recover the original document structure from
it. But then, you might as well just write in the intermediate format to
begin with, instead of using ddoc.

So while I do agree that ddoc is pretty good at what it does --
expanding macros -- I'm still on the fence as to whether that's the best
approach to documentation generation.


T

-- 
Sometimes the best solution to morale problems is just to fire all of the unhappy people. -- despair.com