-1

I have done some experiments with writing programs that are also at the same time valid documentation that can be rendered as README's by e.g. Github - this ensures that code snippets are up to date and valid - and had some very interesting findings with Markdown. Unfortunately that format does not support having an automatically generated table of contents, so we looked into AsciiDoc which does.

I managed to copy an example using :toc: macro (to be able to place it after the opening summary), and then went on to make it valid Java, which essentially mean that you have to start the file with the /* characters but then I cannot make the table of contents appear any more.

The snippet starts with:

= Asciidoctor PDF Theming Guide
Dan Allen <https://github.com/mojavelinux[@mojavelinux]>
// Settings:
:idprefix:
:idseparator: -
:toc: macro
:experimental:
ifndef::env-github[:icons: font]
ifdef::env-github[]
:outfilesuffix: .adoc
:!toc-title:
:caution-caption: :fire:
:important-caption: :exclamation:
:note-caption: :paperclip:
:tip-caption: :bulb:
:warning-caption: :warning:
endif::[]
:window: _blank
// Aliases:
:conum-guard-yaml: #
ifndef::icons[:conum-guard-yaml: # #]
ifdef::backend-pdf[:conum-guard-yaml: # #]
:url-fontforge: https://fontforge.github.io/en-US/
:url-fontforge-scripting: https://fontforge.github.io/en-US/documentation/scripting/
:url-prawn: http://prawnpdf.org

////
Topics remaining to document:
* line height and line height length (and what that all means)
* title page layout / title page images (logo & background)
////

[.lead]
The theming system in Asciidoctor PDF is used to control the layout and styling of the PDF file 
... blurb removed ...
/* (Experiment with asciidoc)

= Dagger 2 Hello World

// (Important:  As an experiment Main.java is also a valid markdown file copied unmodified to README.md, so only edit Main.java)

This project is a single file Hello World Dagger-2 Maven project for
Java 8 and later, while also being its own documentation written in AsciiDoc.

toc::[]

My gut feeling is that the TOC does only work as expected if the file starts with lines parsed by AsciiDoc where this is set up and configured. If any output is generated before the configuration bits (like the Java comment) then the TOC is silently empty.

Hence I would like to know how I should do this correctly. All I want is a functional toc::[] macro in a file starting with /*

Thorbjørn Ravn Andersen
  • 73,784
  • 33
  • 194
  • 347

1 Answers1

1

Asciidoc markup files are not Java source files. While I understand that this would be a compelling combination of the formats, that capability does not exist.

To keep source files up-to-date, your Asciidoc source files can use the include directive to include a source file. See: https://asciidoctor.org/docs/user-manual/#include-directive

To include, say, a single method, you can use tags to mark the start and end of the method's implementation, and then you can include that tag-delimited code section like this:

[source,java]
----
include::path/to/source.java[tag="method-x"]
----

Note that if the path to the Java source that you want to include is outside of the current directory, you may have to change the safe mode accordingly: https://asciidoctor.org/docs/user-manual/#running-asciidoctor-securely

eskwayrd
  • 3,691
  • 18
  • 23