% rm /tmp/foo
Capítulo 6. Primer AsciiDoctor
Í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).
É 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.5. Links
6.5.1. Links externos
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 |
6.5.2. Link interno
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.
Inclua o arquivo urls.adoc da pasta ~/doc/shared.
include::shared/{lang}/urls.adoc[]
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.
Última alteração em: 6 de fevereiro de 2022 por Danilo G. Baio