标签: asciidoc

我是asciidoc的新手。我想从java文件中带注释的javadoc（asciidoc格式）生成HTML文档。

例如java文件

/**
 * = Asciidoclet
 *
 * Sample comments that include `source code`.
 *
 * [source,java]
 * --
 * public class Asciidoclet extends Doclet {
 *     private final Asciidoctor asciidoctor = Asciidoctor.Factory.create();
 *
 *     @SuppressWarnings("UnusedDeclaration")
 *     public static boolean start(RootDoc rootDoc) {
 *         new Asciidoclet().render(rootDoc);
 *         return Standard.start(rootDoc);
 *     }
 * }
 * --
 *
 * @author https://github.com/johncarl81[John Ericksen]
 */
public class Asciidoclet extends Doclet {
}

我可以从.ad文件生成html文件，但是我不知道如何从javadoc生成.ad（或任何asciidoc格式的文件）。
所以我想生成.ad（asciidoc文件），我正在使用asciidoctor-maven-plugin生成html文档。asciidoctor-maven-plugin将在sourceDirectory中检查.ad文件，并在outputDirectory中生成html文件。

</plugin>
<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>${asciidoctor.version}</version>
    <executions>
        <execution>
            <id>output-html</id>
            <phase>generate-resources</phase>
            <goals> …

我有一个Asciidoc文档foo.1.txt,并按照这里的说明,我尝试编译它a2x如下:

a2x --doctype manpage --format manpage foo.1.txt

在此之后,我收到以下错误:

a2x: ERROR: "/usr/bin/asciidoc.py" --backend docbook -a 
"a2x-format=manpage"  --doctype manpage  --out-file 
"/home/koz/Documents/foo.1.xml" 
"/home/koz/Documents/foo.1.txt" returned non-zero exit status 1

我不确定发生了什么,或者我怎么能诊断出什么是错的.XML文件被在同一文件夹(标题为产生foo.1.xml)作为这个过程的一部分.所有帮助表示赞赏.

编辑:基于--verbose标志的使用,问题似乎在这一部分:

COPYING
----------
 Copyright \(C) 2015, Koz Ross <koz.ross@runbox.com>. Free use of this software
is granted under the terms of the GNU General Public License (GPL) version 3, or
any later version.

投诉是:[blockdef-listing] missing closing delimiter就行了COPYING.

我正在尝试用Asciidoctor在AsciiDoc轻量级标记语言中创建一个"可点击"的图像.

我尝试了以下(不工作): image::<url1>[<url2>[]]

例如:

image::https://img.shields.io/badge/License-Apache%202.0-blue.svg[http://www.apache.org/licenses/LICENSE-2.0[]]

它应该大致成为以下html:

<a href="http://www.apache.org/licenses/LICENSE-2.0"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg"></a> 

如何在不通过原始HTML的情况下在AsciiDoc中完成此操作？

我使用org.asciidoctor.convert插件进行gradle生成团队的API文档。我包含文件：

include::{snippets}/index/curl-request.adoc[] 

并希望将其内容放入扰流器或类似的东西中。有什么办法可以隐藏动态的asciidoc元素吗？我尝试使用

pass:[<details open>  
include::{snippets}/index/curl-request.adoc[]
</details>]

但它不经过处理，包括在其中。任何想法都会受到赞赏。在不隐藏代码片段的情况下，我的文档几乎没有限制：)。如果没有使用ascii doc的方式，还应该感谢其他文档格式的建议，我可以在其中包含文件内容并将其放置到剧透中。

有一些AsciiDoc有一个像...的块

----
  this is a test
    with *some* formatted/tabbed text in it
blah
----

...我希望文字显示为...

  这是一个测验
    带有一些格式化/标签的文本
等等

...其中“ some”一词为粗体。

我有一个相当大的asciidoc文档,我为我们的开发人员指南动态翻译为PDF.由于doc通常引用我们的开发人员指南中记录的Java类,因此我们将它们直接转换为文档中的链接,例如:

