Add footer navigation to the DLang specification

[wilzbach]

This adds a nice footer navigation to the specification documents:

I doubt that we need to update it in the near future, but if, I put the script to do so in the spec folder.
Also once this is in, further navigation updates will be easier, because the Ddoc maco string can be matched nicely.

[PetarKirov]

Is there something like a master layout template, that we can use in order to avoid repetition?

[wilzbach]

Is there something like a master layout template, that we can use in order to avoid repetition?

In Ddoc you only have macro expansion and a file doesn't know it's neighbors ... so there's unfortunately no other way than hard-coding it:
I added the duplicate definitions of the Macros to avoid undefined macro errors in the ePUB / Latex build, but I just realized that there's no need, e.g. from latex.ddoc:

DDOC_COMMENT=% $0
DDOC_UNDEFINED_MACRO = $(DDOC_COMMENT UNDEFINED MACRO: $1)

[CyberShadow]

I think at some point we will want to consolidate all these little edits into a single program which post-processes the DDoc-generated HTML files.

[PetarKirov]

I think at some point we will want to consolidate all these little edits into a single program which post-processes the DDoc-generated HTML files.

Also known as ddox :P

[CyberShadow]

I realize you're probably joking, but to be pedantic - DDox does not post-process HTML files, it generates them directly from JSON. It also only deals with Phobos/Druntime, not the spec, website, or other formats like PDF/eBook. You may be thinking of Adam Ruppe's documentation generator, which does work by post-processing DDoc output.

[PetarKirov]

To clarify, IMO the right way to implement those kinds of features is with diet templates in ddox. We do this already in dlang-tour - see https://github.com/dlang-tour/core/blob/master/views/tour.dt#L52.
Of course, I know that's easier said than done for dlang.org ;)
But I'm sure that the end result would be orders of magnitude more maintainable than adding even more feature creep to the make files, which would happen inevitably when we start adding post-processing steps.

[adamdruppe]

On Sun, Jun 18, 2017 at 03:49:06AM -0700, Vladimir Panteleev wrote: You may be thinking of Adam Ruppe's documentation generator, which does work by post-processing DDoc output.

That was true years ago, but I've since dropped that approach. My new one at dpldocs.info works by parsing the original D source code itself. This allows it to handle things like version blocks and other useful semantic info that dmd strips out of even the json. Post processing can do quite a bit (especially if you have enough decently semantic macros defined), but it too hits a wall before long.

[PetarKirov]

@adamdruppe are you using by any chance libdparse? If so, do you have anything that may be upstreamable?

[adamdruppe]

On Sun, Jun 18, 2017 at 12:22:46PM -0700, Petar Kirov wrote: @adamdruppe are you using by any chance [libdparse]

I am, though I forked it a while ago since some upstream change totally broke my code and I couldn't figure out how to correctly adapt it, so probably not much upstreamable. Besides, I haven't done a lot of changes anyway - just minor stuff to keep it up with changes to the language and a few minor fixes/tweaks like storing doc comments for anonymous enums and a few other ast nodes; nothing big. libdparse is a bit awkward and I put on a whole second layer to gather attributes and stuff in a convenient api (my visitor class builds an enhanced AST), but it does a fairly good job on the D source out of the box.