From 447c6fc76e8d34a7fbb5ad0517d22645cedcb13a Mon Sep 17 00:00:00 2001 From: diguage Date: Thu, 9 Jun 2016 14:52:43 +0800 Subject: [PATCH 1/2] translate README into Chinese --- README_zh-CN.adoc | 301 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 301 insertions(+) create mode 100644 README_zh-CN.adoc diff --git a/README_zh-CN.adoc b/README_zh-CN.adoc new file mode 100644 index 0000000..55e060e --- /dev/null +++ b/README_zh-CN.adoc @@ -0,0 +1,301 @@ += Asciidoclet +John Ericksen +v0.1.3 +:description: This is a guide for setting up and using the Asciidoclet project. Asciidoclet is a Javadoc Doclet based on Asciidoctor that lets you write Javadoc in the AsciiDoc syntax. +:keywords: Asciidoclet, AsciiDoc, Asciidoctor, syntax, Javadoc, Doclet, reference +:page-layout: base +:language: java +ifdef::env-github,env-browser[:outfilesuffix: .adoc] +ifndef::awestruct[] +:idprefix: +:idseparator: - +:toc: +:sectanchors: +:icons: font +:source-highlighter: highlight.js +endif::awestruct[] +// Refs +:asciidoclet-src-ref: https://github.com/asciidoctor/asciidoclet +:asciidoclet-javadoc-ref: https://oss.sonatype.org/service/local/repositories/releases/archive/org/asciidoctor/asciidoclet/1.5.2/asciidoclet-1.5.2-javadoc.jar/!/index.html +:asciidoclet-release-ref: http://asciidoctor.org/news/2014/09/09/asciidoclet-1.5.0-released/ +:asciidoc-ref: http://asciidoc.org +:asciidoctor-java-ref: http://asciidoctor.org/docs/install-and-use-asciidoctor-java-integration/ +:asciidoclet-issues-ref: https://github.com/asciidoctor/asciidoclet/issues +:asciidoctor-src-ref: https://github.com/asciidoctor/asciidoctor +:asciidoctor-java-src-ref: https://github.com/asciidoctor/asciidoctor-java-integration +:discuss-ref: http://discuss.asciidoctor.org/ +:translators: D瓜哥 +ifdef::env-github[翻译： {translators}] + +{asciidoclet-src-ref}[Asciidoclet] 是一个基于 Asciidoctor 的 Javadoc Doclet，它可以让你是使用 AsciiDoc 语法来撰写 Javadoc。 + +image:http://img.shields.io/travis/asciidoctor/asciidoclet/master.svg["Build Status", link="https://travis-ci.org/asciidoctor/asciidoclet"] +image:https://img.shields.io/badge/javadoc.io-1.5.4-blue.svg[Javadoc, link=http://www.javadoc.io/doc/org.asciidoctor/asciidoclet/1.5.4] + +[[introduction]] +== 介绍 + +当你撰写为 HTML 格式的 Javadoc 输出时，传统做法是 Javadocs 会稍微混合一些 HTML 标记，随着时间的推移这将导致既不易读又难以书写。 +这也是轻量级标记语言之所以能繁荣成长的原因所在。 +AsciiDoc 跨越了易读标记和精美的渲染内容之间的鸿沟。 + +Asciidoclet 将 AsciiDoc 渲染器（通过调用 {asciidoctor-java-ref}[Asciidoctor Java integration] 库而组成的 Asciidoctor）包装成了一个简单的 Doclet，这样就可以在 Javadoc 的注释和标签中使用 AsciiDoc 格式。 + +[[example]] +== 示例 + +这是一个类的传统 Javadoc 的例子。 + +[source] +.使用传统方式撰写 Javadoc 的 Java 类 +---- +/** + *

Asciidoclet

+ * + *

Sample comments that include {@code source code}.

