Skip to content

Latest commit

 

History

History
82 lines (51 loc) · 4.82 KB

authoring.adoc

File metadata and controls

82 lines (51 loc) · 4.82 KB
Raw

Asciidoc authoring for RISC-V contributors

As a contributor to RISC-V, your contributions will likely be in one of the two following categories:

  • adding content to an existing specification.

  • creating an entirely new specification.

In either case, please feel free to examine the AsciiDoc source files for this example.pdf and adapt the markup for your use.

About Asciidoctor

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

There are three major Asciidoctor toolchains:

  • Ruby, which is well-established and which we are using.

  • Antora, which is relatively new and which uses NPM.

  • Python-based, which is legacy and in maintenance mode.

RISC-V AsciiDoc authoring assets

Please view the readme in the docs-templates repo for information on automated build processes.

The above mentioned repo also contains assets (fonts, styles, directory structure, and themes) that you need for RISC-V specifications, along with a document that takes you through a local install process that supports all of the needed 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 HTMl5 output using the following command:

asciidoctor book_header.adoc

Simply writing

To begin authoring in AsciiDoc, all you need is a text editor. Text editors that support AsciiDoc authoring lists editors that support authoring in AsciiDoc.

A quick reference for AsciiDoc markup: https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/. Most of the markup that you will need is simple, and will have a familiar feel to people who have used git-flavored Markdown. For RISC-V specifications, it is the procedures for [graphics] that add complexity.

The AsciiDoc Writers Guide contains details about AsciiDoc markup. For pdf generation, you can find details at asciidoctor-pdf.

Text editors that support AsciiDoc authoring

I have not yet encountered a true wysiwyg editor for asciidoc. However, there are live preview options listed in the Asciidoctor documentation. You might want to use your favorite text editor, or perhaps switch to one that has good asciidoc linting.

The following list contains links to resources for text editor/IDE support of asciidoc:

We received a request for information on ghostwriter and found that while it does support Markdown, it does not at this time support AsciiDoc.

An asciidoc primer and more

Much of what you need to know about the asciidoc toolchain that we are using, including install procedures, is online in the

Here are a few additional, useful links:

Note

The best linter for asciidoc is available for Sublime Text, and linters are available for other popular text editors as listed above.

Build often

As soon as you have installed asciidoctor on your computer, you have the ability to check that each individual file builds in html by simply running asciidoctor filename.adoc on any file. You can also check that the book or report on which you are working builds in html by running asciidoctor bookname.adoc or asciidoctor reportname.adoc on the book or report header. The strings filename, bookname, and reportname all should be replaced with the actual names you are using.

Asciidoctor has fairly good error messages and usually lets you know the file and row number where the build first breaks.