diff --git a/documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc b/documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc --- a/documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc +++ b/documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc @@ -67,7 +67,7 @@ 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. 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. +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. More precisely, they need help identifying what is what. @@ -89,12 +89,18 @@ .... To remove */tmp/foo*, use man:rm[1]. -[source,shell] ----- -% rm /tmp/foo ----- + [source,shell] + ---- + % rm /tmp/foo + ---- .... +[NOTE] +==== +This chapter provides examples of AsciiDoc document code. Since the documents themselves are also written in AsciiDoc, measures must be taken to ensure that the examples are displayed correctly. This is achieved by adding a single space character at the beginning of each line in the example. This is particularly important for lines containing directives such as `ifdef::`, `endif::`, `include::`, and similar, as well as for lines beginning with the characters `-` or `=`. This note applies to all code blocks in the FreeBSD documentation. It should be noted that ignoring this requirement may result in a document that renders correctly in English while breaking the rendering of documents in other translation languages. +==== + + [[asciidoctor-headings]] == Headings @@ -105,19 +111,19 @@ This is an example of headings in an `article`. .... -= Document Title (Level 0) + = Document Title (Level 0) -== Level 1 Section Title + == Level 1 Section Title -=== Level 2 Section Title + === Level 2 Section Title -==== Level 3 Section Title + ==== Level 3 Section Title -===== Level 4 Section Title + ===== Level 4 Section Title -====== Level 5 Section Title + ====== Level 5 Section Title -== Another Level 1 Section Title + == Another Level 1 Section Title .... [WARNING] @@ -127,11 +133,11 @@ The following syntax is not correct. .... -= Document Title + = Document Title -== Level 1 + == Level 1 -==== Level 3 + ==== Level 3 .... ==== @@ -145,12 +151,12 @@ For example, this is a heading with two paragraphs. .... -= This is the heading + = This is the heading -This is the first paragraph. -This is also the first paragraph. + This is the first paragraph. + This is also the first paragraph. -And this is the second paragraph. + And this is the second paragraph. .... [[asciidoctor-lists]] @@ -167,10 +173,10 @@ For example, this is an ordered list. .... -. First item -. Second item -.. Subsecond item -. Third item + . First item + . Second item + .. Subsecond item + . Third item .... And this would be rendered as. @@ -188,10 +194,10 @@ For example, this is an unordered list. .... -* First item -* Second item -** Subsecond item -* Third item + * First item + * Second item + ** Subsecond item + * Third item .... And this would be rendered as. @@ -210,7 +216,7 @@ To point to another website the `link` macro should be used. .... -link:https://www.FreeBSD.org[FreeBSD] + link:https://www.FreeBSD.org[FreeBSD] .... [NOTE] @@ -228,13 +234,13 @@ . Include the [.filename]#urls.adoc# file from [.filename]#~/doc/shared# folder. + .... -\include::shared/{lang}/urls.adoc[] + include::shared/{lang}/urls.adoc[] .... + . Then create a link using the Asciidoctor variable to the `ipsec-must` article. + .... -extref:{ipsec-must}[IPSec-Must article] + extref:{ipsec-must}[IPSec-Must article] .... + And this would be rendered as. @@ -253,7 +259,7 @@ To create a link from one subdirectory of a book to another subdirectory of the same book, use the `crossref` macro: .... -crossref:doc-build[documentation-makefile, This link] + crossref:doc-build[documentation-makefile, This link] .... And this would be rendered as @@ -302,18 +308,18 @@ [source,asciidoc] .... -= FreeBSD Release Engineering -:doctype: article + = FreeBSD Release Engineering + :doctype: article -[...] + [...] -:images-path: articles/freebsd-releng/ <1> + :images-path: articles/freebsd-releng/ <1> -[...] + [...] -:imagesdir: ../../../images/{images-path} <2> + :imagesdir: ../../../images/{images-path} <2> -[...] + [...] .... @@ -325,7 +331,7 @@ This is an example: .... -image::new-image3.png[New step in the FreeBSD install process] + image::new-image3.png[New step in the FreeBSD install process] .... [TIP] @@ -341,7 +347,7 @@ The first step to use icons is to add the `icons` property to the Asciidoctor properties section, at the top of each document. .... -:icons: font + :icons: font .... Once the Asciidoctor icon property has been set an icon supported by link:https://fontawesome.com/v4/icons/[Font Awesome] can be added. @@ -349,7 +355,7 @@ This is an example about how to use the `envelope` icon: .... -icon:envelope[link=mailto:test@example.com, title="contact"] + icon:envelope[link=mailto:test@example.com, title="contact"] .... [TIP] diff --git a/documentation/content/en/books/fdp-primer/examples/_index.adoc b/documentation/content/en/books/fdp-primer/examples/_index.adoc --- a/documentation/content/en/books/fdp-primer/examples/_index.adoc +++ b/documentation/content/en/books/fdp-primer/examples/_index.adoc @@ -59,64 +59,64 @@ ==== [.programlisting] .... ---- -title: An Example Book -authors: - - author: The FreeBSD Documentation Project -copyright: 1995-2021 The FreeBSD Documentation Project -releaseinfo: "" -trademarks: ["general"] ---- - -= An Example Book -:doctype: book -:toc: macro -:toclevels: 2 -:icons: font -:xrefstyle: basic -:relfileprefix: ../ -:outfilesuffix: -:sectnums: -:sectnumlevels: 6 -:partnums: -:chapter-signifier: Chapter -:part-signifier: Part -:source-highlighter: rouge -:experimental: -:skip-front-matter: -:book: true -:pdf: false - -ifeval::["{backend}" == "html5"] -:chapters-path: content/en/books/bookname/ -endif::[] - -ifeval::["{backend}" == "pdf"] -:chapters-path: -endif::[] - -ifeval::["{backend}" == "epub3"] -:chapters-path: -endif::[] - -[abstract] -Abstract - -Abstract section - -''' - -toc::[] - -:sectnums!: - -\include::{chapters-path}preface/_index.adoc[leveloffset=+1] - -:sectnums: - -\include::{chapters-path}parti.adoc[lines=7..18] - -\include::{chapters-path}chapter-name/_index.adoc[leveloffset=+1] + --- + title: An Example Book + authors: + - author: The FreeBSD Documentation Project + copyright: 1995-2021 The FreeBSD Documentation Project + releaseinfo: "" + trademarks: ["general"] + --- + + = An Example Book + :doctype: book + :toc: macro + :toclevels: 2 + :icons: font + :xrefstyle: basic + :relfileprefix: ../ + :outfilesuffix: + :sectnums: + :sectnumlevels: 6 + :partnums: + :chapter-signifier: Chapter + :part-signifier: Part + :source-highlighter: rouge + :experimental: + :skip-front-matter: + :book: true + :pdf: false + + ifeval::["{backend}" == "html5"] + :chapters-path: content/en/books/bookname/ + endif::[] + + ifeval::["{backend}" == "pdf"] + :chapters-path: + endif::[] + + ifeval::["{backend}" == "epub3"] + :chapters-path: + endif::[] + + [abstract] + Abstract + + Abstract section + + ''' + + toc::[] + + :sectnums!: + + include::{chapters-path}preface/_index.adoc[leveloffset=+1] + + :sectnums: + + include::{chapters-path}parti.adoc[lines=7..18] + + include::{chapters-path}chapter-name/_index.adoc[leveloffset=+1] .... ==== @@ -129,35 +129,35 @@ ==== [.programlisting] .... ---- -title: An Example Article -authors: - - author: Your name and surname - email: foo@example.com -trademarks: ["general"] ---- + --- + title: An Example Article + authors: + - author: Your name and surname + email: foo@example.com + trademarks: ["general"] + --- -= An Example Article -:doctype: article -:toc: macro -:toclevels: 1 -:icons: font -:sectnums: -:sectnumlevels: 6 -:source-highlighter: rouge -:experimental: + = An Example Article + :doctype: article + :toc: macro + :toclevels: 1 + :icons: font + :sectnums: + :sectnumlevels: 6 + :source-highlighter: rouge + :experimental: -''' + ''' -toc::[] + toc::[] -== My First Section + == My First Section -This is the first section in my article. + This is the first section in my article. -=== My First Sub-Section + === My First Sub-Section -This is the first sub-section in my article. + This is the first sub-section in my article. .... diff --git a/documentation/content/en/books/fdp-primer/structure/_index.adoc b/documentation/content/en/books/fdp-primer/structure/_index.adoc --- a/documentation/content/en/books/fdp-primer/structure/_index.adoc +++ b/documentation/content/en/books/fdp-primer/structure/_index.adoc @@ -188,16 +188,16 @@ [source.programlisting,asciidoc] .... ---- -title: Chapter 8. Configuring the FreeBSD Kernel -part: Part II. Common Tasks -prev: books/handbook/multimedia -next: books/handbook/printing ---- - -[[kernelconfig]] -= Configuring the FreeBSD Kernel -... + --- + title: Chapter 8. Configuring the FreeBSD Kernel + part: Part II. Common Tasks + prev: books/handbook/multimedia + next: books/handbook/printing + --- + + [[kernelconfig]] + = Configuring the FreeBSD Kernel + ... .... When the HTML5 version of the Handbook is produced, this will yield *kernelconfig/index.html*. @@ -233,30 +233,30 @@ [source.programlisting,asciidoc] .... ---- -title: Why you should use a BSD style license for your Open Source Project -authors: - - author: Bruce Montague - email: brucem@alumni.cse.ucsc.edu -trademarks: ["freebsd", "intel", "general"] ---- - -= Why you should use a BSD style license for your Open Source Project -:doctype: article -:toc: macro -:toclevels: 1 -:icons: font -:sectnums: -:sectnumlevels: 6 -:source-highlighter: rouge -:experimental: - -''' - -toc::[] - -[[intro]] -== Introduction + --- + title: Why you should use a BSD style license for your Open Source Project + authors: + - author: Bruce Montague + email: brucem@alumni.cse.ucsc.edu + trademarks: ["freebsd", "intel", "general"] + --- + + = Why you should use a BSD style license for your Open Source Project + :doctype: article + :toc: macro + :toclevels: 1 + :icons: font + :sectnums: + :sectnumlevels: 6 + :source-highlighter: rouge + :experimental: + + ''' + + toc::[] + + [[intro]] + == Introduction .... == Managing Contributor Lists diff --git a/documentation/content/en/books/fdp-primer/trademarks/_index.adoc b/documentation/content/en/books/fdp-primer/trademarks/_index.adoc --- a/documentation/content/en/books/fdp-primer/trademarks/_index.adoc +++ b/documentation/content/en/books/fdp-primer/trademarks/_index.adoc @@ -69,17 +69,17 @@ The following is an example of the `Front Matter` of the extref:{contributing}[Contributing to FreeBSD] article: .... ---- -title: Contributing to FreeBSD -authors: - - author: Jordan Hubbard - - author: Sam Lawrance - - author: Mark Linimon -description: How to contribute to the FreeBSD Project -trademarks: ["freebsd", "ieee", "general"] -weight: 15 -tags: ["Contributing", "FreeBSD", "Non-Programmer Tasks", "Programmer Tasks"] ---- + --- + title: Contributing to FreeBSD + authors: + - author: Jordan Hubbard + - author: Sam Lawrance + - author: Mark Linimon + description: How to contribute to the FreeBSD Project + trademarks: ["freebsd", "ieee", "general"] + weight: 15 + tags: ["Contributing", "FreeBSD", "Non-Programmer Tasks", "Programmer Tasks"] + --- .... The trademark tags `freebsd`, `ieee`, and `general` will be automatically rendered when building the document like this: