Capítulo 6. Primer AsciiDoctor

A maioria das documentações do FDP é escrita em AsciiDoc. Este capítulo explica o que isso significa, como ler e entender o código da documentação e as técnicas usadas. Para obter uma referência completa dos recursos do AsciiDoctor, consulte a documentação do Asciidoctor. Alguns exemplos usados neste capítulo foram retirados da Referência rápida de sintaxe AsciiDoc.

6.1. Visão geral

Nos primórdios da era computacional, o texto eletrônico era simples. Havia poucos conjuntos de caracteres como ASCII ou EBCDIC, e apenas isso. Texto era texto, e o que você lia era realmente o texto que você tinha. Sem frescuras, sem formatação, sem inteligência.

Inevitavelmente, isso não era suficiente. Quando o texto está em um formato utilizável por computadores, espera-se que eles possam usá-lo e manipulá-lo de maneira inteligente. Os autores querem indicar que certas frases devem ser enfatizadas, adicionadas a um glossário ou transformadas em hiperlinks. Os nomes dos arquivos podem ser apresentados em uma fonte de estilo "typewriter" para exibição na tela do computador, ou como "itálico" quando impressos, ou qualquer outra opção dentre uma infinidade de opções para apresentação.

Esperava-se que a Inteligência Artificial (IA) facilitasse isso. O computador leria o documento e identificaria automaticamente frases-chave, nomes de arquivos, textos que o leitor deveria digitar, exemplos e outros tipos. Infelizmente, na vida real não foi dessa forma, e os computadores ainda precisam de assistência antes que possam processar o texto de maneira significativa.

Mais precisamente, eles precisam de ajuda para identificar o que é o quê. Considere este texto:

Para remover /tmp/foo, utilize o rm(1).

% rm /tmp/foo

É fácil identificar quais partes são nomes de arquivos, quais são comandos a serem digitados, quais partes são referências a páginas de manual e assim por diante. Mas o computador que processa o documento não consegue. Para isso, precisamos utilizar markup.

O exemplo anterior é representado neste documento da seguinte forma:

Para remover */tmp/foo*, utilize o man:rm[1].

[source,shell]
----
% rm /tmp/foo
----

6.2. Cabeçalhos

AsciiDoctor suporta seis níveis de cabeçalhos. Se o tipo de documento for artigo, apenas um nível 0 (=) pode ser usado. Se o tipo de documento for livro, pode haver vários títulos de nível 0 (=).

Estes são exemplos de cabeçalhos em um artigo.

= Título do Documento (Nível 0)

== Título da Seção de Nível 1

=== Título da Seção de Nível 2

==== Título da Seção de Nível 3

===== Título da Seção de Nível 4

====== Título da Seção de Nível 5

== Outro Título de Seção de Nível 1

Os níveis de seção não podem ser ignorados ao aninhar seções.

A sintaxe a seguir não está correta.

= Título do Documento

== Nível 2

==== Nível 4

6.3. Parágrafos

Os parágrafos não precisam de marcação especial no AsciiDoc. Um parágrafo é definido por uma ou mais linhas consecutivas de texto. Para criar um novo parágrafo, deixe uma linha em branco.

Por exemplo, este é um título com dois parágrafos.

= Este é o título

Este é o primeiro parágrafo. Este também é o primeiro parágrafo.

E este é o segundo parágrafo.

6.4. Listas

AsciiDoctor suporta alguns tipos de listas, as mais comuns são ordenadas e` não ordenadas`. Para obter mais informações sobre listas, consulte o Referência Rápida da Sintaxe AsciiDoc.

6.4.1. Listas ordenadas

Para criar uma lista ordenada, use o caractere ..

Por exemplo, esta é uma lista ordenada.

. Primeiro item
. Segundo item
.. Sub-segundo item
. Terceiro item

E isso seria processado como.

  1. Primeiro item

  2. Segundo item

    1. Sub-segundo item

  3. Terceiro item

6.4.2. Listas não ordenadas

Para criar uma lista não ordenada, use o caractere *.

Por exemplo, esta é uma lista não ordenada.

* Primeiro item
* Segundo item
** Sub-segundo item
* Terceiro item

E isso seria processado como.

  • Primeiro item

  • Segundo item

    • Sub-segundo item

  • Terceiro item

Para apontar para outro site, a macro link deve ser usada.

link:https://www.FreeBSD.org[FreeBSD]

Como a documentação do AsciiDoctor descreve, a macro link não é necessária quando o link começa com um esquema de URL como https. No entanto, é uma boa prática fazer o uso assim para garantir que o AsciiDoctor renderize o link corretamente, especialmente em idiomas não latinos como o Japonês.

Para apontar para outro livro ou artigo, as variáveis AsciiDoctor devem ser usadas. Por exemplo, se estamos no artigo cups e queremos apontar para ipsec-must, esses passos devem ser usados.

  1. Inclua o arquivo urls.adoc da pasta ~/doc/shared.

    include::shared/{lang}/urls.adoc[]
  2. Em seguida, crie um link usando a variável AsciiDoctor para o artigo ipsec-must.

    extref:{ipsec-must}[IPSec-Must article]

    E isso seria processado como.

6.6. Conclusão

Esta é a conclusão deste primer do AsciiDoctor. Por razões de espaço e complexidade, várias assuntos não foram abordadas em profundidade (ou completamente).


Última alteração em: 6 de fevereiro de 2022 por Danilo G. Baio