Publications Development using the GitLab® and AsciiDoc® Toolchain

8. Using AsciiDoc Markup Language

Imagine if writing documentation was as simple as writing an email.

It can be.

That’s the idea behind lightweight markup languages such as AsciiDoc. They offer a plain-text syntax, embellished with subtle, yet intuitive markup, that’s designed for humans to read, write, and edit in raw form. The natural feel of the syntax keeps you focused on the content. Best of all, the plain text can quickly and easily be translated into output formats such as HTML5 and PDF.

Source: Asciidoctor web site, https://asciidoctor.org/docs/what-is-asciidoc/

In this chapter we introduce step-by-step examples of AsciiDoc markup language as a tutorial. We use the theme of “Tea & Coffee” and provide examples of each of the styles used to develop The Open Group Standards in the AsciiDoc markup language.

Additional guidance on The Open Group styles for AsciiDoc markup language is available in Appendix B.

8.1. Task 1: A Cup of Tea

Guidance

For main (chapter) headings, always use Heading 1 (===)
Then use Heading 2 (====), Heading 3 (=====), Heading 4 (======), and Unnumbered Heading (*text*)

To format the text, use *bold* or _italics_

To create a list use:
* Bullet points
or
. A numbered list

The Task: A Cup of Tea

The text below describes how to make a cup of tea. Follow the steps to present these instructions using the AsciiDoc markup language.

A Cup of Tea
You will need a kettle, a cup, a teabag, a teaspoon, milk, and sugar.
First of all, fill the kettle with enough cold water and switch it on to boil the water. Put a teabag into the cup. Add the hot water to the cup as soon as the kettle boils. Add milk as required. Add sugar or sweeteners as required. Use the teaspoon to stir and remove the teabag. Alternatively, lemon juice can be used instead of milk.

Create an unnumbered heading as a title for the task.
Put the items needed into a bullet list, putting each individual item in bold.
Put the method required into a numerical list.
Put the final sentence into italics.

In AsciiDoc Markup Language:

*A Cup of Tea*

You will need the following items:
* *Kettle*
* *Cup*
* *Teabag*
* *Teaspoon*
* *Milk*
* *Sugar*

. First of all, fill the kettle with cold water and switch it on to boil the water.
. Put a teabag into the cup.
. Add the hot water to the cup as soon as the kettle boils.
. Add milk as required.
. Add sugar or sweeteners as required.
. Use the teaspoon to stir and remove the teabag.

_Alternatively, lemon juice can be used instead of milk._

The Output:

A Cup of Tea

You will need the following items:

Kettle
Cup
Teabag
Teaspoon
Milk
Sugar
1. First of all, fill the kettle with cold water and switch it on to boil the water.
2. Put a teabag into the cup.
3. Add the hot water to the cup as soon as the kettle boils.
4. Add milk as required.
5. Add sugar or sweeteners as required.
6. Use the teaspoon to stir and remove the teabag.

Alternatively, lemon juice can be used instead of milk.

8.2. Task 2: Coffee Break

But not everybody likes tea; many people prefer coffee. Some would even choose herbal tea or a hot chocolate instead. Making drinks for the office staff can be a challenge.

Guidance

For tables, the %header option makes the first row of the table into the header row. The number of columns is set by cols=n*, so three columns would be cols=3*. Using .Title sets the Table Caption.

[%header, cols=3*]
.Table Caption
|===
| Table Column Heading | Table Column Heading | Table Column Heading
| Table text
| Table text
| Table text
|===

The Task: Coffee Break

Design a table to show preferences for hot drinks in the office.

The table should show names, type of hot drink, and preferences regarding milk or lemon, sugar or sweeteners, etc.

These are the office staff:

Peter prefers tea, with milk and no sugar
Joe prefers coffee, black with two sugars
Hayley prefers coffee, white with one sweetener
Sam prefers herbal tea – just add hot water

Give your table a suitable caption.

In AsciiDoc Markup Language:

