search

loonwerks / AGREE

Assume-Guarantee REasoning Environment
BSD 3-Clause "New" or "Revised" License
12 stars 5 forks source link

AGREE doc build does not generate ToC #88

Open kfhoech opened 2 years ago

kfhoech commented 2 years ago

A table of contents XML file for the AGREE documentation is not generated. Instead the present contents of the old user_guide_toc.xml is copied to the generated outputs directory. Fix this such that the ToC is generated from the markdown sources

kfhoech commented 2 years ago

This is somewhat thorny. For AGREE, the user guide is divided into separate html documents each containing a separate section or subsection. When the LUA script that generates the ToC XML is run it receives from Pandoc a combined document containing all the sections/subsections and the name of a combined html guide is passed in as an environment variable. Thus, the LUA script cannot differentiate which of the individual section html files to link in for each ToC entry.

There are a (at least) two approaches to resolve the problem:

  1. Separately invoke Pandoc and the LUA script to generate separate ToC files for each of the sections and passing the name of the html filename environment variable. Then combine the various ToC files for each section into a master ToC XML file. The advantages of the approach are that iterative invocation is easy and a further Python script can be written to combine the section ToC files as a separate step. The disadvantage is that the sections/subsections are at differing levels of hierarchy and a means of handling the hierarchy would need to be invented.

  2. Continue to use the single invocation of Pandoc and the LUA script but rather than passing in the name of a single combined document, pass in a table mapping section/subsection numbers to section/subsection filenames and modify the LUA script to look up the appropriate html link for each section/subsection heading in the ToC. The development of the mapping from section/subsection number to html file would be done as a precursor step.

Either way, there needs to be a mechanism to derive a mapping from section/subsection numbers to file names. In the input source the convention is that the filename is prefixed with the top level section number and the second level section number. Also need to handle letters as this is done for appendices.