-1

我已经做了一些编写程序的实验，这些程序同时也是有效的文档，可以通过例如 Github 呈现为自述文件——这确保了代码片段是最新的和有效的——并且在 Markdown 中有一些非常有趣的发现。不幸的是，这种格式不支持自动生成的目录，所以我们研究了 AsciiDoc，它支持。

我设法复制了一个示例:toc: macro（以便能够将其放在开头摘要之后），然后继续使其成为有效的 Java，这实际上意味着您必须使用/*字符开始文件，但随后我无法制作表格的内容不再出现。

片段开始于：

= 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::[]

我的直觉是，只有当文件以设置和配置 AsciiDoc 解析的行开头时，TOC 才会按预期工作。如果在配置位之前生成任何输出（如 Java 注释），则 TOC 为空。

因此，我想知道我应该如何正确地做到这一点。我想要的只是toc::[]文件中的一个功能宏/*

4

1 回答 1

1

Asciidoc 标记文件不是 Java 源文件。虽然我知道这将是一种引人注目的格式组合，但这种能力并不存在。

为了使源文件保持最新，您的 Asciidoc 源文件可以使用该include指令来包含源文件。请参阅：https ://asciidoctor.org/docs/user-manual/#include-directive

比如说，要包含一个方法，您可以使用标签来标记方法实现的开始和结束，然后您可以像这样包含该标签分隔的代码部分：

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

请注意，如果要包含的 Java 源的路径在当前目录之外，则可能必须相应地更改安全模式：https ://asciidoctor.org/docs/user-manual/#running-asciidoctor-安全地

于 2020-06-03T21:33:19.537 回答