Cross referencing in Ddoc

[Jonathan M Davis]

On Friday, January 03, 2014 12:12:44 Jacob Carlborg wrote:
> On 2014-01-03 01:56, Jonathan M Davis wrote:
> > 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.
> 
> Seems unnecessary complicated.

It depends on what you're trying to do. For generating something like a table 
of contents, it's pretty straightforward.

For instance,

$(CHAPTER Introduction,
    $(P Contents of chapter)
 )

could be processed by a short program to have that chapter's name put in the 
table of contents which it generates (which is then also ddoc). e.g.

$(TABLE_OF_CONTENTS
    $(CHAPTER_ENTRY Introduction, 1)
    $(CHAPTER_ENTRY Some Other Chapter, 2)
    $(CHAPTER_ENTRY Conclusion, 3)
)

and if any other operations need to be done on CHAPTER to make it suitable for 
your target formats, then it can be tweaked as necessary.

You then take the resulting .dd file and generate the documentation with the 
ddoc file that corresponds to the target format (e.g. html.ddoc or latex.ddoc 
or whatever). I've found that it works quite well.

But that's for generating a book, not documentation for code. You could do 
something similar to generate cross-references in code documentation, I'm 
sure, but I wasn't necessarily suggesting that we do. I was just pointing out 
that it's quite possible (and not necessarily difficult) to manipulate a .dd file 
(or a .d file with ddoc in it) to generate another .dd file which you then 
actually use to generate the html or latex or whatever you need to generate 
and that you don't necessarily need to manipulate the target format to get 
what you want.

- Jonathan M Davis