Build Notes

This document is a work in progress, thus is currently incomplete and may contain inaccuracies…

1. AsciiDoc

AsciiDoc documentation can be found here.

1.1. Editing Software

1.1.1. PyCharm Community Edition

1.1.2. AsciiDocFX

Installation

AsciidocFX can be downloaded from here.

Features

Can be installed as a Portable App but can’t run from a network share in this mode.
Real-Time preview with accurate rendering of.
1. Admonitions.
2. Syntax highlighting of code blocks.
Offers functionality similar to a full-fledged WYSIWYG editor.
1. Has menu strip allowing for bold, italicize, quote, etc. of text.

Issues

Exported HTML doesn’t embed images.
Preview ignores :stylesheet: attribute.
Exported PDFs are rendered poorly and appear unprofessional.

1.1.3. Visual Studio Code

Installation

Download Visual Studio Code.
Install the AsciiDoc extension.

Features

Real-Time preview but some AsciiDoc features are not rendered.
Preview applies stylesheet from the :stylesheet: attribute.
Editor show syntax highlighting for code blocks.

Issues

Real-Time preview doesn’t render all AsciiDoc features.
1. Admonitions are missing icons.
2. Code blocks are missing syntax highlighting.

1.1.4. Atom

Installation

Download Atom
Then install the AsciiDoc Assistant package.

Issues

Preview ignores :stylesheet: attribute.

1.2. Useful AsciiDoc Stuff

1.2.1. A Standard Header

This is an example header that can be placed at the top of an AsciiDoc:

= About
Codey Martinez ; Dhante
:description: About for Xackley Studio Tech Docs
//Enable TOC. Values = auto, left, right
:toc: auto
//Name the TOC
:toc-title: Table of Contents
//Set TOC Depth
:toclevels: 5
//Enable Numbered Sections
:sectnums: |,all|
//Enable image-based icons
:icons: font
//Enable Source Code Highlighting
:source-highlighter: highlightjs
:highlightjs-theme: vs
//Set image directory
:imagesdir: ./images
//Embed images in HTML
:data-uri:
//Use `experimental` for keyboard, button, and menu macros
:experimental:

1.2.2. Applying Styles

Download style sheets from here.
Create a folder to contain your style sheets.

Reference a stylesheet in your AsciiDoc file via:

= How To
Codey Martinez ; Dhante
:stylesdir: ..\..\..\my-styles (1) (2)
:stylesheet: adoc-golo.css (3)

1	This attribute indicates where the style folder is located.
2	The attribute must appear at the top of your `AsciiDoc` file.
3	This attribute will allow you to reference a style from the `my-styles` folder.

1.2.3. Code Blocks

Code block

Asciidoc

[source,C#]
var a=5;
for (var x=1;x<a;x++)
{

}

Rendered

var a=5;
for (var x=1;x<a;x++)
{

}

1.2.4. Color Text

To add color to text
```
Text color can be set when formatted [red]#this way#.
```
Example 1. Results

Text color can be set when formatted this way.

1.2.5. Highlight Text

To highlight text:
```
Text can be #highlighted# when enclosed between '#'s.
```
Example 2. Results

Text can be highlighted when enclosed between '#'s.

1.2.6. Button Macros

Set the :experimental: attribute within the document’s header in order to enable UI macros!

To clearly indicate to a reader of your documentation when a button should be pressed, compose AsciiDoc like the following:
```
Press the btn:[OK] button when you are finished.

Select a file in the file navigator and click btn:[Open].
```
Example 3. Result

Press the OK button when you are finished.

Select a file in the file navigator and click Open.

1.2.7. Keybinding Macros

Set the :experimental: attribute to enable UI macros!

To clearly indicate keyboard shortcuts, write AsciiDoc like the following:
```
Press kbd:[esc] to exit insert mode.

Use the shortcut kbd:[Ctrl+T] to open a new tab in your browser.

kbd:[Ctrl+Shift+N] will open a new incognito window.
```
Example 4. Result

Press esc to exit insert mode.

Use the shortcut Ctrl+T to open a new tab in your browser.

Ctrl+Shift+N will open a new incognito window.

1.2.8. Menu Macros

Set the :experimental: attribute to enable UI macros!

To clearly indicate menu navigation, write AsciiDoc like the following:
```
To save the file, select menu:File[Save].

Select menu:View[Zoom > Reset] to reset the zoom level to the default setting.
```
Example 5. Result

To save the file, select File Save.

Select View Zoom Reset to reset the zoom level to the default setting.

1.2.9. Admonitions List

The following AsciiDoc will create a Note admonition:
Admonition
```
.Note
NOTE: Additional information
```
Admonition with block level content
```
.Note
[NOTE]
====
Additional information
====
```
There are 5 built in admonitions:

Note

Additional information

Tip

Useful information or trick:
A document regarding creating custom admonitions can be found here.

Important

Ensure something is known

Caution

Advise the reader to act carefully (i.e., exercise care)

Warning

Inform the reader of danger, harm, or consequences that exist.

1.2.10. Horizontal Rule

This is simply one of the following:
```
---

- - -

***

* * *
```
Example 6. The rendered horizontal rules

1.2.11. Tables

A table with cell widths
Source
```
[cols="1,10"]
|===
|OS | Command

|Unix| This is a long line
|Windows| This is another long line

|===
```
Table 1. The rendered table

OS Command

Unix

This is a long line

Windows

This is another long line

Table 1. The rendered table
OS	Command
Unix	This is a long line
Windows	This is another long line

The following AsciiDoc will create a table. It also shows how to include a block level element within a cell.
Use these two characters a| as the cell separator:

.Commands
|====
| OS | Command | Description

| Unix
| ls
a|
* *-l* _Long format_
* *-a* _Show hidden files_

| Windows
| dir
a|
* */q* _file ownership_
* *-a* _Show hidden files_

|====

The rendered table
Table 2. Commands

OS Command Description
Unix

ls

-l Long format

-a Show hidden files

Windows

dir

/q file ownership

-a Show hidden files

Table 2. Commands
OS	Command	Description
Unix	ls	-l Long format -a Show hidden files
Windows	dir	/q file ownership -a Show hidden files

To make a CSV table:

,===
Artist,Track,Genre

Snoop Dogg,Gin and Juice,Hip Hop
,===

The rendered table:

Artist Track Genre

Baauer

Harlem Shake

Hip Hop

Artist	Track	Genre
Baauer	Harlem Shake	Hip Hop

To make a CSV Table from a CSV data file with this CSV data:
```
Artist,Track,Genre
Baauer,Harlem Shake,Hip Hop
```

Use this AsciiDoc

[%header,format=csv]
|===
include::../attachments/sample.csv[]
|===

The rendered table:

Artist Track Genre

Baauer

Harlem Shake

Hip Hop

Artist	Track	Genre
Baauer	Harlem Shake	Hip Hop

2. AsciiDoctor

2.1. Installation

Installation instruction can be found here.

2.1.1. StyleSheets

Documentation can be found here.

Default style sheet is here:

C:\tools\ruby31\lib\ruby\gems\3.1.0\gems\asciidoctor-2.0.17\data\stylesheets

Additional style sheets can be downloaded from here