Capítulo 6. Primer Asciidoctor

Esta tradução pode estar desatualizada. Para ajudar com as traduções, acesse a ferramenta de traduções do FreeBSD.

Índice

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 1

==== Nível 3

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.

    IPSec-Must article

A macro extref é definida como uma extensão. Ela é projetada para renderizar o link correto entre as diferentes saídas

6.5.3. Links para o mesmo arquivo ou para outro arquivo no mesmo livro

Os livros são estruturados em diretórios diferentes para manter um layout sensato. Para criar um link de um subdiretório de um livro para outro subdiretório do mesmo livro, use a macro crossref:

crossref:doc-build[documentation-makefile]

E isso seria renderizado como

Este link

A macro crossref é definida como uma extensão. Ela é projetada para renderizar o link correto entre as diferentes saídas

Use a macro crossref para links intra-documento também. Embora possa ser inconveniente escrever o nome do documento atual, ela garante que o link correto seja renderizado entre as diferentes saídas

Não use nem a macro xref nem seu atalho << >>. Eles não funcionam bem em todos os formatos de saída.

6.6. Imagens e Ícones

Imagens e ícones desempenham um papel crucial na melhoria da experiência geral do usuário. Esses elementos visuais são estrategicamente integrados para transmitir informações, esclarecer conceitos e fornecer uma interface visualmente envolvente.

6.6.1. Imagens

As imagens ajudam a ilustrar conceitos complexos, tornando-os mais acessíveis aos usuários.

O primeiro passo será adicionar a imagem no diretório de imagens no caminho:

  • ~/website/static/images/ para o website.

  • ~/documentation/static/images/ para a documentação.

Por exemplo, para adicionar uma nova imagem ao processo de instalação do FreeBSD, a imagem será salva no caminho ~/documentation/static/images/books/handbook/bsdinstall/new-image3.png.

O próximo passo será configurar os atributos do Asciidoctor images-path e imagesdir.

Usaremos como exemplo o cabeçalho do artigo Engenharia de Releases do FreeBSD.

= Engenharia de Release do FreeBSD
:doctype: article

[...]

:images-path: articles/freebsd-releng/ (1)


[...]

:imagesdir: ../../../images/{images-path} (2)

[...]
1Faz referência ao caminho dentro da pasta /static/images.
2Faz referência ao atributo Asciidoctor.

Uma vez que a imagem esteja no caminho correto e os atributos do Asciidoctor tenham sido configurados no documento, a macro image pode ser usada.

Este é um exemplo:

image::new-image3.png[Nova etapa no processo de instalação do FreeBSD]

Para melhorar a acessibilidade, é obrigatório adicionar texto descritivo a cada imagem.

6.6.2. Ícones

Os ícones servem como símbolos intuitivos para reconhecimento e navegação rápidos.

O primeiro passo para usar ícones é adicionar a propriedade icons à seção de propriedades do Asciidoctor, no topo de cada documento.

:icons: font

Depois que a propriedade do ícone do Asciidoctor for definida, um ícone suportado pela Font Awesome pode ser adicionado.

Este é um exemplo de como usar o ícone envelope:

icon:envelope[link=mailto:test@example.com, title="contact"]

Para melhorar a acessibilidade do site, o atributo title é obrigatório.

6.7. 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: 14 de setembro de 2024 por Danilo G. Baio

Início