diff options
Diffstat (limited to 'documentation/content/pt-br/books/fdp-primer/asciidoctor-primer/_index.adoc')
| -rw-r--r-- | documentation/content/pt-br/books/fdp-primer/asciidoctor-primer/_index.adoc | 143 |
1 files changed, 128 insertions, 15 deletions
diff --git a/documentation/content/pt-br/books/fdp-primer/asciidoctor-primer/_index.adoc b/documentation/content/pt-br/books/fdp-primer/asciidoctor-primer/_index.adoc index df89fb146b..501dc0608c 100644 --- a/documentation/content/pt-br/books/fdp-primer/asciidoctor-primer/_index.adoc +++ b/documentation/content/pt-br/books/fdp-primer/asciidoctor-primer/_index.adoc @@ -1,16 +1,17 @@ --- -description: 'Uma breve introdução ao AsciiDoctor' +description: 'Uma breve introdução ao Asciidoctor' next: books/fdp-primer/rosetta -path: /books/fdp-primer/ +params: + path: /books/fdp-primer/asciidoctor-primer/ prev: books/fdp-primer/doc-build showBookMenu: 'true' -tags: ["AsciiDoc", "AsciiDoctor", "Primer", "Introduction", "Guide"] -title: 'Capítulo 6. Primer AsciiDoctor' +tags: ["AsciiDoc", "Asciidoctor", "Primer", "Introduction", "Guide"] +title: 'Capítulo 6. Primer Asciidoctor' weight: 7 --- [[asciidoctor-primer]] -= Primer AsciiDoctor += Primer Asciidoctor :doctype: book :toc: macro :toclevels: 1 @@ -47,7 +48,7 @@ toc::[] include::../../../../../shared/asciidoctor.adoc[] endif::[] -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 link:https://docs.asciidoctor.org/home/[documentação do Asciidoctor]. Alguns exemplos usados neste capítulo foram retirados da link:https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference[Referência rápida de sintaxe AsciiDoc]. +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 link:https://docs.asciidoctor.org/home/[documentação do Asciidoctor]. Alguns exemplos usados neste capítulo foram retirados da link:https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference[Referência rápida de sintaxe AsciiDoc]. [[asciidoctor-primer-overview]] == Visão geral @@ -83,7 +84,7 @@ Para remover */tmp/foo*, utilize o man:rm[1]. [[asciidoctor-headings]] == 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 (`=`). +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`. @@ -112,9 +113,9 @@ A sintaxe a seguir não está correta. .... = Título do Documento -== Nível 2 +== Nível 1 -==== Nível 4 +==== Nível 3 .... ==== @@ -136,7 +137,7 @@ E este é o segundo parágrafo. [[asciidoctor-lists]] == 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 link:https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/#lists[Referência Rápida da Sintaxe AsciiDoc]. +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 link:https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/#lists[Referência Rápida da Sintaxe AsciiDoc]. [[asciidoctor-ordered-lists]] === Listas ordenadas @@ -194,13 +195,13 @@ link:https://www.FreeBSD.org[FreeBSD] [NOTE] ==== -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. +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. ==== [[asciidoctor-links-internal]] -=== Link interno +=== Links para outro livro ou artigo -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. +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 [.filename]#urls.adoc# da pasta [.filename]#~/doc/shared#. + @@ -208,7 +209,7 @@ Para apontar para outro livro ou artigo, as variáveis AsciiDoctor devem ser usa \include::shared/{lang}/urls.adoc[] .... + -. Em seguida, crie um link usando a variável AsciiDoctor para o artigo `ipsec-must`. +. Em seguida, crie um link usando a variável Asciidoctor para o artigo `ipsec-must`. + .... extref:{ipsec-must}[IPSec-Must article] @@ -218,7 +219,119 @@ E isso seria processado como. + extref:{ipsec-must}[IPSec-Must article] +[NOTE] +==== +A macro `extref` é definida como uma extensão. Ela é projetada para renderizar o link correto entre as diferentes saídas +==== + +=== 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, Este link] +.... +E isso seria renderizado como + +crossref:doc-build[documentation-makefile, Este link] + +[NOTE] +==== +A macro `crossref` é definida como uma extensão. Ela é projetada para renderizar o link correto entre as diferentes saídas +==== + +[NOTE] +==== +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 +==== + +[WARNING] +==== +Não use nem a macro `xref` nem seu atalho `<<` `>>`. Eles não funcionam bem em todos os formatos de saída. +==== + +[[asciidoctor-images-icons]] +== 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. + +[[asciidoctor-images]] +=== 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: + +* [.filename]#~/website/static/images/# para o website. +* [.filename]#~/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 [.filename]#~/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 extref:{freebsd-releng}[Engenharia de Releases do FreeBSD]. + +[source, asciidoc] +.... += Engenharia de Release do FreeBSD +:doctype: article + +[...] + +:images-path: articles/freebsd-releng/ <1> + +ifdef::env-beastie[] +ifdef::backend-html5[] + +[...] + +:imagesdir: ../../../images/{images-path} <2> +endif::[] + +[...] + +.... + +<.> Faz referência ao caminho dentro da pasta [.filename]#/static/images#. +<.> Faz 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] +.... + +[TIP] +==== +Para melhorar a acessibilidade, é obrigatório adicionar texto descritivo a cada imagem. +==== + +[[asciidoctor-icons]] +=== Í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 link:https://fontawesome.com/v4/icons/[Font Awesome] pode ser adicionado. + +Este é um exemplo de como usar o ícone `envelope`: + +.... +icon:envelope[link=mailto:test@example.com, title="contact"] +.... + +[TIP] +==== +Para melhorar a acessibilidade do site, o atributo `title` é obrigatório. +==== + [[asciidoctor-conclusion]] == 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). +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). |