In this block we create a new 
https://www.codenameone.com/javadoc/com/codename1/ui/Form.html[Form] 
named `hi`. 

这在大多数情况下工作得相当好,并且在HTML中看起来很棒,因为对类的每个引用都直接导致其JavaDoc使得引用/引导过程更加简单.

但是,当我们生成PDF时,我们最终会在某些页面上显示这样的内容:

通常情况下,我不会介意前一页中的大量脚注甚至重复.但是,在这种情况下,Container的链接出现3次.

我可以删除一些链接,但我不愿意,因为它们在网络版本上有很多意义.因为我也不知道分页会落在哪里,所以我宁愿不自己做.

这看起来像某个地方的错误,如果链接相同,链接的脚注应该只生成一次.

我可以删除文档中的所有链接脚注,如果这是要支付的价格,虽然我宁愿能够根据具体情况这样做,所以一些链接仍然可以打印

我正在使用Spring Rest Docs生成文档.我想做一些像Bootstrap的Togglable标签.

Spring文档使用了可切换的标签,但我不知道该怎么做.这是一个例子(MockMvc/REST Assured):http://docs.spring.io/spring-restdocs/docs/1.1.0.RELEASE/reference/html5/#documenting-your-api 感谢您的帮助.

参考样式链接非常有用,因为我可以通过名称来引用链接.例如,在Markdown我习惯做类似的事情:

The [Web site][tag-web-site] references...blah.

[tag-web-site]: https://web-site-url.tld

...它将根据tag-web-site参考创建一个链接.

有什么办法可以在AsciiDoc中模仿这个功能吗？我试过但到目前为止我找不到任何东西.

我想将Asciidoc转换为LaTeX，然后使用包含LaTeX模块的现有工具链将生成的文档进一步转换为最终格式。根据他们的文档，Asciidoc的本机LaTeX转换是“实验性的”，对我也不起作用。Asciidoc支持另一个工具链，该工具链首先转换为Docbook，然后使用dblatex对其进行进一步转换。但是，它的LaTeX输出中包含很多格式，这与我的工具链的格式冲突。

有什么方法可以将Asciidoc转换为LaTex，使内容包含在生成的文档中，但没有任何确切的格式规则（请注意文档中明确指定的格式）。我不希望LaTeX结果包含有关字体，页面布局等的任何信息，因为对于那些我已经有了工具链。

我正在构建我的 asciidoc 模板来管理我的开发文档。因此，我希望能够将现有的 ASCII 文档链接到主/或包含图像和其他资源的新文档中。为了链接文档，我使用include关键字，该关键字可以将文档引用到新文档中。

问题

我的问题是，包含/引用文档的图像未显示。我知道图像的路径分辨率从主文档开始，与包含/引用的文档图像的路径不匹配。所包含文档中的图像路径是正确的。仅生成包含的文档时会显示图像。有没有人有好的解决方案来解决这个问题？

包含图像的无效文档示例

1. 文档的目录结构。

main.adoc 包括包含图像的 Risikoanalysis_v2.adoc

• ./main.adoc
• ./Risikoanalysisn/Risikoanalysis_v2.adoc
• ./Risikoanalysisn/Risikodiagramm_1_v2.png
• ./Risikoanalysisn/Risikodiagramm_2_v2.png

2.main.adoc文件的内容

== Content 1

ratatata

include::./Risikoanalysen/Risikoanalyse_v2.adoc[]

3. Risikoanalysis_v2.adoc 的内容

= Risikoanalyse 
Inhaltsverzeichnis
:doctype: book
:toc: left
:toclevels: 4
:sectnums:

:version: Version 2.0, 03.03.2019
{version}

<<<
== Risiken
bachelor party

image::Risikodiagramm_1_v2.png[Risikodiagramm,300,align="center"]       // image that is not resolved

<<<
== preventive Gegenmassnahmen
rooftop party

image::Risikodiagramm_2_v2.png[Risikodiagramm,300,align="center"]       // image that is not resolved

4. 生成文档的命令

• asciidoctor main.doc*
• asciidoctor-pdf main.doc