On Wed, 31 Jan 2024 00:49:09 GMT, Jonathan Gibbons <j...@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
