git: aef48a9185 - main - Split the FDP Primer into different chapters
Sergio Carlavilla Delgado
carlavilla at FreeBSD.org
Sat Apr 10 14:31:47 UTC 2021
The branch main has been updated by carlavilla:
URL: https://cgit.FreeBSD.org/doc/commit/?id=aef48a918535769311c2c93448f1920b7a3cf351
commit aef48a918535769311c2c93448f1920b7a3cf351
Author: Sergio Carlavilla Delgado <carlavilla at FreeBSD.org>
AuthorDate: 2021-04-10 14:31:17 +0000
Commit: Sergio Carlavilla Delgado <carlavilla at FreeBSD.org>
CommitDate: 2021-04-10 14:31:17 +0000
Split the FDP Primer into different chapters
---
.../content/en/books/fdp-primer/_index.adoc | 97 +--------
.../fdp-primer/asciidoctor-primer/_index.adoc | 224 ++++++++++++++++++++
.../fdp-primer/asciidoctor-primer/chapter.adoc | 202 ------------------
.../content/en/books/fdp-primer/book.adoc | 114 ++++++++++
.../en/books/fdp-primer/chapters-order.adoc | 30 +--
.../doc-build/{chapter.adoc => _index.adoc} | 29 ++-
.../editor-config/{chapter.adoc => _index.adoc} | 10 +-
.../examples/{chapter.adoc => _index.adoc} | 9 +-
.../manual-pages/{chapter.adoc => _index.adoc} | 102 ++++++---
.../overview/{chapter.adoc => _index.adoc} | 44 ++--
.../po-translations/{chapter.adoc => _index.adoc} | 72 +++++--
.../preface/{chapter.adoc => _index.adoc} | 9 +-
.../rosetta/{chapter.adoc => _index.adoc} | 2 +-
.../see-also/{chapter.adoc => _index.adoc} | 3 +-
.../structure/{chapter.adoc => _index.adoc} | 76 +++++--
.../fdp-primer/tools/{chapter.adoc => _index.adoc} | 11 +-
.../translations/{chapter.adoc => _index.adoc} | 90 +++++---
.../en/books/fdp-primer/working-copy/_index.adoc | 134 ++++++++++++
.../en/books/fdp-primer/working-copy/chapter.adoc | 113 ----------
.../en/books/fdp-primer/writing-style/_index.adoc | 231 +++++++++++++++++++++
.../en/books/fdp-primer/writing-style/chapter.adoc | 173 ---------------
21 files changed, 1038 insertions(+), 737 deletions(-)
diff --git a/documentation/content/en/books/fdp-primer/_index.adoc b/documentation/content/en/books/fdp-primer/_index.adoc
index 7428515fdf..3ec2036db2 100644
--- a/documentation/content/en/books/fdp-primer/_index.adoc
+++ b/documentation/content/en/books/fdp-primer/_index.adoc
@@ -3,113 +3,30 @@ title: FreeBSD Documentation Project Primer for New Contributors
authors:
- author: The FreeBSD Documentation Project
copyright: 1998-2021 DocEng
-releaseinfo: "$FreeBSD$"
trademarks: ["general"]
+next: books/fdp-primer/preface
---
= FreeBSD Documentation Project Primer for New Contributors
:doctype: book
:toc: macro
-:toclevels: 2
+:toclevels: 1
: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"]
-include::shared/mirrors.adoc[]
-include::shared/authors.adoc[]
-include::shared/releases.adoc[]
-include::shared/en/mailing-lists.adoc[]
-include::shared/en/teams.adoc[]
-include::shared/en/urls.adoc[]
-:chapters-path: content/en/books/fdp-primer/
-endif::[]
-
-ifeval::["{backend}" == "pdf"]
-include::../../../../shared/mirrors.adoc[]
-include::../../../../shared/authors.adoc[]
-include::../../../../shared/releases.adoc[]
-include::../../../../shared/en/mailing-lists.adoc[]
-include::../../../../shared/en/teams.adoc[]
-include::../../../../shared/en/urls.adoc[]
-:chapters-path:
-endif::[]
-
-ifeval::["{backend}" == "epub3"]
-include::../../../../shared/mirrors.adoc[]
-include::../../../../shared/authors.adoc[]
-include::../../../../shared/releases.adoc[]
-include::../../../../shared/en/mailing-lists.adoc[]
-include::../../../../shared/en/teams.adoc[]
-include::../../../../shared/en/urls.adoc[]
-:chapters-path:
-endif::[]
[.abstract-title]
-[abstract]
Abstract
-Thank you for becoming a part of the FreeBSD Documentation Project. Your contribution is extremely valuable, and we appreciate it.
+Thank you for becoming a part of the FreeBSD Documentation Project.
+Your contribution is extremely valuable, and we appreciate it.
This primer covers details needed to start contributing to the FreeBSD Documentation Project, or FDP, including tools, software, and the philosophy behind the Documentation Project.
-This is a work in progress. Corrections and additions are always welcome.
+This is a work in progress.
+Corrections and additions are always welcome.
'''
-toc::[]
-
-include::{chapters-path}toc-figures.adoc[]
-
-include::{chapters-path}toc-tables.adoc[]
-
-include::{chapters-path}toc-examples.adoc[]
-
-:sectnums!:
-
-include::{chapters-path}preface/chapter.adoc[leveloffset=+1, lines=7..-1]
-
-:sectnums:
-
-include::{chapters-path}overview/chapter.adoc[leveloffset=+1, lines=7..21; 25..-1]
-
-include::{chapters-path}tools/chapter.adoc[leveloffset=+1, lines=7..21; 25..-1]
-
-include::{chapters-path}working-copy/chapter.adoc[leveloffset=+1, lines=7..21; 25..-1]
-
-include::{chapters-path}structure/chapter.adoc[leveloffset=+1, lines=7..21; 25..-1]
-
-include::{chapters-path}doc-build/chapter.adoc[leveloffset=+1, lines=7..21; 25..-1]
-
-include::{chapters-path}asciidoctor-primer/chapter.adoc[leveloffset=+1, lines=7..21; 27..-1]
-
-include::{chapters-path}rosetta/chapter.adoc[leveloffset=+1, lines=7..21; 25..-1]
-
-include::{chapters-path}translations/chapter.adoc[leveloffset=+1, lines=7..21; 28..-1]
-
-include::{chapters-path}po-translations/chapter.adoc[leveloffset=+1, lines=7..21; 27..-1]
-
-include::{chapters-path}manual-pages/chapter.adoc[leveloffset=+1, lines=7..21; 25..-1]
-
-include::{chapters-path}writing-style/chapter.adoc[leveloffset=+1, lines=7..21; 27..-1]
-
-include::{chapters-path}editor-config/chapter.adoc[leveloffset=+1, lines=7..21; 25..-1]
-
-include::{chapters-path}see-also/chapter.adoc[leveloffset=+1, lines=7..21; 27..-1]
-
-:sectnums!:
-
-include::{chapters-path}examples/chapter.adoc[leveloffset=+1, lines=6..21; 25..-1]
-
-:sectnums:
+include::content/en/books/fdp-primer/toc.adoc[]
diff --git a/documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc b/documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc
new file mode 100644
index 0000000000..947a42ca45
--- /dev/null
+++ b/documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc
@@ -0,0 +1,224 @@
+---
+title: Chapter 6. AsciiDoctor Primer
+prev: books/fdp-primer/doc-build
+next: books/fdp-primer/rosetta
+---
+
+[[asciidoctor-primer]]
+= AsciiDoctor Primer
+:doctype: book
+:toc: macro
+:toclevels: 1
+:icons: font
+:sectnums:
+:sectnumlevels: 6
+:source-highlighter: rouge
+:experimental:
+:skip-front-matter:
+:xrefstyle: basic
+:relfileprefix: ../
+:outfilesuffix:
+:sectnumoffset: 6
+
+include::shared/en/urls.adoc[]
+
+toc::[]
+
+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].
+
+[[asciidoctor-primer-overview]]
+== Overview
+
+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.
+
+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.
+
+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.
+
+More precisely, they need help identifying what is what.
+Consider this text:
+
+To remove [.filename]#/tmp/foo#, use man:rm[1].
+
+[source,shell]
+----
+% rm /tmp/foo
+----
+
+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.
+
+The previous example is actually represented in this document like this:
+
+....
+To remove [.filename]#/tmp/foo#, use man:rm[1].
+
+[source,shell]
+----
+% rm /tmp/foo
+----
+....
+
+[[asciidoctor-headings]]
+== Headings
+
+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.
+
+This is an example of headings in an `article`.
+
+....
+\= Document Title (Level 0)
+
+\== Level 1 Section Title
+
+\=== Level 2 Section Title
+
+\==== Level 3 Section Title
+
+\===== Level 4 Section Title
+
+\====== Level 5 Section Title
+
+\== Another Level 1 Section Title
+....
+
+[WARNING]
+====
+Section levels cannot be skipped when nesting sections.
+
+The following syntax is not correct.
+
+....
+\= Document Title
+
+\== Level 2
+
+\==== Level 4
+....
+====
+
+[[asciidoctor-paragraphs]]
+== Paragraphs
+
+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.
+
+For example, this is a heading with two paragraphs.
+
+....
+\= This is the heading
+
+This is the first paragraph.
+This is also the first paragraph.
+
+And this is the second paragraph.
+....
+
+[[asciidoctor-lists]]
+== Lists
+
+AsciiDoctor supports two type of lists: ordered and unordered.
+To get more information about lists check link:https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/#lists[AsciiDoc Syntax Quick Reference]
+
+[[asciidoctor-ordered-lists]]
+=== Ordered lists
+
+To create an ordered list use the `*` character.
+
+For example this is an ordered list.
+
+....
+* First item
+* Second item
+** Subsecond item
+* Third item
+....
+
+And this would be rendered as.
+
+* First item
+* Second item
+** Subsecond item
+* Third item
+
+[[asciidoctor-unordered-lists]]
+=== Unordered lists
+
+To create an unordered list use the `.` character.
+
+For example this is an unordered list.
+
+....
+. First item
+. Second item
+.. Subsecond item
+. Third item
+....
+
+And this would be rendered as.
+
+. First item
+. Second item
+.. Subsecond item
+. Third item
+
+[[asciidoctor-links]]
+== Links
+
+[[asciidoctor-links-external]]
+=== External links
+
+To point to another website the `link` macro should be used.
+
+....
+link:https://www.FreeBSD.org[FreeBSD]
+....
+
+[NOTE]
+====
+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.
+====
+
+[[asciidoctor-links-internal]]
+=== Internal link
+
+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.
+
+. Include the [.filename]#urls.adoc# file from [.filename]#~/doc/shared# folder.
++
+....
+\include::shared/{lang}/urls.adoc[]
+....
++
+. Then create a link using the AsciiDoctor variable to the `ipsec-must` article.
++
+....
+link:{ipsec-must}[IPSec-Must article]
+....
++
+And this would be rendered as.
++
+link:{ipsec-must}[IPSec-Must article]
+
+[[asciidoctor-conclusion]]
+== Conclusion
+
+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).
diff --git a/documentation/content/en/books/fdp-primer/asciidoctor-primer/chapter.adoc b/documentation/content/en/books/fdp-primer/asciidoctor-primer/chapter.adoc
deleted file mode 100644
index d13a79de9c..0000000000
--- a/documentation/content/en/books/fdp-primer/asciidoctor-primer/chapter.adoc
+++ /dev/null
@@ -1,202 +0,0 @@
----
-title: Chapter 6. AsciiDoctor Primer
-prev: books/fdp-primer/doc-build
-next: books/fdp-primer/rosetta
----
-
-[[asciidoctor-primer]]
-= AsciiDoctor Primer
-:doctype: book
-:toc: macro
-:toclevels: 1
-:icons: font
-:sectnums:
-:sectnumlevels: 6
-:source-highlighter: rouge
-:experimental:
-:skip-front-matter:
-:xrefstyle: basic
-:relfileprefix: ../
-:outfilesuffix:
-:sectnumoffset: 6
-
-include::shared/en/urls.adoc[]
-
-toc::[]
-
-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].
-
-[[asciidoctor-primer-overview]]
-== Overview
-
-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.
-
-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.
-
-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.
-
-More precisely, they need help identifying what is what. Consider this text:
-
-To remove [.filename]#/tmp/foo#, use man:rm[1].
-
-[source,shell]
-----
-% rm /tmp/foo
-----
-
-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.
-
-
-The previous example is actually represented in this document like this:
-
-....
-To remove [.filename]#/tmp/foo#, use man:rm[1].
-
-[source,shell]
-----
-% rm /tmp/foo
-----
-....
-
-[[asciidoctor-headings]]
-== Headings
-
-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.
-
-This is an example of headings in an `article`.
-
-....
-= Document Title (Level 0)
-
-== Level 1 Section Title
-
-=== Level 2 Section Title
-
-==== Level 3 Section Title
-
-===== Level 4 Section Title
-
-====== Level 5 Section Title
-
-== Another Level 1 Section Title
-....
-
-[WARNING]
-====
-Section levels cannot be skipped when nesting sections.
-
-The following syntax is not correct.
-
-....
-= Document Title
-
-== Level 2
-
-==== Level 4
-....
-====
-
-[[asciidoctor-paragraphs]]
-== Paragraphs
-
-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.
-
-For example, this is a heading with two paragraphs.
-
-....
-= This is the heading
-
-This is the first paragraph.
-
-And this is the second paragraph.
-....
-
-[[asciidoctor-lists]]
-== Lists
-
-AsciiDoctor supports two type of lists: ordered and unordered. To get more information about lists check link:https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/#lists[AsciiDoc Syntax Quick Reference]
-
-[[asciidoctor-ordered-lists]]
-=== Ordered lists
-
-To create an ordered list use the `*` character.
-
-For example this is an ordered list.
-
-....
-* First item
-* Second item
-** Subsecond item
-* Third item
-....
-
-And this would be rendered as.
-
-* First item
-* Second item
-** Subsecond item
-* Third item
-
-[[asciidoctor-unordered-lists]]
-=== Unordered lists
-
-To create an unordered list use the `.` character.
-
-For example this is an unordered list.
-
-....
-. First item
-. Second item
-.. Subsecond item
-. Third item
-....
-
-And this would be rendered as.
-
-. First item
-. Second item
-.. Subsecond item
-. Third item
-
-[[asciidoctor-links]]
-== Links
-
-[[asciidoctor-links-external]]
-=== External links
-
-To point to another website the `link` macro should be used.
-
-....
-link:https://www.FreeBSD.org[FreeBSD]
-....
-
-[NOTE]
-====
-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.
-====
-
-[[asciidoctor-links-internal]]
-=== Internal link
-
-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.
-
-. Include the [.filename]#urls.adoc# file from [.filename]#~/doc/shared# folder.
-+
-....
-\include::shared/{lang}/urls.adoc[]
-....
-+
-. Then create a link using the AsciiDoctor variable to the `ipsec-must` article.
-+
-....
-link:{ipsec-must}[IPSec-Must article]
-....
-+
-And this would be rendered as.
-+
-link:{ipsec-must}[IPSec-Must article]
-
-[[asciidoctor-conclusion]]
-== Conclusion
-
-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).
diff --git a/documentation/content/en/books/fdp-primer/book.adoc b/documentation/content/en/books/fdp-primer/book.adoc
new file mode 100644
index 0000000000..b12b59b48e
--- /dev/null
+++ b/documentation/content/en/books/fdp-primer/book.adoc
@@ -0,0 +1,114 @@
+---
+title: FreeBSD Documentation Project Primer for New Contributors
+authors:
+ - author: The FreeBSD Documentation Project
+copyright: 1998-2021 DocEng
+trademarks: ["general"]
+---
+
+= FreeBSD Documentation Project Primer for New Contributors
+: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"]
+include::shared/mirrors.adoc[]
+include::shared/authors.adoc[]
+include::shared/releases.adoc[]
+include::shared/en/mailing-lists.adoc[]
+include::shared/en/teams.adoc[]
+include::shared/en/urls.adoc[]
+:chapters-path: content/en/books/fdp-primer/
+endif::[]
+
+ifeval::["{backend}" == "pdf"]
+include::../../../../shared/mirrors.adoc[]
+include::../../../../shared/authors.adoc[]
+include::../../../../shared/releases.adoc[]
+include::../../../../shared/en/mailing-lists.adoc[]
+include::../../../../shared/en/teams.adoc[]
+include::../../../../shared/en/urls.adoc[]
+:chapters-path:
+endif::[]
+
+ifeval::["{backend}" == "epub3"]
+include::../../../../shared/mirrors.adoc[]
+include::../../../../shared/authors.adoc[]
+include::../../../../shared/releases.adoc[]
+include::../../../../shared/en/mailing-lists.adoc[]
+include::../../../../shared/en/teams.adoc[]
+include::../../../../shared/en/urls.adoc[]
+:chapters-path:
+endif::[]
+
+[.abstract-title]
+[abstract]
+Abstract
+
+Thank you for becoming a part of the FreeBSD Documentation Project. Your contribution is extremely valuable, and we appreciate it.
+
+This primer covers details needed to start contributing to the FreeBSD Documentation Project, or FDP, including tools, software, and the philosophy behind the Documentation Project.
+
+This is a work in progress. Corrections and additions are always welcome.
+
+'''
+
+toc::[]
+
+include::content/en/books/fdp-primer/toc-figures.adoc[]
+
+include::content/en/books/fdp-primer/toc-tables.adoc[]
+
+include::content/en/books/fdp-primer/toc-examples.adoc[]
+
+:sectnums!:
+
+include::{chapters-path}preface/_index.adoc[leveloffset=+1, lines=7..-1]
+
+:sectnums:
+
+include::{chapters-path}overview/_index.adoc[leveloffset=+1, lines=7..21; 25..-1]
+
+include::{chapters-path}tools/_index.adoc[leveloffset=+1, lines=7..21; 25..-1]
+
+include::{chapters-path}working-copy/_index.adoc[leveloffset=+1, lines=7..21; 25..-1]
+
+include::{chapters-path}structure/_index.adoc[leveloffset=+1, lines=7..21; 25..-1]
+
+include::{chapters-path}doc-build/_index.adoc[leveloffset=+1, lines=7..21; 25..-1]
+
+include::{chapters-path}asciidoctor-primer/_index.adoc[leveloffset=+1, lines=7..21; 27..-1]
+
+include::{chapters-path}rosetta/_index.adoc[leveloffset=+1, lines=7..21; 25..-1]
+
+include::{chapters-path}translations/_index.adoc[leveloffset=+1, lines=7..21; 28..-1]
+
+include::{chapters-path}po-translations/_index.adoc[leveloffset=+1, lines=7..21; 27..-1]
+
+include::{chapters-path}manual-pages/_index.adoc[leveloffset=+1, lines=7..21; 25..-1]
+
+include::{chapters-path}writing-style/_index.adoc[leveloffset=+1, lines=7..21; 27..-1]
+
+include::{chapters-path}editor-config/_index.adoc[leveloffset=+1, lines=7..21; 25..-1]
+
+include::{chapters-path}see-also/_index.adoc[leveloffset=+1, lines=7..21; 27..-1]
+
+:sectnums!:
+
+include::{chapters-path}examples/_index.adoc[leveloffset=+1, lines=6..21; 25..-1]
+
+:sectnums:
diff --git a/documentation/content/en/books/fdp-primer/chapters-order.adoc b/documentation/content/en/books/fdp-primer/chapters-order.adoc
index e0693a8503..e351e05521 100644
--- a/documentation/content/en/books/fdp-primer/chapters-order.adoc
+++ b/documentation/content/en/books/fdp-primer/chapters-order.adoc
@@ -1,15 +1,15 @@
-preface/chapter.adoc
-overview/chapter.adoc
-tools/chapter.adoc
-working-copy/chapter.adoc
-structure/chapter.adoc
-doc-build/chapter.adoc
-asciidoctor-primer/chapter.adoc
-rosetta/chapter.adoc
-translations/chapter.adoc
-po-translations/chapter.adoc
-manual-pages/chapter.adoc
-writing-style/chapter.adoc
-editor-config/chapter.adoc
-see-also/chapter.adoc
-examples/chapter.adoc
+preface/_index.adoc
+overview/_index.adoc
+tools/_index.adoc
+working-copy/_index.adoc
+structure/_index.adoc
+doc-build/_index.adoc
+asciidoctor-primer/_index.adoc
+rosetta/_index.adoc
+translations/_index.adoc
+po-translations/_index.adoc
+manual-pages/_index.adoc
+writing-style/_index.adoc
+editor-config/_index.adoc
+see-also/_index.adoc
+examples/_index.adoc
diff --git a/documentation/content/en/books/fdp-primer/doc-build/chapter.adoc b/documentation/content/en/books/fdp-primer/doc-build/_index.adoc
similarity index 93%
rename from documentation/content/en/books/fdp-primer/doc-build/chapter.adoc
rename to documentation/content/en/books/fdp-primer/doc-build/_index.adoc
index 13ceb60f53..04a3398b20 100644
--- a/documentation/content/en/books/fdp-primer/doc-build/chapter.adoc
+++ b/documentation/content/en/books/fdp-primer/doc-build/_index.adoc
@@ -45,7 +45,8 @@ Different types of output can be produced from a single AsciiDoc source file.
|`epub`
|EPUB
-|Electronic Publication. ePub file format.
+|Electronic Publication.
+ePub file format.
|===
[[doc-build-rendering-html]]
@@ -123,7 +124,8 @@ There are three [.filename]#Makefile# files for building some or all of the docu
* The [.filename]#Makefile# in the [.filename]#website# directory will build only the website.
* The [.filename]#Makefile# at the top of the tree will build both the documentation and the website.
-The [.filename]#Makefile# appearing in subdirectories also support `make run` to serve built content with Hugo's internal webserver. This webserver runs on port 1313 by default.
+The [.filename]#Makefile# appearing in subdirectories also support `make run` to serve built content with Hugo's internal webserver.
+This webserver runs on port 1313 by default.
[[documentation-makefile]]
=== Documentation Makefile
@@ -152,6 +154,14 @@ MAINTAINER=carlavilla at FreeBSD.org <.>
PYTHON_CMD = /usr/local/bin/python3 <.>
HUGO_CMD = /usr/local/bin/hugo <.>
LANGUAGES = en,es,pt_BR,de,ja,zh_CN,zh_TW,ru,el,hu,it,mn,nl,pl,fr <.>
+RUBYLIB = ../shared/lib
+.export RUBYLIB
+
+.ifndef HOSTNAME
+.HOST+=localhost
+.else
+.HOST+=$(HOSTNAME)
+.endif
.ORDER: all run<.>
@@ -174,7 +184,7 @@ generate-books-toc: .PHONY <.>
${PYTHON_CMD} ./tools/books-toc-examples-creator.py -l ${LANGUAGES}
run: .PHONY <.>
- ${HUGO_CMD} server -D
+ ${HUGO_CMD} server -D --baseURL="http://$(.HOST):1313"
build: .PHONY <.>
${HUGO_CMD} --minify
@@ -217,6 +227,14 @@ MAINTAINER=carlavilla at FreeBSD.org <.>
PYTHON_CMD = /usr/local/bin/python3 <.>
HUGO_CMD = /usr/local/bin/hugo <.>
+RUBYLIB = ../shared/lib
+.export RUBYLIB
+
+.ifndef HOSTNAME
+.HOST+=localhost
+.else
+.HOST+=$(HOSTNAME)
+.endif
.ORDER: all run<.>
@@ -235,7 +253,7 @@ generate-releases: .PHONY <.>
${PYTHON_CMD} ./tools/releases-toml.py -p ./shared/releases.adoc
run: .PHONY <.>
- ${HUGO_CMD} server -D
+ ${HUGO_CMD} server -D --baseURL="http://$(.HOST):1313"
build: .PHONY <.>
${HUGO_CMD}
@@ -247,6 +265,7 @@ build: .PHONY <.>
<.> `.ORDER` directives are used to ensure multiple make jobs may run without problem.
<.> `all` target builds the website and puts the result in [.filename]#~/doc/website/public#.
<.> `starting-message` shows a message in the CLI to show the user that the process is running.
-<.> `generate-releases` calls the script used to convert from AsciiDoc variables to TOML variables. With this conversion, the releases variables can be used in AsciiDoc and in the Hugo custom templates.
+<.> `generate-releases` calls the script used to convert from AsciiDoc variables to TOML variables.
+With this conversion, the releases variables can be used in AsciiDoc and in the Hugo custom templates.
<.> `run` runs hugo webserver on port 1313, or a random free port if that is already in use.
<.> `build` builds the website and puts the result in the [.filename]#~/doc/website/public#.
diff --git a/documentation/content/en/books/fdp-primer/editor-config/chapter.adoc b/documentation/content/en/books/fdp-primer/editor-config/_index.adoc
similarity index 92%
rename from documentation/content/en/books/fdp-primer/editor-config/chapter.adoc
rename to documentation/content/en/books/fdp-primer/editor-config/_index.adoc
index 0e8f4405c6..5f184292dd 100644
--- a/documentation/content/en/books/fdp-primer/editor-config/chapter.adoc
+++ b/documentation/content/en/books/fdp-primer/editor-config/_index.adoc
@@ -32,7 +32,8 @@ Install from package:editors/vim[], package:editors/vim-console[], or package:ed
[[editor-config-vim-use]]
=== Use
-Press kbd:[P] to reformat paragraphs or text that has been selected in Visual mode. Press kbd:[T] to replace groups of eight spaces with a tab.
+Press kbd:[P] to reformat paragraphs or text that has been selected in Visual mode.
+Press kbd:[T] to replace groups of eight spaces with a tab.
[[editor-config-vim-config]]
=== Configuration
@@ -89,7 +90,9 @@ Install from package:editors/emacs[] or package:editors/emacs-devel[].
[[editor-config-emacs-validation]]
=== Validation
-Emacs's nxml-mode uses compact relax NG schemas for validating XML. A compact relax NG schema for FreeBSD's extension to DocBook 5.0 is included in the documentation repository. To configure nxml-mode to validate using this schema, create [.filename]#~/.emacs.d/schema/schemas.xml# and add these lines to the file:
+Emacs's nxml-mode uses compact relax NG schemas for validating XML.
+A compact relax NG schema for FreeBSD's extension to DocBook 5.0 is included in the documentation repository.
+To configure nxml-mode to validate using this schema, create [.filename]#~/.emacs.d/schema/schemas.xml# and add these lines to the file:
....
locatingRules xmlns="http://thaiopensource.com/ns/locating-rules/1.0"
@@ -104,7 +107,8 @@ locatingRules
[[editor-config-emacs-igor]]
=== Automated Proofreading with Flycheck and Igor
-The Flycheck package is available from Milkypostman's Emacs Lisp Package Archive (MELPA). If MELPA is not already in Emacs's packages-archives, it can be added by evaluating
+The Flycheck package is available from Milkypostman's Emacs Lisp Package Archive (MELPA).
+If MELPA is not already in Emacs's packages-archives, it can be added by evaluating
....
(add-to-list 'package-archives '("melpa" . "http://stable.melpa.org/packages/") t)
diff --git a/documentation/content/en/books/fdp-primer/examples/chapter.adoc b/documentation/content/en/books/fdp-primer/examples/_index.adoc
similarity index 86%
rename from documentation/content/en/books/fdp-primer/examples/chapter.adoc
rename to documentation/content/en/books/fdp-primer/examples/_index.adoc
index fe89666d66..65a97518ef 100644
--- a/documentation/content/en/books/fdp-primer/examples/chapter.adoc
+++ b/documentation/content/en/books/fdp-primer/examples/_index.adoc
@@ -22,7 +22,8 @@ prev: books/fdp-primer/see-also/
toc::[]
-These examples are not exhaustive - they do not contain all the elements that might be desirable to use, particularly in a document's front matter. For more examples of AsciiDoctor, examine the AsciiDoc source for this and other documents available in the Git `doc` repository, or available online starting at link:https://cgit.freebsd.org/doc/[https://cgit.freebsd.org/doc/].
+These examples are not exhaustive - they do not contain all the elements that might be desirable to use, particularly in a document's front matter.
+For more examples of AsciiDoctor, examine the AsciiDoc source for this and other documents available in the Git `doc` repository, or available online starting at link:https://cgit.freebsd.org/doc/[https://cgit.freebsd.org/doc/].
[[examples-asciidoctor-book]]
== AsciiDoctor `book`
@@ -110,7 +111,7 @@ authors:
trademarks: ["general"]
---
-= An Example Article
+\= An Example Article
:doctype: article
:toc: macro
:toclevels: 1
@@ -124,11 +125,11 @@ trademarks: ["general"]
toc::[]
-== My First Section
+\== My First Section
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.
diff --git a/documentation/content/en/books/fdp-primer/manual-pages/chapter.adoc b/documentation/content/en/books/fdp-primer/manual-pages/_index.adoc
similarity index 65%
rename from documentation/content/en/books/fdp-primer/manual-pages/chapter.adoc
rename to documentation/content/en/books/fdp-primer/manual-pages/_index.adoc
index 46b770a624..057e965a9d 100644
--- a/documentation/content/en/books/fdp-primer/manual-pages/chapter.adoc
+++ b/documentation/content/en/books/fdp-primer/manual-pages/_index.adoc
@@ -25,16 +25,20 @@ toc::[]
[[manual-pages-introduction]]
== Introduction
-_Manual pages_, commonly shortened to _man pages_, were conceived as readily-available reminders for command syntax, device driver details, or configuration file formats. They have become an extremely valuable quick-reference from the command line for users, system administrators, and programmers.
+_Manual pages_, commonly shortened to _man pages_, were conceived as readily-available reminders for command syntax, device driver details, or configuration file formats.
+They have become an extremely valuable quick-reference from the command line for users, system administrators, and programmers.
Although intended as reference material rather than tutorials, the EXAMPLES sections of manual pages often provide detailed use case.
-Manual pages are generally shown interactively by the man:man[1] command. When the user types `man ls`, a search is performed for a manual page matching `ls`. The first matching result is displayed.
+Manual pages are generally shown interactively by the man:man[1] command.
+When the user types `man ls`, a search is performed for a manual page matching `ls`.
+The first matching result is displayed.
[[manual-pages-sections]]
== Sections
-Manual pages are grouped into _sections_. Each section contains manual pages for a specific category of documentation:
+Manual pages are grouped into _sections_.
+Each section contains manual pages for a specific category of documentation:
[.informaltable]
[cols="1,8", options="header"]
@@ -74,16 +78,25 @@ Manual pages are grouped into _sections_. Each section contains manual pages for
[[manual-pages-markup]]
== Markup
-Various markup forms and rendering programs have been used for manual pages. FreeBSD has used man:groff[7] and the newer man:mandoc[1]. Most existing FreeBSD manual pages, and all new ones, use the man:mdoc[7] form of markup. This is a simple line-based markup that is reasonably expressive. It is mostly semantic: parts of text are marked up for what they are, rather than for how they should appear when rendered. There is some appearance-based markup which is usually best avoided.
+Various markup forms and rendering programs have been used for manual pages.
+FreeBSD has used man:groff[7] and the newer man:mandoc[1].
+Most existing FreeBSD manual pages, and all new ones, use the man:mdoc[7] form of markup.
+This is a simple line-based markup that is reasonably expressive.
+It is mostly semantic: parts of text are marked up for what they are, rather than for how they should appear when rendered.
+There is some appearance-based markup which is usually best avoided.
-Manual page source is usually interpreted and displayed to the screen interactively. The source files can be ordinary text files or compressed with man:gzip[1] to save space.
+Manual page source is usually interpreted and displayed to the screen interactively.
+The source files can be ordinary text files or compressed with man:gzip[1] to save space.
-Manual pages can also be rendered to other formats, including PostScript for printing or PDF generation. See man:man[1].
+Manual pages can also be rendered to other formats, including PostScript for printing or PDF generation.
+See man:man[1].
[[manual-pages-markup-sections]]
=== Manual Page Sections
-Manual pages are composed of several standard sections. Each section has a title in upper case, and the sections for a particular type of manual page appear in a specific order. For a category 1 General Command manual page, the sections are:
+Manual pages are composed of several standard sections.
+Each section has a title in upper case, and the sections for a particular type of manual page appear in a specific order.
+For a category 1 General Command manual page, the sections are:
[.informaltable]
[cols="2,4", options="header"]
@@ -129,12 +142,15 @@ Manual pages are composed of several standard sections. Each section has a title
|People who created the command or wrote the manual page.
|===
-Some sections are optional, and the combination of sections for a specific type of manual page vary. Examples of the most common types are shown later in this chapter.
+Some sections are optional, and the combination of sections for a specific type of manual page vary.
+Examples of the most common types are shown later in this chapter.
[[manual-pages-markup-macros]]
=== Macros
*** 1601 LINES SKIPPED ***
More information about the dev-commits-doc-all
mailing list