[%header, cols=3*]
.Office Staff - Hot Drinks
|===
| Name | Hot Drink | Milk/Sugar?
| Peter
| Tea
| No Sugar
| Joe
| Coffee
| No Milk, Two Sugars
| Hayley
| Coffee
| Milk, One Sweetener
| Sam
| Herbal Tea
| No Milk, No Sugar
|===

The Output:

Table 1. Office Staff – Hot Drinks
Name	Hot Drink	Milk/Sugar?
Peter	Tea	No Sugar
Joe	Coffee	No Milk, Two Sugars
Hayley	Coffee	Milk, One Sweetener
Sam	Herbal Tea	No Milk, No Sugar

8.3. Task 3: Staff Reminder

A member of the office staff is having trouble remembering who has what to drink. They need to be redirected to the list.

Guidance

For cross-referencing, an anchor to the reference must be created or identified. Use the inline xref macro as a way to create a cross-reference.

An anchor has the format [[anchor-name]].
Task 1 has the anchor [[Task-Cup-of-Tea]] on the line above it.
To cross-reference back to Task 1, reference with the format xref:Task-Cup-of-Tea[].

The Task: Staff Reminder

To help staff remember who drinks what, add a cross-reference to the table of staff preferences at the end of the memo.

Memo: A staff rota is in place to make hot drinks. As a reminder of what everyone drinks, please refer to: (add cross-reference here)

In AsciiDoc Markup Language:

Memo: A staff rota is in place to make hot drinks. As a reminder of what everyone drinks, please refer to: xref:Tbl-Staff-Drinks[]

The Output:

Memo: A staff rota is in place to make hot drinks. As a reminder of what everyone drinks, please refer to: Table 1

8.4. Task 4: Put Up a Poster

Guidance

Once imported into the images file, a figure can be incorporated into a document. Here we see an anchor for cross-referencing, with the .Caption Text and the image reference:

[[Anchor Name, beginning with fig-]]
.Figure caption
image::images/sample-figure.png[width, height, float="left/right", align="center"]

In AsciiDoc Markup Language:

[[fig-Making-Tea-Flowchart]]
.Flowchart: Making a Cup of Tea
image::images/Making-a-Cup-of-Tea.png[200,200, align="center"]

The Output:

Figure 54. Flowchart: Making a Cup of Tea

The Task: Put Up a Poster

In the images folder there is a poster asking new colleagues what they would like to drink. Incorporate this image, add an anchor, and give the poster a suitable caption.

In AsciiDoc Markup Language:

[[fig-what-drink]]
.Poster: What Would you Like to Drink?
image::images/What_Would_You_Like_To_Drink.png[300,300, align="center"]

The Output:

Figure 55. Poster: What Would you Like to Drink?

8.5. Task 5: Housekeeping

With all of these hot drinks being made, there are a number of issues arising in the office kitchen area. Some housekeeping rules are needed.

Guidance

A note block can be added as:

NOTE: This is a simple note block.

or:

[NOTE]
====
A note block can contain complex content.
. A list:
- One
- Two
- Three

Another paragraph.
====

Speech marks (curly quotes) are shown like this:

This is an example of "`double curly quotes`".

The Task: Housekeeping

Use a note block and speech marks to make a polite request to staff to return their used cups to the office area and be responsible for washing up and tidying away their own cup.

Using AsciiDoc Markup Language:

[NOTE]
 ====
 A Polite Request:
