# SOME DESCRIPTIVE TITLE # Copyright (C) YEAR The FreeBSD Project # This file is distributed under the same license as the FreeBSD Documentation package. # FIRST AUTHOR , YEAR. # #, fuzzy msgid "" msgstr "" "Project-Id-Version: FreeBSD Documentation VERSION\n" "POT-Creation-Date: 2026-08-16 15:11-0300\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language-Team: LANGUAGE \n" "Language: \n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" #. type: Yaml Front Matter Hash Value: description #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:1 #, no-wrap msgid "A brief introduction to Asciidoctor" msgstr "" #. type: Yaml Front Matter Hash Value: title #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:1 #, no-wrap msgid "Chapter 6. Asciidoctor Primer" msgstr "" #. type: Title = #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:14 #, no-wrap msgid "Asciidoctor Primer" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:54 msgid "" "Most FDP documentation is written with AsciiDoc. This chapter explains what " "that means, how to read and understand the documentation source, and the " "techniques used. To get a complete reference of the Asciidoctor " "capabilities please consult the link:https://docs.asciidoctor.org/home/" "[Asciidoctor documentation]. Some of the examples used in this chapter have " "been taken from the link:https://docs.asciidoctor.org/asciidoc/latest/syntax-" "quick-reference[AsciiDoc Syntax Quick Reference]." msgstr "" #. type: Title == #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:56 #, no-wrap msgid "Overview" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:62 msgid "" "In the original days of computers, electronic text was simple. There were a " "few character sets like ASCII or EBCDIC, but that was about it. Text was " "text, and what you saw really was what you got. No frills, no formatting, " "no intelligence." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:67 msgid "" "Inevitably, this was not enough. When text is in a machine-usable format, " "machines are expected to be able to use and manipulate it intelligently. " "Authors want to indicate that certain phrases should be emphasized, or added " "to a glossary, or made into hyperlinks. Filenames could be shown in a " "“typewriter” style font for viewing on screen, but as “italics” when " "printed, or any of a myriad of other options for presentation." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:71 msgid "" "It was once hoped that Artificial Intelligence (AI) would make this easy. " "The computer would read the document and automatically identify key phrases, " "filenames, text that the reader should type in, examples, and more. " "Unfortunately, real life has not happened quite like that, and computers " "still require assistance before they can meaningfully process text." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:74 msgid "" "More precisely, they need help identifying what is what. Consider this text:" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:76 msgid "To remove [.filename]#/tmp/foo#, use man:rm[1]." msgstr "" #. type: delimited block - 4 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:80 #, no-wrap msgid "% rm /tmp/foo\n" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:85 msgid "" "It is easy for the reader to see which parts are filenames, which are " "commands to be typed in, which parts are references to manual pages, and so " "on. But the computer processing the document cannot reliably determine " "this. For this we need markup." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:87 msgid "" "The previous example is actually represented in this document like this:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:90 #, no-wrap msgid "To remove */tmp/foo*, use man:rm[1].\n" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:95 #, no-wrap msgid "" "[source,shell]\n" "----\n" "% rm /tmp/foo\n" "----\n" msgstr "" #. type: Title == #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:98 #, no-wrap msgid "Headings" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:103 msgid "" "Asciidoctor supports six headings levels. If the document type is `article` " "only one level 0 (`=`) can be used. If the document type is `book` then " "there can be multiple level 0 (`=`) headings." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:105 msgid "This is an example of headings in an `article`." msgstr "" #. type: Title = #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:107 #, no-wrap msgid "Document Title (Level 0)" msgstr "" #. type: Title == #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:109 #, no-wrap msgid "Level 1 Section Title" msgstr "" #. type: Title === #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:111 #, no-wrap msgid "Level 2 Section Title" msgstr "" #. type: Title ==== #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:113 #, no-wrap msgid "Level 3 Section Title" msgstr "" #. type: Title ===== #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:115 #, no-wrap msgid "Level 4 Section Title" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:118 msgid "====== Level 5 Section Title" msgstr "" #. type: Title == #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:119 #, no-wrap msgid "Another Level 1 Section Title" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:125 msgid "Section levels cannot be skipped when nesting sections." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:127 msgid "The following syntax is not correct." msgstr "" #. type: Title = #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:129 #, no-wrap msgid "Document Title" msgstr "" #. type: Title == #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:131 #, no-wrap msgid "Level 1" msgstr "" #. type: Title ==== #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:133 #, no-wrap msgid "Level 3" msgstr "" #. type: Title == #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:138 #, no-wrap msgid "Paragraphs" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:143 msgid "" "Paragraphs don't require special markup in AsciiDoc. A paragraph is defined " "by one or more consecutive lines of text. To create a new paragraph leave " "one blank line." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:145 msgid "For example, this is a heading with two paragraphs." msgstr "" #. type: Title = #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:147 #, no-wrap msgid "This is the heading" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:151 msgid "This is the first paragraph. This is also the first paragraph." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:153 msgid "And this is the second paragraph." msgstr "" #. type: Title == #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:156 #, no-wrap msgid "Lists" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:160 msgid "" "Asciidoctor supports a few types of lists, the most common are `ordered` and " "`unordered`. To get more information about lists, see link:https://" "docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/#lists[AsciiDoc " "Syntax Quick Reference]." msgstr "" #. type: Title === #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:162 #, no-wrap msgid "Ordered lists" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:165 msgid "To create an ordered list use the `.` character." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:167 msgid "For example, this is an ordered list." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:173 #, no-wrap msgid "" ". First item\n" ". Second item\n" ".. Subsecond item\n" ". Third item\n" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:176 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:197 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:240 msgid "And this would be rendered as." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:178 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:199 msgid "First item" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:179 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:200 msgid "Second item" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:180 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:201 msgid "Subsecond item" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:181 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:202 msgid "Third item" msgstr "" #. type: Title === #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:183 #, no-wrap msgid "Unordered lists" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:186 msgid "To create an unordered list use the `*` character." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:188 msgid "For example, this is an unordered list." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:194 #, no-wrap msgid "" "* First item\n" "* Second item\n" "** Subsecond item\n" "* Third item\n" msgstr "" #. type: Title == #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:204 #, no-wrap msgid "Links" msgstr "" #. type: Title === #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:207 #, no-wrap msgid "External links" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:210 msgid "To point to another website the `link` macro should be used." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:213 #, no-wrap msgid "link:https://www.FreeBSD.org[FreeBSD]\n" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:219 msgid "" "As the Asciidoctor documentation describes, the `link` macro is not required " "when the target starts with a URL scheme like `https`. However, it is a " "good practice to do this anyway to ensure that Asciidoctor renders the link " "correctly, especially in non-latin languages like Japanese." msgstr "" #. type: Title === #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:222 #, no-wrap msgid "Links to another book or article" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:226 msgid "" "To point to another book or article the Asciidoctor variables should be " "used. For example, if we are in the `cups` article and we want to point to " "`ipsec-must` these steps should be used." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:228 msgid "" "Include the [.filename]#urls.adoc# file from [.filename]#~/doc/shared# " "folder." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:231 #, no-wrap msgid "\\include::shared/{lang}/urls.adoc[]\n" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:234 msgid "" "Then create a link using the Asciidoctor variable to the `ipsec-must` " "article." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:237 #, no-wrap msgid "extref:{ipsec-must}[IPSec-Must article]\n" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:242 msgid "extref:{ipsec-must}[IPSec-Must article]" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:247 msgid "" "The `extref` macro is defined as an extension. It is designed to render the " "correct link across the different outputs" msgstr "" #. type: Title === #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:249 #, no-wrap msgid "Links to the same file or to another file in the same book" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:254 msgid "" "Books are structured in different directories to keep a sane layout. To " "create a link from one subdirectory of a book to another subdirectory of the " "same book, use the `crossref` macro:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:256 #, no-wrap msgid "crossref:doc-build[documentation-makefile, This link]\n" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:258 msgid "And this would be rendered as" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:260 msgid "crossref:doc-build[documentation-makefile, This link]" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:265 msgid "" "The `crossref` macro is defined as an extension. It is designed to render " "the correct link across the different outputs" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:272 msgid "" "Use the `crossref` macro for intra-document links too. Although it might be " "inconvenient to write the name of the current document, it ensures the " "correct link is rendered across the different outputs" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:278 msgid "" "Do not use either the `xref` macro or its shortcut `<<` `>>`. They do not " "work well in all output formats." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:284 msgid "" "When the second parameter of the `crossref` macro contains a comma, it must " "be enclosed in double quotes. Otherwise, the comma is interpreted as a " "parameter separator, and the text after the comma is stripped." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:286 msgid "For example:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:288 #, no-wrap msgid "crossref:plist[documentation-comma, \"First, second\"]\n" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:290 msgid "" "Without quotes, only `First` would be used as the link text, and the rest " "would be lost." msgstr "" #. type: Title == #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:293 #, no-wrap msgid "Images and Icons" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:297 msgid "" "Images and icons play a crucial role in enhancing the overall user " "experience. These visual elements are strategically integrated to convey " "information, clarify concepts, and provide a visually engaging interface." msgstr "" #. type: Title === #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:299 #, no-wrap msgid "Images" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:302 msgid "" "Images help illustrate complex concepts, making them more accessible to " "users." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:304 msgid "" "The first step will be to add the image in the images directory in the path:" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:306 msgid "[.filename]#~/website/static/images/# for the website." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:307 msgid "[.filename]#~/documentation/static/images/# for the documentation." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:309 msgid "" "For example, to add a new image to the FreeBSD installation process, the " "image will be saved to the path [.filename]#~/documentation/static/images/" "books/handbook/bsdinstall/new-image3.png#." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:311 msgid "" "The next step will be to configure the Asciidoctor attributes `images-path` " "and `imagesdir`." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:313 msgid "" "We are going to use as an example the header of the extref:{freebsd-releng}" "[FreeBSD Release Engineering] article." msgstr "" #. type: Title = #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:316 #, no-wrap msgid "FreeBSD Release Engineering" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:318 msgid ":doctype: article" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:320 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:324 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:328 msgid "[...]" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:322 msgid ":images-path: articles/freebsd-releng/ <1>" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:326 msgid ":imagesdir: ../../../images/{images-path} <2>" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:332 msgid "Makes reference to the path inside [.filename]#/static/images# folder." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:333 msgid "Makes reference to the Asciidoctor attribute." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:335 msgid "" "Once the image is in the correct path and the Asciidoctor attributes have " "been configured in the document, the `image` macro can be used." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:337 msgid "This is an example:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:340 #, no-wrap msgid "image::new-image3.png[New step in the FreeBSD install process]\n" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:345 msgid "" "To improve accessibility, it is mandatory to add descriptive text to each " "image." msgstr "" #. type: Title === #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:348 #, no-wrap msgid "Icons" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:351 msgid "Icons serve as intuitive symbols for quick recognition and navigation." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:353 msgid "" "The first step to use icons is to add the `icons` property to the " "Asciidoctor properties section, at the top of each document." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:356 #, no-wrap msgid ":icons: font\n" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:359 msgid "" "Once the Asciidoctor icon property has been set an icon supported by " "link:https://fontawesome.com/v4/icons/[Font Awesome] can be added." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:361 msgid "This is an example about how to use the `envelope` icon:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:364 #, no-wrap msgid "icon:envelope[link=mailto:test@example.com, title=\"contact\"]\n" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:369 msgid "" "To improve the accessibility of the website, the `title` attribute is " "mandatory." msgstr "" #. type: Title == #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:372 #, no-wrap msgid "Conclusion" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:375 msgid "" "This is the conclusion of this Asciidoctor primer. For reasons of space and " "complexity, several things have not been covered in depth (or at all)." msgstr ""