+ * + * 
{@code
+ * public class Asciidoclet extends Doclet {
+ *     private final Asciidoctor asciidoctor = Asciidoctor.Factory.create();
+ *
+ *     {@literal @}SuppressWarnings("UnusedDeclaration")
+ *     public static boolean start(RootDoc rootDoc) {
+ *         new Asciidoclet().render(rootDoc);
+ *         return Standard.start(rootDoc);
+ *     }
+ * }
+ * }
+ * + * @author John Ericksen + */ +public class Asciidoclet extends Doclet { +} +---- + +相同的类，但使用了 Asciidoclet。 + +[source] +.使用 Asciidoclet 撰写 Javadoc 的 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 { +} +---- + +结果就是更易读的源码和渲染后精美的 Javadocs，各得其所，堪称完美。 + +// tag::usage[] +[[usage]] +== 用法 + +带上 `org.asciidoctor.Asciidoclet` 参数来运行 `javadoc`。 +下面几个例子演示在常用的构建系统中的用法。 +通过 <> 来查看更多的支持的选项。 + +[[maven]] +=== Maven + +可以通过 `maven-javadoc-plugin` 插件来使用 Asciidoclet : + +[source,xml] +---- + + org.apache.maven.plugins + maven-javadoc-plugin + 2.9 + + 1.7 + org.asciidoctor.Asciidoclet + + org.asciidoctor + asciidoclet + ${asciidoclet.version} + + src/main/java/overview.adoc + + --base-dir ${project.basedir} + --attribute "name=${project.name}" + --attribute "version=${project.version}" + --attribute "title-link=http://example.com[${project.name} ${project.version}]" + + + +---- + +[[gradle]] +=== Gradle + +可以通过 `Javadoc` 任务来使用 Asciidoclet : + +[source,groovy] +---- +configurations { + asciidoclet +} + +dependencies { + asciidoclet 'org.asciidoctor:asciidoclet:1.+' +} + +javadoc { + options.docletpath = configurations.asciidoclet.files.asType(List) + options.doclet = 'org.asciidoctor.Asciidoclet' + options.overview = "src/main/java/overview.adoc" + options.addStringOption "-base-dir", "${projectDir}" // <1> + options.addStringOption "-attribute", // <2> + "name=${project.name}," + + "version=${project.version}," + + "title-link=http://example.com[${project.name} ${project.version}]") +} +---- +<1> 传递给 Gradle 的 javadoc 任务的选项名必须忽略掉第一个 `-`，所以，这里的 `-base-dir` 就指 `--base-dir`。 + 请看下面 <>。 +<2> Gradle 的 javadoc 任务不允许多次出现相同选项。 + 多个属性可以在一行中指定，之间使用英文半角逗号分割。 + +[[ant]] +=== Ant +// Some of us still use Ant, alright?! +可以通过 Ant 的 `javadoc` 任务的 doclet 元素来使用 Asciidoclet： + +[source,xml] +---- + + + + + + + + +---- +<1> 假设定义了指向 Asciidoclet 及其依赖的路径。举例来说，使用 http://ant.apache.org/ivy/[Ivy] 或相似产品。 + +[[doclet-options]] +=== Doclet 选项 +// tag::doclet-options[] + +--base-dir :: +设置基础目录，被 Asciidoc 用于解析在 `include::` 中的相对路径。 +这个选项应该设置成项目的根目录。 + +-a, --attribute "name[=value], ...":: +设置 http://asciidoctor.org/docs/user-manual/#attributes[文档属性^]，这些设置将用在 javadoc 注释上。 +这个参数是一个字符串，包含一个属性或者多个使用英文半角逗号分割的多个属性。 ++ +这个选项可以使用多次，例如：`-a name=foo -a version=1`。 ++ +属性使用和 Asciidoctor 命令行属性相同的语法： ++ +-- +* `name` 设置属性（使用空值） +* `name=value` 将属性设置为 `value`。出现中在 javadoc 中的 `{name}` 将会使用这个值来替换。 +* `name=value@` 除非在属性文件或者 javadoc 中设置这个属性，否则将这个属性设置为 `value`。 +* `name!` 取消设置。 +-- ++ +文档属性 `javadoc` 将会被这个 doclet 自动设置。 +当为 javadoc 和其他文档使用相同 Asciidoc 文件，它将被用于有条件的选中的内容。 +// This can be used for conditionally selecting content when using the same Asciidoc file for javadoc and other documentation. + +--attributes-file :: +从一个 Asciidoc 文件中，读取 http://asciidoctor.org/docs/user-manual/#attributes[文档属性^] 。 +这些属性将用在 javadoc 注释上。 ++ +如果 `` 是一个相对路径名称，它将假设相对于 `--base-dir` 路径。 ++ +通过 `-a`/`--attribute` 选项设置的属性比属性文件中的属性有更高的优先级。 + +-r, --require ,...:: +给 Asciidoctor 的 JRuby 运行时增加必要的 RubyGems 库，例如 `-r asciidoctor-diagram`。 ++ +这个选项可以设置一次道多次。 +也可以在一个参数中设置多个库，中间使用英文半角逗号分割。 + +--gem-path :: +为 Asciidoctor 的 JRuby 运行时 设置 `GEM_PATH`。 +这个选项只有在使用 `--require` 选项并且 `GEM_PATH` 环境变量没有设置或者需要一个不同的 `GEM_PATH` 时才需要。 + +-overview :: +标准的 `-overview` 选项，可以从 Asciidoc 文件生成概述文档。 +匹配 [x-]`*.adoc`、[x-]`*.ad`、[x-]`*.asciidoc` 或 [x-]`*.txt` 的文件都可以被 Asciidoclet 处理。 +其他文件被认为是 HTML，将由标准的 doclet 处理。 + +// end::doclet-options[] +// end::usage[] + +[[log-warning]] +=== 日志警告 + +目前，当运行 Asciidoclet 时，会输出一个类似下面的间歇良性警告消息： +// Currently there is a intermittent benign warning message that is emitted during a run of Asciidoclet stating the following: + +.... +WARN: tilt autoloading 'tilt/haml' in a non thread-safe way; explicit require 'tilt/haml' suggested. +.... + +不幸的是，直到底层库删除这个警告信息，在构建中都会输出这条消息。 + +[[additional-features]] +== 附加特性 + +查看 {asciidoclet-release-ref}[Asciidoclet 1.5.0 发布日志] 来获取更多这里没有记录的特性。 + +[[resources-and-help]] +== 资源及帮助 + +从下来链接中可以获取更多信息： + +* {asciidoclet-release-ref}[Asciidoclet 1.5.0 发布日志] +* {asciidoclet-src-ref}[Asciidoclet 源码] +* {asciidoclet-javadoc-ref}[Asciidoclet JavaDoc] +* {asciidoclet-issues-ref}[Asciidoclet Issue Tracker] +* {asciidoctor-src-ref}[Asciidoctor 源码] +* {asciidoctor-java-src-ref}[Asciidoctor Java 集成源码] + +如果你有什么问题或者想帮助开发这个项目，请加入 {discuss-ref}[Asciidoctor 讨论组]。 + +[[powered-by-asciidoclet]] +== Powered by Asciidoclet + +我们有一个 <> 页面。如果你有使用 Asciidoclet 制成的精美 JavaDoc 例子，请提交一个 Pull Request。 + +[[license]] +== 许可证 + +.... +Copyright (C) 2013-2015 John Ericksen + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +.... From d53ba40a60d0c41bc1d475de2748593a9d98fc03 Mon Sep 17 00:00:00 2001 From: diguage Date: Thu, 9 Jun 2016 19:25:04 +0800 Subject: [PATCH 2/2] add Chinese README link to README --- README.adoc | 3 +++ README_zh-CN.adoc | 5 +++++ 2 files changed, 8 insertions(+) diff --git a/README.adoc b/README.adoc index 297e0de..a55e9ac 100644 --- a/README.adoc +++ b/README.adoc @@ -27,6 +27,9 @@ endif::awestruct[] {asciidoclet-src-ref}[Asciidoclet] is a Javadoc Doclet based on Asciidoctor that lets you write Javadoc in the AsciiDoc syntax. +.Translations of the document are available in the following languages: +* link:README_zh-CN.adoc[汉语] + image:http://img.shields.io/travis/asciidoctor/asciidoclet/master.svg["Build Status", link="https://travis-ci.org/asciidoctor/asciidoclet"] image:https://img.shields.io/badge/javadoc.io-1.5.4-blue.svg[Javadoc, link=http://www.javadoc.io/doc/org.asciidoctor/asciidoclet/1.5.4] diff --git a/README_zh-CN.adoc b/README_zh-CN.adoc index 55e060e..911dbba 100644 --- a/README_zh-CN.adoc +++ b/README_zh-CN.adoc @@ -29,6 +29,11 @@ ifdef::env-github[翻译： {translators}] {asciidoclet-src-ref}[Asciidoclet] 是一个基于 Asciidoctor 的 Javadoc Doclet，它可以让你是使用 AsciiDoc 语法来撰写 Javadoc。 +.该文档有如下语言的翻译版： +* link:README.adoc[English] -- 这是原始文档。 + +TIP: 本文档是 link:README.adoc[README] 的翻译版。如果发现有什么不一致或者错误的地方，请以原文档为准。 + image:http://img.shields.io/travis/asciidoctor/asciidoclet/master.svg["Build Status", link="https://travis-ci.org/asciidoctor/asciidoclet"] image:https://img.shields.io/badge/javadoc.io-1.5.4-blue.svg[Javadoc, link=http://www.javadoc.io/doc/org.asciidoctor/asciidoclet/1.5.4]