== AsciiDoc authoring for RISC-V contributors

=== About Asciidoctor

AsciiDoc is the markup language and Asciidoctor is a set of toolchains that support publishing from AsciiDoc.

Asciidoctor toolchains:

* https://github.com/asciidoctor/asciidoctor[asciidoctor], which is well-established and written in ruby.
* https://gitlab.com/antora/antora[antora], which is newer and written in javascript.
* Python-based, which is legacy and in maintenance mode.

=== RISC-V AsciiDoc authoring assets

Please view the https://github.com/riscv/docs-templates[readme] in the docs-templates repo for information about the automated build processes.

The docs-templates repo also contains assets, such as fonts, styles, directory structure, and themes that you need for RISC-V specifications, along with a https://github.com/riscv/docs-templates/commit/5c18cc9761eb3f6516975ee0c109729a4ce66b93[document] that takes you through a local install process that supports all of the required features for a local build.

Although testing your markup by building a PDF is good practice, you can catch many common errors by simply downloading Asciidoctor and building the HTML output using the following command:

[source,cmd]
----
asciidoctor book_header.adoc
----

=== Writing

To begin writing in AsciiDoc, select a text editor. Here's <<editors>>.

For quick reference, see https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/[AsciiDoc Syntax Quick Reference]. Most of the markup for the specifications is simple and should have a familiar feel to those who have used Git-flavored Markdown. For RISC-V specifications, it is the procedures for <<graphics>> that add complexity.

The https://asciidoctor.org/docs/asciidoc-writers-guide/[AsciiDoc Writers Guide] contains details about AsciiDoc markup.

Here are a few additional, useful links:

* https://asciidoctor.org/docs/asciidoc-recommended-practices/[asciidoc recommended practices]
* https://docs.asciidoctor.org/asciidoc/latest/tables/build-a-basic-table/[tables]
* https://docs.asciidoctor.org/asciidoc/latest/macros/link-macro-ref/[links]

[[editors]]
==== Text editors with AsciiDoc support

There isn't a true WYSIWYG editor for AsciiDoc. However, there are live preview options that are listed in the https://docs.asciidoctor.org/asciidoctor/latest/tooling/[Asciidoctor documentation] that can help you see what the output looks like. You can also use your favorite text editor, or perhaps switch to one that has good AsciiDoc linting.

The following list contains links to resources for text editors/IDEs support of AsciiDoc:

* Information on helpful https://docs.asciidoctor.org/asciidoctor/latest/tooling/[AsciiDoc tools that integrate with several popular IDEs]
* https://code.visualstudio.com/[vscode]
** https://marketplace.visualstudio.com/items?itemName=asciidoctor.asciidoctor-vscode[asciidoctor-vscode extension]
* https://www.vim.org/[vim] (supports asciidoc natively)
* https://www.gnu.org/software/emacs/[emacs]
** https://www.emacswiki.org/emacs/AsciiDoc[emacs Wiki Asciidoc page]
*** https://github.com/bbatsov/adoc-mode[bbatsov/adoc-mode]
* https://www.asciidocfx.com/[AsciidocFX]
* https://www.jetbrains.com/idea/[Intellij IDEs] (NOTE: IntelliJ IDEs are not free/OSS)
** https://plugins.jetbrains.com/plugin/7391-asciidoc[jetbrain asciidoc plugin]
* https://www.sublimetext.com/[Sublime Text] (NOTE: Sublime is not free)
** https://packagecontrol.io/packages/AsciiDoc[asciidoc package for Sublime Text2]
