How To Install and Use AsciiDoc in Linux System

There are many applications you can use for writing articles, notes, writing slides, making web pages, etc. you can use LaTex, HTML, XML, AsciiDoc, etc., for these purposes. Each of them has its own pros and cons. Among all of these, AsciiDoc is quite different from all others and has its own unique features. For Linux users, AsciiDoc is also available. AsciiDoc in Linux needs some special attention to learn, and to fulfill that is the goal of this post.

AsciiDoc is lightweight and way handier than other writing applications. You can put your concentration on a single point, i.e., writing content with it. It won’t distract your concentration with redundant features. To learn about AsciiDoc in great detail, stick to this post till the end. Happy learning!

AsciiDoc at a Glance

Basically, it is a writing format. You can write plenty of varieties with it. It can be a blog post, or an ebook or a book or simple articles, anything. There is an underlying text processor embedded in it that translates your content into various backends like HTML or ePub, etc.

Probably you have heard the name of Markdown. That is made upon a base of lightweight markup language. AsciiDoc belongs to the same origin and is made up of the same infrastructure. It will provide you with the extra advantages of drafting several types of content.

AsciiDoc was mainly built to be a handy substitution of DocBook. DocBook is one of the most common generatable formats of AsciiDoc. This application covers every step for you, from the rough draft to the publishing of manuscripts. We are going to discover as many aspects of AsciiDoc as we can in this post.

Why Give Preference for AsciiDoc?

There are several reasons behind choosing AsciiDoc as a priority for writing stuff. Writing is an essential part of a language. But for many of us, we are usually habituated with informal writings.

But in the case of formal or semi-formal writings, we often find it quite difficult. Which words to choose, the arrangement of them, the font family choosing, spacing between lines, spelling check, etc., disrupts our writings a lot.

As a solution to this problem, AsciiDoc pops into the scenario. To minimize the interruption and distraction for a typer, AsciiDoc is one of the best applications. You do not have to think about the styling, layout, and sometimes even the semantics. You just have to write. AsciiDoc will deal with those for you.

AsciiDoc is available in Windows, Linux as well as mac. Let’s see an example, how AsciiDoc makes the art of writing easier. The following content is a document written in AsciiDoc.

= This is AsciiDoc
Doc Writer: Ubuntu PIT

A rough estimation about https://asciidoc.org[AsciiDoc]

== First para with some points

* first point

* second point

* third point

* and so on

[source, ruby]

Admiring "How easy is this?"

Now time to see the same bunch of words written in DocBook.

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"

    "https://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">

<article lang="en">

  <articleinfo>

    <title>This is AsciiDoc</title>

    <date>2021-01-01</date>

    <author>

      <firstname>Ubuntu</firstname>

      <surname>PIT</surname>

        </author>

    <authorinitials>DW</authorinitials>

  </articleinfo>

  <simpara>

    A rough estimation about

    <ulink url="https://asciidoc.org">Sample AsciiDoc document</ulink>.

  </simpara>

  <section id="_first_section">

    <title>First Section</title>

    <itemizedlist>

      <listitem>

        <simpara>first point</simpara>

      </listitem>

      <listitem>

        <simpara>second point</simpara>

      </listitem>

<listitem>

        <simpara>third point</simpara>

      </listitem>

<listitem>

        <simpara>and so on</simpara>

      </listitem>

    </itemizedlist>

    <programlisting language="ruby"

        linenumbering="unnumbered">

      <![CDATA[Admiring "How easy is this?"]]>

    </programlisting>

  </section>

</article>

Probably I do not have to tell you anything more. You can see the convenience of AsciiDoc over anything now with your own eyes. 

Install AsciiDoc in Linux Distros

AsciiDoc requires some installments from Ruby as its pre-requisite dependency. You must have those installed on your PC before installing AsciiDoc. Assuming that you have fulfilled all the dependencies, I am going to show you the core installation only.

1. Installation in Kali Linux

