Path: blob/main/documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.po
18099 views
# SOME DESCRIPTIVE TITLE # Copyright (C) YEAR The FreeBSD Project # This file is distributed under the same license as the FreeBSD Documentation package. # FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. # #, fuzzy msgid "" msgstr "" "Project-Id-Version: FreeBSD Documentation VERSION\n" "POT-Creation-Date: 2025-11-08 16:17+0000\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" "Language-Team: LANGUAGE <[email protected]>\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: 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: 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:55 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:57 #, no-wrap msgid "Overview" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:63 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:68 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:72 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:75 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:77 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:81 #, no-wrap msgid "% rm /tmp/foo\n" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:86 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:88 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:91 #, 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:96 #, 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:99 #, no-wrap msgid "Headings" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:104 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:106 msgid "This is an example of headings in an `article`." msgstr "" #. type: Title = #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:108 #, no-wrap msgid "Document Title (Level 0)" msgstr "" #. type: Title == #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:110 #, no-wrap msgid "Level 1 Section Title" msgstr "" #. type: Title === #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:112 #, no-wrap msgid "Level 2 Section Title" msgstr "" #. type: Title ==== #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:114 #, no-wrap msgid "Level 3 Section Title" msgstr "" #. type: Title ===== #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:116 #, no-wrap msgid "Level 4 Section Title" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:119 msgid "====== Level 5 Section Title" msgstr "" #. type: Title == #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:120 #, no-wrap msgid "Another Level 1 Section Title" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:126 msgid "Section levels cannot be skipped when nesting sections." msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:128 msgid "The following syntax is not correct." msgstr "" #. type: Title = #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:130 #, no-wrap msgid "Document Title" msgstr "" #. type: Title == #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:132 #, no-wrap msgid "Level 1" msgstr "" #. type: Title ==== #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:134 #, no-wrap msgid "Level 3" msgstr "" #. type: Title == #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:139 #, no-wrap msgid "Paragraphs" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:144 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:146 msgid "For example, this is a heading with two paragraphs." msgstr "" #. type: Title = #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:148 #, no-wrap msgid "This is the heading" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:152 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:154 msgid "And this is the second paragraph." msgstr "" #. type: Title == #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:157 #, no-wrap msgid "Lists" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:161 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:163 #, no-wrap msgid "Ordered lists" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:166 msgid "To create an ordered list use the `.` character." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:168 msgid "For example, this is an ordered list." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:174 #, 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:177 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:198 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:241 msgid "And this would be rendered as." 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 "First 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 "Second 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 "Subsecond item" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:182 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:203 msgid "Third item" msgstr "" #. type: Title === #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:184 #, no-wrap msgid "Unordered lists" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:187 msgid "To create an unordered list use the `*` character." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:189 msgid "For example, this is an unordered list." msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:195 #, 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:205 #, no-wrap msgid "Links" msgstr "" #. type: Title === #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:208 #, no-wrap msgid "External links" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:211 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:214 #, 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:220 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:223 #, no-wrap msgid "Links to another book or article" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:227 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:229 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:232 #, no-wrap msgid "\\include::shared/{lang}/urls.adoc[]\n" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:235 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:238 #, no-wrap msgid "extref:{ipsec-must}[IPSec-Must article]\n" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:243 msgid "extref:{ipsec-must}[IPSec-Must article]" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:248 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:250 #, 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:255 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:257 #, 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:259 msgid "And this would be rendered as" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:261 msgid "crossref:doc-build[documentation-makefile, This link]" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:266 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:273 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:279 msgid "" "Do not use either the `xref` macro or its shortcut `<<` `>>`. They do not " "work well in all output formats." msgstr "" #. type: Title == #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:282 #, no-wrap msgid "Images and Icons" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:286 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:288 #, no-wrap msgid "Images" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:291 msgid "" "Images help illustrate complex concepts, making them more accessible to " "users." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:293 msgid "" "The first step will be to add the image in the images directory in the path:" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:295 msgid "[.filename]#~/website/static/images/# for the website." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:296 msgid "[.filename]#~/documentation/static/images/# for the documentation." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:298 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: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:300 msgid "" "The next step will be to configure the Asciidoctor attributes `images-path` " "and `imagesdir`." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:302 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:305 #, no-wrap msgid "FreeBSD Release Engineering" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:307 msgid ":doctype: article" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:309 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:313 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:317 msgid "[...]" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:311 msgid ":images-path: articles/freebsd-releng/ <1>" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:315 msgid ":imagesdir: ../../../images/{images-path} <2>" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:321 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:322 msgid "Makes reference to the Asciidoctor attribute." msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:324 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:326 msgid "This is an example:" msgstr "" #. type: delimited block . 4 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:329 #, 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:334 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:337 #, no-wrap msgid "Icons" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:340 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:342 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:345 #, no-wrap msgid ":icons: font\n" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:348 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:350 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:353 #, no-wrap msgid "icon:envelope[link=mailto:[email protected], title=\"contact\"]\n" msgstr "" #. type: delimited block = 4 #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:358 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:361 #, no-wrap msgid "Conclusion" msgstr "" #. type: Plain text #: documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc:364 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 ""