RFR: JDK-8325004: Support a "table-of-contents" for some Markdown spec docs

[Magnus Ihse Bursie]

On Wed, 31 Jan 2024 00:49:09 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a small change, at least as a "proof of concept", to allow customized options to be given to `pandoc` based on the module and filename for a spec.
> 
> The goal is to allow a Markdown spec file to have an auto-generated table-of-contents, by including the `--toc` option when running pandoc for specific documents.
> 
> There may be better ways to achieve this goal; while I have a working knowledge of this makefile, I'm not an expert. In particular, I tried to find a way to defer the evaluation of the option, so that the declaration of the value did not have to appear before its use in the macros.  But I could only get it to work as presented here.
> 
> No other support for a TOC is needed, since we already generate TOCs for other pages, like tool guides (man pages.)

... wait a moment now. 

I thought I'd already added a mechanism to let the markdown file itself request a TOC?

make/Docs.gmk line 640:

> 638: # Customization for specific files
> 639: 
> 640: jdk.javadoc_doc-comment-spec.md_TOC := --toc

Since this is a method to add any kind of options to pandoc, please call it _OPTIONS instead of _TOC.

Or, if you really want to make it toc-specific, you should do something like:

jdk.javadoc_doc-comment-spec.md_TOC := true

and check the boolean value for this and add `--toc` as appropriate. (That does seem like a worse solution to me.)

make/Docs.gmk line 662:

> 660:             DEST := $(DOCS_OUTPUTDIR)/specs/, \
> 661:             CSS := $(GLOBAL_SPECS_DEFAULT_CSS_FILE), \
> 662:             OPTIONS := $($m_$(notdir $f)_TOC) -V include-before='$(SPECS_TOP)' -V include-after='$(SPECS_BOTTOM_$($m_$f_NOF_SUBDIRS))', \

I'd like you to calculate a variable for this, a few lines above (can't mark it in github review mode 😞), like:

        $(eval $m_$f_OPTIONS := $($m_$(notdir $f)_OPTIONS) \


and then use that variable instead in the OPTIONS line.

-------------

PR Comment: https://git.openjdk.org/jdk/pull/17642#issuecomment-1918776133
PR Review Comment: https://git.openjdk.org/jdk/pull/17642#discussion_r1472583444
PR Review Comment: https://git.openjdk.org/jdk/pull/17642#discussion_r1472581520