There are several methods to install AsciiDoc in Kali Linux. I shall try to cover each of them individually.

a. Using aptitude

As aptitude is not pre-installed with Kali Linux, you have to install it first. Then you have to use it. After installation, update the database first.

sudo aptitude update

Then execute this:

sudo aptitude -y install asciidoc

b. Using the apt-get

Write the following command in the terminal and press enter.

sudo apt-get update

Now we are ready to install AsciiDoc. Implement the command:

sudo apt-get -y install asciidoc

c. Using the apt

Again, you have to update the apt database first.

sudo apt update

Now run this command:

sudo apt-y install asciidoc

2. Installation in Ubuntu and Debian

Installing the application in Ubuntu and Debian is quite easy. Both of the Linux distros have the same installation syntax. Just update the apt database at first.

sudo apt update

And then execute the following syntax:

sudo apt install asciidoc

3. Installing in Fedora

Fedora extras have built-in dependencies for AsciiDoc. When you boot Fedora on your PC, you will get those by default. So all you have to do is, executing the following instruction:

yum install asciidoc

How to Use AsciiDoc?

Now, we have Asciidoc installed in our Linux system. You have to have a text editor in order to use AsciiDoc. This is your place of freedom. You can choose any editor. There are dedicated editors for AsciiDoc only. You can also use them for your work.

The main advantage of AsciiDoc is that you do not have to use starting tag and ending tag for commands. You just have to make the PC understand what you are intended to do. There are some default syntaxes you need to follow. Compared to other similar types of applications, these syntaxes are way easier. Let’s see some of the most commonly used syntaxes below.

Let’s say you want to write a title for your essay. This is the most fundamental one. You have to start the title with === or — and AsciiDoc will recognize the preceding line as a title. The two different sign conventions make a difference in the level of the title. If you write any words within two asterisks, that will be bold. For instance, you have written *hello martha*. That will be shown as hello martha.

These are known as text formatting. You will find other text formattings as well. Writing any word within two underscores will make it italic. Writing _this is a very good day_ will be converted into this is a very good day. You can also find monospace and other stuff in the list. Check the official website of AsciiDoc for more. All of the syntaxes are beyond the scope of this post.

The images and hyperlinks are two very common features we often use. You just have to write “link:” and then write your desired website. The images command works pretty much in the same way. Again, there are lots of these commands. Check the official website and get a vast idea of them. These small words will make your life easier.

I Have Written A Content. How to Get the Output?

As I said earlier, AsciiDoc produces human-readable output, so you can use them directly. But we do not use text files directly, and rather we work with PDFs or HTML, etc. To get those types of output from your written file, you have to do some additional work.

One of the most common outputs we use is the HTML format. You or I often write content and want that to be in HTML format. How to get that? You have to have some processors on your PC. No, not the processors of the CPU. These are just processor software to work in combination with the AsciiDoc.

The processors convert your raw file into some intermediate file formats that are hidden from you. You do not have to think about that. You just have to fulfill the dependencies and then choose your desired output format.

So, returning to our main point, let’s say you want to get an HTML output of your file. Then all you need is the AsciiDoc tool. There are other output formats that require more processors to work. Use a2x for that toolchain. So, how to get HTML output? Look at the following syntax closely. asciidoc asciidoc.txt firefox asciidoc.html Pretty easy, isn’t it?

Now, how to get PDF output? Well, there are two processors you can use to get PDF output. Two PDF backends. One is dblatex and the other is fop. Both of them have their own positives and negatives. Choose one between them according to your necessity. You have to make a trade-off while choosing according to your work.

Wrapping Up

Writing content with HTML can solve your problem in the first place, but that is not an easy task. It is not handy and has less readability. That’s why AsciiDoc is a great choice for every writer. In Linux, workability is versatile, and you can modify AsciiDoc in accordance with your choice. Comment below anything that is vague in this post. Suggest any edits. Happy learning.