Asciidoc cheatsheet for GitHub

Introduction

These are the pages and the toolchain used to generate the GCBASIC Help system.

The source files, in ADOC format, are here: https://github.com/GreatCowBASIC/Help/tree/main/source

For the online operation Help, see here: http://gcbasic.sourceforge.net/help

For the daily build, see here: http://gcbasic.sourceforge.net/help/output/

This is a simple cheat sheet for editors of the GCBASIC Help source files.

GitHub limitations

This cheatsheet contains small part of Asciidoc markup which works and looks fine on GitHub.  There is also full cheatsheet, but for now its main use is to show bugs, design issues, GitHub limitations and other differences from how Asciidoc cheatsheet should really looks like.

GCBASIC Help

The format is pre-determined.  Meaning the layout and the style sheets are already mandated, please refer to existing Help pages as a reference.  These notes are to enable the casual editor insights into some of the tricks when editing Asciidoc’s.

To add an example hard space, use the following:

Cheat Sheet

This is an example of how to show user code. Four dashes, then code indented by two tabs, terminated by four dashes.

An example of showing program code

Progrom code is marked with backticks or by explicit declaration of a code block.

'Monospace or code'

    ----

    GLCDCLS

    ----

An example of Headlines

Headings are marked with leading equal signs (=):

== Heading 1 (<h1>)

==== Heading 2 (<h2>)

====== Heading 3 (<h3>)

======== Heading 4 (<h4>)

========== Heading 5 (<h5>)

============ Heading 6 (<h6>)

An example of links

Hyperlinks favor the link first, followed by the word or phrase used to "disguise" the link as text.

This is a http://example.com [ hyperlink ] that leads to the example.com site.

This is a https://example.com [ link,role=external,window=_blank ] with the target="_blank" attribute set.

An example of bold

*BOLD*

An example of a hard space

&#160;&#160;

Note	It is best practice to always add a hard space at the end of each sentence in a paragraph.

To add a table, using the following:

An example table

[cols="3,4,4", options="header,autowidth"]
|===
|Constant
|Purpose
|Default

|`GLCD_WIDTH`
|The width parameter of the GLCD
|Set automatically

|`GLCD_HEIGHT`
|The height parameter of the GLCD
|Set automatically

|`GLCDFontWidth`
|Specifies the font width of the GCBASIC font set.
|6
|===

Will dispay as:

Constant	Purpose	Default
GLCD_WIDTH	The width parameter of the GLCD	Set automatically
GLCD_HEIGHT	The height parameter of the GLCD	Set automatically
GLCDFontWidth	Specifies the font width of the GCBASIC font set.	6

To add an empty line, use the following:

An example empty line

{empty} +

Lots more

AsciiDoc also features internal links so you can link from one section to another, a standard for document headers, automatic table of content generation, the ability to include other documents within another, and much much more.

But best of all, AsciiDoc is actually standardized. AsciiDoc was designed from the start with a standard definition, so the tool or website that claims to parse AsciiDoc actually does parse all valid AsciiDoc, because there is only one valid AsciiDoc.

AsciiDoc to anything

The point of writing in AsciiDoc is to ensure predictability and consistency when text is parsed.

There are several tools to help you transform AsciiDoc to another format. A popular command is Asciidoctor, which you can install using your package manager. For instance, on Fedora, CentOS, or RHEL:

$ sudo dnf install asciidoctor

On Debian-based systems:

$ sudo apt install asciidoctor

Alternately, you can install it on any OS with Ruby:

$ gem install asciidoctor

Here’s a simple example of an AsciiDoc document, which you can create using any text editor or even a word processor (like LibreOffice) as long as you save the file as plain text. Most applications expect a plain text document to use the extension .txt, and while it’s a convention use the extension .adoc for AsciiDoc, it’s not necessary. Asciidoctor doesn’t require any special extension.

    = This is my example document

    It's not written in _Markdown_, nor _reStructured Text_.
    This is *AsciiDoc*.

    It can be transformed into nearly any format using the tool `Asciidoctor` and other similar parsers.
    Try it for yourself!

To transform an AsciiDoc document to HTML, run asciidoctor:

$ asciidoctor example.adoc

The file example.adoc is transformed into HTML5 by default, but you can use different backends to gain access to more formats.

From AsciiDoc to XML

Using Docbook backend, because it transforms my AsciiDoc to Docbook XML, allowing me to use my existing Docbook toolchain (custom Makefiles, Apache FOP, xsltproc, xmlto, and so on) to complete my work:

$ asciidoctor --backend docbook5 example.adoc

This outputs Docbook XML. The final two built-in backends are xhtml5 and manpage.

From AsciiDoc to EPUB

If you want to turn your writing into an ebook, you can install the EPUB3 backend:

$ gem install asciidoctor-epub3

Transform your AsciiDoc into EPUB

$ asciidoctor-epub3 example.adoc

From AsciiDoc to PDF

You can transform AsciiDoc directly to PDF, too:

    $ gem install asciidoctor-pdf
    $ asciidoctor-pdf example.adoc

Why AsciiDoc

AsciiDoc is excellent for technical writers and writers who have precise requirements for how they want text to be organized and parsed. It is a clear and strictly defined markup format that eliminates the confusion of competing formats, and it transforms to all the major formats. AsciiDoc is admittedly more verbose and possibly less intuitive than other formats, but it’s still just plain text so you can author on anything, and Asciidoctor makes processing easy. Next time you write a document for any purpose, consider trying AsciiDoc.

Extracts from (Seth Kenlon, CC BY-SA 4.0)