Cross referencing in Ddoc

[Jonathan M Davis]

On Thursday, January 02, 2014 13:38:22 H. S. Teoh wrote:
> 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.

That depends on how you go about post-processing. If you design your ddoc 
macros with the idea that there's going to be post-processing, then they can 
convert to other ddoc macros which are designed for the post-processor to be 
able to handle, and then the post-processor can convert those into another set 
of macros that you run ddoc on again to get the final result. That's 
essentially what I've done when using ddoc for stuff like a table of contents 
or index.

Now, if the post-processing is really the last step rather than just post one 
of multiple runs of ddoc, then it's stuck dealing with whatever the target 
format is, but if you do multiple runs of ddoc with a separate program 
operating on the intermediate results of the macro expansion and then 
generating a new set of ddoc macros for another run of ddoc, then your post-
processor doesn't have to understand the target format.

- Jonathan M Davis