Automatically generate TOC menu for the specification pages

[wilzbach]

The Makefile target update-spec-toc is idempotent and thus can be called as called as part of the build process. In a later PR, we can do sth like dlang/dmd#7483 and ensure that the git working directory is clean or in other words that the update-spec-toc didn't need to do any changes.

[dlang-bot]

Thanks for your pull request, @wilzbach!

Bugzilla references

Auto-close	Bugzilla	Description
✓	18202	Show TOC overview in the dlang specification pages

[JinShil]

There's quite a bit of redundancy between the grammar specifications and the table of contents:

http://dtest.dlang.io/artifact/website-a8466b059a80a6ed06a54bc20933af661c945799-b8f9a919d0890d3eacff31373bc726c0/web/spec/traits.html
http://dtest.dlang.io/artifact/website-a8466b059a80a6ed06a54bc20933af661c945799-b8f9a919d0890d3eacff31373bc726c0/web/spec/attribute.html

It doesn't bother me much, but it was quite noticeable.

The table of contents is especially nice on other pages, though:

http://dtest.dlang.io/artifact/website-a8466b059a80a6ed06a54bc20933af661c945799-b8f9a919d0890d3eacff31373bc726c0/web/spec/ddoc.html

[wilzbach]

There's quite a bit of redundancy between the grammar specifications and the table of contents:

That would be very trivial to fix. The update script searches for $(SPEC_HEADERNAV_TOC ...) DDoc macros. So simply removing the TOC in the spec page for these pages works.

[JinShil]

That would be very trivial to fix.

I don't know if it needs to be "fixed", it was just and observation.

[wilzbach]

I know that this looks quite shocking for reviewers with 45 files changed and 20 commits, but please note that most of it is generated and I used tiny commits for a very granular history.

Also considering that this a similar effort was merged two years ago (dlang/tools#180) and comes up in the NG from time to time (e.g. the most recent post is http://forum.dlang.org/post/bbghyhuzuofogjxkwisb@forum.dlang.org), shows that there's quite some interested in it.

(I rebased as I added a Bugzilla issue for it)

[CyberShadow]

Could this be done as part of the build instead of modifying the source files?

[wilzbach]

Could this be done as part of the build instead of modifying the source files?

Hmm we could add a layer on top of Ddoc, but IIRC the last time I tried to add sth. like this you weren't really happy about it either.
So the simple thing that comes to my mind would be to have a ddoc.d that does these replacement on the fly and then handing the ddoc file on to dmd -D -. Is that what you were thinking about?

[CyberShadow]

So the simple thing that comes to my mind would be to have a ddoc.d that does these replacement on the fly and then handing the ddoc file on to dmd -D -. Is that what you were thinking about?

That sounds like a good idea.

[wilzbach]

That sounds like a good idea.

-> #2060

I separated my improvements to the footer generation to #2061, but when #2060 is accepted, we can also integrate the footer generation into this script. Moreover, I just realized that this DDoc wrapper might solve a lot of our other DDoc problems.