"`Please would you return, wash, and tidy away your cup ready for the next round of drinks.
Thank you.`"
====

The Output:

A Polite Request: “Please would you return, wash, and tidy away your cup ready for the next round of drinks. Thank you.”

8.6. Task 6: Charity Event

There’s no easier way to raise money than gathering everybody together for a cup of tea and a biscuit, or even a slice of cake.

Guidance

To present a quotation:

[quote, Name/Role of Person, Date]
The quotation itself.

To add a website link:

https://website.com[visible name of website here]

The Task: Charity Event

Set up your own version of this template, ready to fill in the details in order to advertise your office charity event.

In AsciiDoc Markup Language:

*Charity Fundraising Event - Title*

Aim - to raise money for _Name of Charity_*

[[fig-biscuits]]
.Bring a Biscuit
image::images/Biscuits.png[200, 300]

Donate a packet of your favorite style of biscuit as a contribution to this charity event, and put your money in the pot to buy a drink and a biscuit.

Here is a quote from someone who knows how much your donation can make a difference:

[quote, Charity Representative, Date]
Meaningful and heartfelt words to highlight the impact of support from the charity.

To find out more about the work of this charity, please go to: https://website.com[Name of Charity]

The Output:

Charity Fundraising Event - Title

Aim – to raise money for Name of Charity

Figure 56. Bring a Biscuit

Donate a packet of your favorite biscuits as a contribution to this charity appeal, and put your money in the pot to buy a drink and a biscuit.

Here is a quote from someone who knows how much your donation will help:

Meaningful and heartfelt words to highlight the impact of support from the charity.

— Charity Representative
Date

To find out more about the work of this charity, please refer to: Name of Charity

8.7. Task 7: Shopping List

Guidance:

Terms can be indexed as follows:

Selecting the word to be indexed as it appears in the text, this:
```
Coffee ((breaks)) are important.
```
will render like this:

Coffee breaks are important.

Identifying a word without revealing the index term itself within the text, this:
```
Coffee (((coffee))) breaks are important.
```
will render like this:

Coffee breaks are important.

The Task: Shopping List

It’s your turn to go shopping for the tea, coffee, kitchen equipment, and any treats for staff next week. From the conversation below, identify the items needed on the shopping list. All of the items on the list should be in lower-case.

Mark: "`We're nearly out of coffee, but I really don't like this instant stuff.`"
Luca: "`As long as there's biscuits, I don't mind what I drink!`"
Mark: "`We must remember Katya's birthday next week - Tuesday, I think.`"
Luca: "`Teaspoons! Where do they all go?`"
Ana: "`Is there any milk left; I only need a drop?`"

In AsciiDoc Markup Language:

Mark: "`We're nearly out of coffee(((instant coffee))), but I really don't like this instant stuff.`"
Luca: "`As long as there's ((biscuits)), I don't mind what I drink!`"
Mark: "`We must remember Katya's birthday (((cake))) next week - Tuesday, I think.`"
Luca: "`Teaspoons!(((teaspoons))) Where do they all go?`"
Ana: "`Is there any ((milk)) left; I only need a drop?`"

The Output:

biscuits
cake
instant coffee
milk
teaspoons

8.8. Task 8: Birthday Bonus

Guidance

To add a footnote, perhaps for a term that needs a definition/further clarification:

termfootnote:[For a definition of "`term`", please refer to: <https://www.website@link>]

Creating a variable width table, and including a list (add an a) inside the contents of a column:

[%header, cols="3,5a"]
.Table Caption
|===
| Heading 1| Heading 2
| Table text
| Table text:

* bullet list item
* bullet list item
* bullet list item
|===

The Task: Birthday Bonus

It is company policy for staff to be given the day off on their birthday. And of course, cake will be required! Design a table to show the dates that staff birthdays occur. Add a footnote to refer staff to the Staff Handbook in case their birthday falls on the weekend.

The birthdays are as follows:

Ashley: June 23rd
Ben: January 25th
Priya: March 8th
Thomas: June 4th

In AsciiDoc Markup Language:

[%header, cols="3,5a"]
.Staff Birthdays
|===
| Monthfootnote:[If your birthday falls on the weekend, please refer to the Staff Handbook:<https://staffhandbook.com>]| Name and Date
| January
| We have:

* Ben (25th)
|March
|We have:

* Priya (8th)
|June
| We have:

* Thomas (4th)
* Ashley (23rd)
|===

The Output:

Table 2. Staff Birthdays
Month^[1]	Name and Date
January	We have: Ben (25th)
March	We have: Priya (8th)
June	We have: Thomas (4th) Ashley (23rd)

1. If your birthday falls on the weekend, please refer to the Staff Handbook:https://staffhandbook.com