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 @@ -1,115 +1,32 @@ --- 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/_index.adoc b/documentation/content/en/books/fdp-primer/book.adoc similarity index 59% copy from documentation/content/en/books/fdp-primer/_index.adoc copy to documentation/content/en/books/fdp-primer/book.adoc index 7428515fdf..b12b59b48e 100644 --- a/documentation/content/en/books/fdp-primer/_index.adoc +++ b/documentation/content/en/books/fdp-primer/book.adoc @@ -1,115 +1,114 @@ --- title: FreeBSD Documentation Project Primer for New Contributors authors: - author: The FreeBSD Documentation Project copyright: 1998-2021 DocEng -releaseinfo: "$FreeBSD$" 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::{chapters-path}toc-figures.adoc[] +include::content/en/books/fdp-primer/toc-figures.adoc[] -include::{chapters-path}toc-tables.adoc[] +include::content/en/books/fdp-primer/toc-tables.adoc[] -include::{chapters-path}toc-examples.adoc[] +include::content/en/books/fdp-primer/toc-examples.adoc[] :sectnums!: -include::{chapters-path}preface/chapter.adoc[leveloffset=+1, lines=7..-1] +include::{chapters-path}preface/_index.adoc[leveloffset=+1, lines=7..-1] :sectnums: -include::{chapters-path}overview/chapter.adoc[leveloffset=+1, lines=7..21; 25..-1] +include::{chapters-path}overview/_index.adoc[leveloffset=+1, lines=7..21; 25..-1] -include::{chapters-path}tools/chapter.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/chapter.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/chapter.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/chapter.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/chapter.adoc[leveloffset=+1, lines=7..21; 27..-1] +include::{chapters-path}asciidoctor-primer/_index.adoc[leveloffset=+1, lines=7..21; 27..-1] -include::{chapters-path}rosetta/chapter.adoc[leveloffset=+1, lines=7..21; 25..-1] +include::{chapters-path}rosetta/_index.adoc[leveloffset=+1, lines=7..21; 25..-1] -include::{chapters-path}translations/chapter.adoc[leveloffset=+1, lines=7..21; 28..-1] +include::{chapters-path}translations/_index.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}po-translations/_index.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}manual-pages/_index.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}writing-style/_index.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}editor-config/_index.adoc[leveloffset=+1, lines=7..21; 25..-1] -include::{chapters-path}see-also/chapter.adoc[leveloffset=+1, lines=7..21; 27..-1] +include::{chapters-path}see-also/_index.adoc[leveloffset=+1, lines=7..21; 27..-1] :sectnums!: -include::{chapters-path}examples/chapter.adoc[leveloffset=+1, lines=6..21; 25..-1] +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 @@ -1,252 +1,271 @@ --- title: Chapter 5. The FreeBSD Documentation Build Process prev: books/fdp-primer/structure next: books/fdp-primer/asciidoctor-primer --- [[doc-build]] = The FreeBSD Documentation Build Process :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :skip-front-matter: :xrefstyle: basic :relfileprefix: ../ :outfilesuffix: :sectnumoffset: 5 toc::[] This chapter covers organization of the documentation build process and how man:make[1] is used to control it. [[doc-build-rendering]] == Rendering AsciiDoc into Output Different types of output can be produced from a single AsciiDoc source file. [cols="20%,20%,60%", frame="none", options="header"] |=== | Formats | File Type | Description |`html` |HTML |An `article` or `book` chapter. |`pdf` |PDF |Portable Document Format. |`epub` |EPUB -|Electronic Publication. ePub file format. +|Electronic Publication. +ePub file format. |=== [[doc-build-rendering-html]] === Rendering to html To render the documentation and the website to `html` use one of the following examples. [[documentation-build-example]] .Build the documentation [example] ==== [source,shell] .... % cd ~/doc/documentation % make .... ==== [[website-build-example]] .Build the website [example] ==== [source,shell] .... % cd ~/doc/website % make .... ==== [[project-build-example]] .Build the entire documentation project [example] ==== [source,shell] .... % cd ~/doc % make -j2 .... ==== [[doc-build-rendering-pdf]] === Rendering to pdf To generate a document in `pdf` format use this command. In this example the English Handbook will be used. In order to export the document correctly all the extensions should be passed used the `-r` argument. [[document-pdf-example]] .Build the entire documentation project [example] ==== [source,shell] .... asciidoctor-pdf -r ./shared/lib/man-macro.rb -r ./shared/lib/git-macro.rb -r ./shared/lib/packages-macro.rb -r ./shared/lib/inter-document-references-macro.rb -r ./shared/lib/sectnumoffset-treeprocessor.rb --doctype=book -a skip-front-matter -a pdf-theme=./themes/default-pdf-theme.yml content/en/books/handbook/book.adoc .... ==== [[doc-build-toolset]] == The FreeBSD Documentation Build Toolset These are the tools used to build and install the FDP documentation. * The primary build tool is man:make[1], specifically Berkeley Make. * Python is used to generate the Table of Contents and other related Tables. * Hugo * AsciiDoctor * Git [[doc-build-makefile]] == Understanding the Makefile in the Documentation Tree There are three [.filename]#Makefile# files for building some or all of the documentation project. * The [.filename]#Makefile# in the [.filename]#documentation# directory will build only the documentation. * 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 This [.filename]#Makefile# takes the following form: [source,shell] .... # Generate the FreeBSD documentation # # Copyright (c) 2020-2021, The FreeBSD Documentation Project # Copyright (c) 2020-2021, Sergio Carlavilla # # Targets intended for use on the command line # # all (default) - generate the books TOC and compile all the documentation # run - serves the built documentation site for local browsing # # The run target uses hugo's built-in webserver to make the documentation site # available for local browsing. The documentation should have been built prior # to attempting to use the `run` target. By default, hugo will start its # webserver on port 1313. MAINTAINER=carlavilla@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<.> .ORDER: starting-message generate-books-toc .ORDER: starting-message build .ORDER: generate-books-toc build all: starting-message generate-books-toc build <.> starting-message: .PHONY <.> @echo --------------------------------------------------------------- @echo Building the documentation @echo --------------------------------------------------------------- generate-books-toc: .PHONY <.> ${PYTHON_CMD} ./tools/books-toc-parts-creator.py -l ${LANGUAGES} ${PYTHON_CMD} ./tools/books-toc-creator.py -l ${LANGUAGES} ${PYTHON_CMD} ./tools/books-toc-figures-creator.py -l ${LANGUAGES} ${PYTHON_CMD} ./tools/books-toc-tables-creator.py -l ${LANGUAGES} ${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 .... <.> The `MAINTAINER` flag specifies who is the maintainer of this Makefile. <.> `PYTHON_CMD` flag specifies the location of the Python binary. <.> `HUGO_CMD` flag specifies the location of the Hugo binary. <.> `LANGUAGES` flag specifies in which languages the table of contents has to be generated. <.> `.ORDER` directives are used to ensure multiple make jobs may run without problem. <.> `all` target generates the books' tables of contents ("TOCs"), builds the documentation and puts the result in [.filename]#~/doc/documentation/public#. <.> `starting-message` shows a message in the CLI to show the user that the process is running. <.> `generate-books-toc` calls the scripts to generate the books TOCs. <.> `run` runs hugo webserver on port 1313, or a random free port if that is already in use. <.> `build` builds the documentation and puts the result in the [.filename]#~/doc/documentation/public#. [[website-makefile]] === Website Makefile This [.filename]#Makefile# takes the form of: [source,shell] .... # Generate the FreeBSD website # # Copyright (c) 2020-2021, The FreeBSD Documentation Project # Copyright (c) 2020-2021, Sergio Carlavilla # # Targets intended for use on the command line # # all (default) - generate the releases.toml and compile all the website # run - serves the built documentation site for local browsing # # The run target uses hugo's built-in webserver to make the documentation site # available for local browsing. The documentation should have been built prior # to attempting to use the `run` target. By default, hugo will start its # webserver on port 1313. MAINTAINER=carlavilla@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<.> .ORDER: starting-message generate-releases .ORDER: starting-message build .ORDER: generate-releases build all: starting-message generate-releases run <.> starting-message: .PHONY <.> @echo --------------------------------------------------------------- @echo Building the website @echo --------------------------------------------------------------- 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} .... <.> The `MAINTAINER` flag specifies who is the maintainer of this Makefile. <.> `PYTHON_CMD` flag specifies the location of the Python binary. <.> `HUGO_CMD` flag specifies the location of the Hugo binary. <.> `.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 @@ -1,217 +1,221 @@ --- title: Chapter 12. Editor Configuration prev: books/fdp-primer/writing-style next: books/fdp-primer/see-also --- [[editor-config]] = Editor Configuration :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :skip-front-matter: :xrefstyle: basic :relfileprefix: ../ :outfilesuffix: :sectnumoffset: 12 toc::[] Adjusting your text editor configuration can make working on document files quicker and easier, and help documents conform to FDP guidelines. [[editor-config-vim]] == Vim Install from package:editors/vim[], package:editors/vim-console[], or package:editors/vim-tiny[] then follow the configuration instructions in <>. [[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 Edit [.filename]#~/.vimrc#, adding these lines to the end of the file: [.programlisting] .... if has("autocmd") au BufNewFile,BufRead *.sgml,*.ent,*.xsl,*.xml call Set_SGML() au BufNewFile,BufRead *.[1-9] call ShowSpecial() endif " has(autocmd) function Set_Highlights() "match ExtraWhitespace /^\s* \s*\|\s\+$/ highlight default link OverLength ErrorMsg match OverLength /\%71v.\+/ return 0 endfunction " Set_Highlights() function ShowSpecial() setlocal list listchars=tab:>>,trail:*,eol:$ hi def link nontext ErrorMsg return 0 endfunction " ShowSpecial() function Set_SGML() setlocal number syn match sgmlSpecial "&[^;]*;" setlocal syntax=sgml setlocal filetype=xml setlocal shiftwidth=2 setlocal textwidth=70 setlocal tabstop=8 setlocal softtabstop=2 setlocal formatprg="fmt -p" setlocal autoindent setlocal smartindent " Rewrap paragraphs noremap P gqj " Replace spaces with tabs noremap T :s/ /\t/ call ShowSpecial() call Set_Highlights() return 0 endfunction " Set_SGML() .... [[editor-config-emacs]] == Emacs 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" documentElement localName="section" typeId="DocBook" documentElement localName="chapter" typeId="DocBook" documentElement localName="article" typeId="DocBook" documentElement localName="book" typeId="DocBook" typeId id="DocBook" uri="/usr/local/shared/xml/docbook/5.0/rng/docbook.rnc" 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) .... Add the line to Emacs's initialization file (one of [.filename]#~/.emacs#, [.filename]#~/.emacs.el#, or [.filename]#~.emacs.d/init.el#) to make this change permanent. To install Flycheck, evaluate .... (package-install 'flycheck) .... Create a Flycheck checker for package:textproc/igor[] by evaluating .... (flycheck-define-checker igor "FreeBSD Documentation Project sanity checker. See URLs https://www.freebsd.org/docproj/ and http://www.freshports.org/textproc/igor/." :command ("igor" "-X" source-inplace) :error-parser flycheck-parse-checkstyle :modes (nxml-mode) :standard-input t) (add-to-list 'flycheck-checkers 'igor 'append) .... Again, add these lines to Emacs's initialization file to make the changes permanent. [[editor-config-emacs-specifc]] === FreeBSD Documentation Specific Settings To apply settings specific to the FreeBSD documentation project, create [.filename]#.dir-locals.el# in the root directory of the documentation repository and add these lines to the file: .... ;;; Directory Local Variables ;;; For more information see (info "(emacs) Directory Variables") ((nxml-mode (eval . (turn-on-auto-fill)) (fill-column . 70) (eval . (require 'flycheck)) (eval . (flycheck-mode 1)) (flycheck-checker . igor) (eval . (add-to-list 'rng-schema-locating-files "~/.emacs.d/schema/schemas.xml")))) .... [[editor-config-nano]] == nano Install from package:editors/nano[] or package:editors/nano-devel[]. [[editor-config-nano-config]] === Configuration Copy the sample XML syntax highlight file to the user's home directory: [source,shell] .... % cp /usr/local/shared/nano/xml.nanorc ~/.nanorc .... Use an editor to replace the lines in the [.filename]#~/.nanorc# `syntax "xml"` block with these rules: .... syntax "xml" "\.([jrs]html?|xml|xslt?)$" # trailing whitespace color ,blue "[[:space:]]+$" # multiples of eight spaces at the start a line # (after zero or more tabs) should be a tab color ,blue "^([TAB]*[ ]{8})+" # tabs after spaces color ,yellow "( )+TAB" # highlight indents that have an odd number of spaces color ,red "^(([ ]{2})+|(TAB+))*[ ]{1}[^ ]{1}" # lines longer than 70 characters color ,yellow "^(.{71})|(TAB.{63})|(TAB{2}.{55})|(TAB{3}.{47}).+$" .... Process the file to create embedded tabs: [source,shell] .... % perl -i'' -pe 's/TAB/\t/g' ~/.nanorc .... [[editor-config-nano-use]] === Use Specify additional helpful options when running the editor: [source,shell] .... % nano -AKipwz -r 70 -T8 _index.adoc .... Users of man:csh[1] can define an alias in [.filename]#~/.cshrc# to automate these options: .... alias nano "nano -AKipwz -r 70 -T8" .... After the alias is defined, the options will be added automatically: [source,shell] .... % nano _index.adoc .... 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 @@ -1,137 +1,138 @@ --- title: Appendix A. Examples prev: books/fdp-primer/see-also/ --- [appendix] [[examples]] = Examples :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :skip-front-matter: :xrefstyle: basic :relfileprefix: ../ :outfilesuffix: :sectnumoffset: A 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` .AsciiDoctor `book` [example] ==== [.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] .... ==== [[examples-asciidoctor-article]] == AsciiDoctor `article` .AsciiDoctor `article` [example] ==== [.programlisting] .... --- title: An Example Article authors: - author: Your name and surname email: foo@example.com trademarks: ["general"] --- -= An Example Article +\= An Example Article :doctype: article :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: ''' 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 @@ -1,488 +1,536 @@ --- title: Chapter 10. Manual Pages prev: books/fdp-primer/po-translations next: books/fdp-primer/writing-style --- [[manual-pages]] = Manual Pages :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :skip-front-matter: :xrefstyle: basic :relfileprefix: ../ :outfilesuffix: :sectnumoffset: 10 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"] |=== | Section Number | Category |1 |General Commands |2 |System Calls |3 |Library Functions |4 |Kernel Interfaces |5 |File Formats |6 |Games |7 |Miscellaneous |8 |System Manager |9 |Kernel Developer |=== [[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"] |=== | Section Name | Description |NAME |Name of the command |SYNOPSIS |Format of options and arguments |DESCRIPTION |Description of purpose and usage |ENVIRONMENT |Environment settings that affect operation |EXIT STATUS |Error codes returned on exit |EXAMPLES |Examples of usage |COMPATIBILITY |Compatibility with other implementations |SEE ALSO |Cross-reference to related manual pages |STANDARDS |Compatibility with standards like POSIX |HISTORY |History of implementation |BUGS |Known bugs |AUTHORS |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 -man:mdoc[7] markup is based on _macros_. Lines that begin with a dot contain macro commands, each two or three letters long. For example, consider this portion of the man:ls[1] manual page: +man:mdoc[7] markup is based on _macros_. +Lines that begin with a dot contain macro commands, each two or three letters long. +For example, consider this portion of the man:ls[1] manual page: [.programlisting] .... .Dd December 1, 2015 .Dt LS 1 .Sh NAME .Nm ls .Nd list directory contents .Sh SYNOPSIS .Nm .Op Fl -libxo .Op Fl ABCFGHILPRSTUWZabcdfghiklmnopqrstuwxy1, .Op Fl D Ar format .Op Ar .Sh DESCRIPTION For each operand that names a .Ar file of a type other than directory, .Nm displays its name as well as any requested, associated information. For each operand that names a .Ar file of type directory, .Nm displays the names of files contained within that directory, as well as any requested, associated information. .... A _Document date_ and _Document title_ are defined. -A _Section header_ for the NAME section is defined. Then the _Name_ of the command and a one-line _Name description_ are defined. -The SYNOPSIS section begins. This section describes the command-line options and arguments accepted. +A _Section header_ for the NAME section is defined. +Then the _Name_ of the command and a one-line _Name description_ are defined. +The SYNOPSIS section begins. +This section describes the command-line options and arguments accepted. _Name_ (`.Nm`) has already been defined, and repeating it here just displays the defined value in the text. -An _Optional_ _Flag_ called `-libxo` is shown. The `Fl` macro adds a dash to the beginning of flags, so this appears in the manual page as `--libxo`. +An _Optional_ _Flag_ called `-libxo` is shown. +The `Fl` macro adds a dash to the beginning of flags, so this appears in the manual page as `--libxo`. A long list of optional single-character flags are shown. -An optional `-D` flag is defined. If the `-D` flag is given, it must be followed by an _Argument_. The argument is a _format_, a string that tells man:ls[1] what to display and how to display it. Details on the format string are given later in the manual page. -A final optional argument is defined. Since no name is specified for the argument, the default of `file ...` is used. +An optional `-D` flag is defined. +If the `-D` flag is given, it must be followed by an _Argument_. +The argument is a _format_, a string that tells man:ls[1] what to display and how to display it. +Details on the format string are given later in the manual page. +A final optional argument is defined. +Since no name is specified for the argument, the default of `file ...` is used. The _Section header_ for the DESCRIPTION section is defined. When rendered with the command `man ls`, the result displayed on the screen looks like this: [.programlisting] .... LS(1) FreeBSD General Commands Manual LS(1) NAME ls - list directory contents SYNOPSIS ls [--libxo] [-ABCFGHILPRSTUWZabcdfghiklmnopqrstuwxy1,] [-D format] [file ...] DESCRIPTION For each operand that names a file of a type other than directory, ls displays its name as well as any requested, associated information. For each operand that names a file of type directory, ls displays the names of files contained within that directory, as well as any requested, associated information. .... Optional values are shown inside square brackets. [[manual-pages-markup-guidelines]] === Markup Guidelines -The man:mdoc[7] markup language is not very strict. For clarity and consistency, the FreeBSD Documentation project adds some additional style guidelines: +The man:mdoc[7] markup language is not very strict. +For clarity and consistency, the FreeBSD Documentation project adds some additional style guidelines: Only the first letter of macros is upper case:: Always use upper case for the first letter of a macro and lower case for the remaining letters. Begin new sentences on new lines:: Start a new sentence on a new line, do not begin it on the same line as an existing sentence. Update `.Dd` when making non-trivial changes to a manual page:: -The _Document date_ informs the reader about the last time the manual page was updated. It is important to update whenever non-trivial changes are made to the manual pages. Trivial changes like spelling or punctuation fixes that do not affect usage can be made without updating `.Dd`. +The _Document date_ informs the reader about the last time the manual page was updated. +It is important to update whenever non-trivial changes are made to the manual pages. +Trivial changes like spelling or punctuation fixes that do not affect usage can be made without updating `.Dd`. Give examples:: -Show the reader examples when possible. Even trivial examples are valuable, because what is trivial to the writer is not necessarily trivial to the reader. Three examples are a good goal. A trivial example shows the minimal requirements, a serious example shows actual use, and an in-depth example demonstrates unusual or non-obvious functionality. +Show the reader examples when possible. +Even trivial examples are valuable, because what is trivial to the writer is not necessarily trivial to the reader. +Three examples are a good goal. +A trivial example shows the minimal requirements, a serious example shows actual use, and an in-depth example demonstrates unusual or non-obvious functionality. Include the BSD license:: -Include the BSD license on new manual pages. The preferred license is available from the link:{committers-guide}[Committer's Guide]. +Include the BSD license on new manual pages. +The preferred license is available from the link:{committers-guide}[Committer's Guide]. [[manual-pages-markup-tricks]] === Markup Tricks Add a space before punctuation on a line with macros. Example: [.programlisting] .... .Sh SEE ALSO .Xr geom 4 , .Xr boot0cfg 8 , .Xr geom 8 , .Xr gptboot 8 .... -Note how the commas at the end of the `.Xr` lines have been placed after a space. The `.Xr` macro expects two parameters to follow it, the name of an external manual page, and a section number. The space separates the punctuation from the section number. Without the space, the external links would incorrectly point to section `4,` or `8,`. +Note how the commas at the end of the `.Xr` lines have been placed after a space. +The `.Xr` macro expects two parameters to follow it, the name of an external manual page, and a section number. +The space separates the punctuation from the section number. +Without the space, the external links would incorrectly point to section `4,` or `8,`. [[manual-pages-markup-important-macros]] === Important Macros -Some very common macros will be shown here. For more usage examples, see man:mdoc[7], man:groff_mdoc[7], or search for actual use in [.filename]#/usr/share/man/man*# directories. For example, to search for examples of the `.Bd`_Begin display_ macro: +Some very common macros will be shown here. +For more usage examples, see man:mdoc[7], man:groff_mdoc[7], or search for actual use in [.filename]#/usr/share/man/man*# directories. +For example, to search for examples of the `.Bd` _Begin display_ macro: [source,shell] .... % find /usr/share/man/man* | xargs zgrep '.Bd' .... [[manual-pages-markup-important-macros-organizational]] ==== Organizational Macros Some macros are used to define logical blocks of a manual page. [.informaltable] [cols="1,8", options="header"] |=== | Organizational Macro | Use |`.Sh` -|Section header. Followed by the name of the section, traditionally all upper case. Think of these as chapter titles. +|Section header. +Followed by the name of the section, traditionally all upper case. +Think of these as chapter titles. |`.Ss` -|Subsection header. Followed by the name of the subsection. Used to divide a `.Sh` section into subsections. +|Subsection header. +Followed by the name of the subsection. +Used to divide a `.Sh` section into subsections. |`.Bl` |Begin list. Start a list of items. |`.El` |End a list. |`.Bd` -|Begin display. Begin a special area of text, like an indented area. +|Begin display. +Begin a special area of text, like an indented area. |`.Ed` |End display. |=== [[manual-pages-markup-important-macros-inline]] ==== Inline Macros Many macros are used to mark up inline text. [.informaltable] [cols="1,8", options="header"] |=== | Inline Macro | Use |`.Nm` -|Name. Called with a name as a parameter on the first use, then used later without the parameter to display the name that has already been defined. +|Name. +Called with a name as a parameter on the first use, then used later without the parameter to display the name that has already been defined. |`.Pa` -|Path to a file. Used to mark up filenames and directory paths. +|Path to a file. +Used to mark up filenames and directory paths. |=== [[manual-pages-sample-structures]] == Sample Manual Page Structures This section shows minimal desired man page contents for several common categories of manual pages. [[manual-pages-sample-structures-section-1-8]] === Section 1 or 8 Command The preferred basic structure for a section 1 or 8 command: [.programlisting] .... .Dd August 25, 2017 .Dt EXAMPLECMD 8 .Os .Sh NAME .Nm examplecmd .Nd "command to demonstrate section 1 and 8 man pages" .Sh SYNOPSIS .Nm .Op Fl v .Sh DESCRIPTION The .Nm utility does nothing except demonstrate a trivial but complete manual page for a section 1 or 8 command. .Sh SEE ALSO .Xr exampleconf 5 .Sh AUTHORS .An Firstname Lastname Aq Mt flastname@example.com .... [[manual-pages-sample-structures-section-4]] === Section 4 Device Driver The preferred basic structure for a section 4 device driver: [.programlisting] .... .Dd August 25, 2017 .Dt EXAMPLEDRIVER 4 .Os .Sh NAME .Nm exampledriver .Nd "driver to demonstrate section 4 man pages" .Sh SYNOPSIS To compile this driver into the kernel, add this line to the kernel configuration file: .Bd -ragged -offset indent .Cd "device exampledriver" .Ed .Pp To load the driver as a module at boot, add this line to .Xr loader.conf 5 : .Bd -literal -offset indent exampledriver_load="YES" .Ed .Sh DESCRIPTION The .Nm driver provides an opportunity to show a skeleton or template file for section 4 manual pages. .Sh HARDWARE The .Nm driver supports these cards from the aptly-named Nonexistent Technologies: .Pp .Bl -bullet -compact .It NT X149.2 (single and dual port) .It NT X149.8 (single port) .El .Sh DIAGNOSTICS .Bl -diag .It "flashing green light" Something bad happened. .It "flashing red light" Something really bad happened. .It "solid black light" Power cord is unplugged. .El .Sh SEE ALSO .Xr example 8 .Sh HISTORY The .Nm device driver first appeared in .Fx 49.2 . .Sh AUTHORS .An Firstname Lastname Aq Mt flastname@example.com .... [[manual-pages-sample-structures-section-5]] === Section 5 Configuration File The preferred basic structure for a section 5 configuration file: [.programlisting] .... .Dd August 25, 2017 .Dt EXAMPLECONF 5 .Os .Sh NAME .Nm example.conf .Nd "config file to demonstrate section 5 man pages" .Sh DESCRIPTION .Nm is an example configuration file. .Sh SEE ALSO .Xr example 8 .Sh AUTHORS .An Firstname Lastname Aq Mt flastname@example.com .... [[manual-pages-testing]] == Testing -Testing a new manual page can be challenging. Fortunately there are some tools that can assist in the task. Some of them, like man:man[1], do not look in the current directory. It is a good idea to prefix the filename with `./` if the new manual page is in the current directory. An absolute path can also be used. +Testing a new manual page can be challenging. +Fortunately there are some tools that can assist in the task. +Some of them, like man:man[1], do not look in the current directory. +It is a good idea to prefix the filename with `./` if the new manual page is in the current directory. +An absolute path can also be used. Use man:mandoc[1]'s linter to check for parsing errors: [source,shell] .... % mandoc -T lint ./mynewmanpage.8 .... Use package:textproc/igor[] to proofread the manual page: [source,shell] .... % igor ./mynewmanpage.8 .... Use man:man[1] to check the final result of your changes: [source,shell] .... % man ./mynewmanpage.8 .... You can use man:col[1] to filter the output of man:man[1] and get rid of the backspace characters before loading the result in your favorite editor for spell checking: [source,shell] .... % man ./mynewmanpage.8 | col -b | vim -R - .... -Spell-checking with fully-featured dictionaries is encouraged, and can be accomplished by using package:textproc/hunspell[] or package:textproc/aspell[] combined with package:textproc/en-hunspell[] or package:textproc/en-aspell[], respectively. For instance: +Spell-checking with fully-featured dictionaries is encouraged, +and can be accomplished by using package:textproc/hunspell[] or package:textproc/aspell[] combined with package:textproc/en-hunspell[] or package:textproc/en-aspell[], respectively. +For instance: [source,shell] .... % aspell check --lang=en --mode=nroff ./mynewmanpage.8 .... [[manual-pages-examples-as-templates]] == Example Manual Pages to Use as Templates Some manual pages are suitable as in-depth examples. [.informaltable] [cols="1,4", options="header"] |=== | Manual Page | Path to Source Location |man:cp[1] |[.filename]#/usr/src/bin/cp/cp.1# |man:vt[4] |[.filename]#/usr/src/share/man/man4/vt.4# |man:crontab[5] |[.filename]#/usr/src/usr.sbin/cron/crontab/crontab.5# |man:gpart[8] |[.filename]#/usr/src/sbin/geom/class/part/gpart.8# |=== [[manual-pages-resources]] == Resources Resources for manual page writers: * man:man[1] * man:mandoc[1] * man:groff_mdoc[7] * http://manpages.bsd.lv/mdoc.html[Practical UNIX Manuals: mdoc] * http://manpages.bsd.lv/history.html[History of UNIX Manpages] diff --git a/documentation/content/en/books/fdp-primer/overview/chapter.adoc b/documentation/content/en/books/fdp-primer/overview/_index.adoc similarity index 69% rename from documentation/content/en/books/fdp-primer/overview/chapter.adoc rename to documentation/content/en/books/fdp-primer/overview/_index.adoc index 2d11df0a1b..dbb08df9ce 100644 --- a/documentation/content/en/books/fdp-primer/overview/chapter.adoc +++ b/documentation/content/en/books/fdp-primer/overview/_index.adoc @@ -1,116 +1,124 @@ --- title: Chapter 1. Overview prev: books/fdp-primer/preface next: books/fdp-primer/tools --- [[overview]] = Overview :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :skip-front-matter: :xrefstyle: basic :relfileprefix: ../ :outfilesuffix: :sectnumoffset: 1 +include::shared/releases.adoc[] +include::shared/en/mailing-lists.adoc[] + toc::[] -Welcome to the FreeBSD Documentation Project (FDP). Quality documentation is crucial to the success of FreeBSD, and we value your contributions very highly. +Welcome to the FreeBSD Documentation Project (FDP). +Quality documentation is crucial to the success of FreeBSD, and we value your contributions very highly. This document describes how the FDP is organized, how to write and submit documentation, and how to effectively use the available tools. -Everyone is welcome to contribute to the FDP. Willingness to contribute is the only membership requirement. +Everyone is welcome to contribute to the FDP. +Willingness to contribute is the only membership requirement. This primer shows how to: * Identify which parts of FreeBSD are maintained by the FDP. * Install the required documentation tools and files. * Make changes to the documentation. * Submit changes back for review and inclusion in the FreeBSD documentation. [[overview-quick-start]] == Quick Start -Some preparatory steps must be taken before editing the FreeBSD documentation. First, subscribe to the {freebsd-doc}. Some team members also interact on the `#bsddocs` IRC channel on http://www.efnet.org/[EFnet]. These people can help with questions or problems involving the documentation. +Some preparatory steps must be taken before editing the FreeBSD documentation. +First, subscribe to the {freebsd-doc}. +Some team members also interact on the `#bsddocs` IRC channel on http://www.efnet.org/[EFnet]. +These people can help with questions or problems involving the documentation. [.procedure] ==== . Install these packages. These packages are all of the software needed to edit and build FreeBSD documentation. The Git package is needed to obtain a working copy of the documentation and generate patches with. + [source,shell] .... # pkg install gohugo python3 git-lite rubygem-asciidoctor rubygem-rouge .... + . Optional: to generate PDF documentation install `asciidoctor-pdf` + [source,shell] .... # pkg install rubygem-asciidoctor-pdf .... + -. Install a local working copy of the documentation from the FreeBSD repository in [.filename]#~/doc# (see <>). +. Install a local working copy of the documentation from the FreeBSD repository in [.filename]#~/doc# (see crossref:working-copy[working-copy,The Working Copy]). + [source,shell] .... -% git clone https://git.FreeBSD.org/doc.git doc +% git clone https://git.FreeBSD.org/doc.git ~/doc .... + -. Configure the text editor: - -** Tab stops set to 2. -** Replace each group of 8 leading spaces with a single tab. -+ -Specific editor configurations are listed in <>. -+ . Edit the documentation files that require changes. If a file needs major changes, consult the mailing list for input. + -Review the output and edit the file to fix any problems shown, then rerun the command to find any remaining problems. Repeat until all of the errors are resolved. +Review the output and edit the file to fix any problems shown, then rerun the command to find any remaining problems. +Repeat until all of the errors are resolved. + -. _Always_ build-test changes before submitting them. Running `make` in the top-level directory of the documentation will generate that documentation in HTML format. +. *_Always_* build and test the changes before submitting them. Running `make` in the top-level directory of the documentation will generate that documentation in HTML format. + [source,shell] .... make .... + . When changes are complete and tested, generate a "diff file": + [source,shell] .... % cd ~/doc % git diff > bsdinstall.diff.txt .... + -Give the diff file a descriptive name. In the example above, changes have been made to the [.filename]#bsdinstall# portion of the Handbook. +Give the diff file a descriptive name. +In the example above, changes have been made to the [.filename]#bsdinstall# portion of the Handbook. . Submit the diff file using the web-based https://bugs.FreeBSD.org/bugzilla/enter_bug.cgi?product=Documentation[Problem Report] system. If using the web form, enter a Summary of _[patch] short description of problem_. Select the Component `Documentation`. In the Description field, enter a short description of the changes and any important details about them. Use the btn:[Add an attachment] button to attach the diff file. Finally, use the btn:[Submit Bug] button to submit your diff to the problem report system. ==== [[overview-doc]] == The FreeBSD Documentation Set The FDP is responsible for four categories of FreeBSD documentation. * _Handbook_: The Handbook is the comprehensive online resource and reference for FreeBSD users. * _FAQ_: The FAQ uses a short question and answer format to address questions that are frequently asked on the various mailing lists and forums devoted to FreeBSD. This format does not permit long and comprehensive answers. * _Manual pages_: The English language system manual pages are usually not written by the FDP, as they are part of the base system. However, the FDP can reword parts of existing manual pages to make them clearer or to correct inaccuracies. * _Web site_: This is the main FreeBSD presence on the web, visible at https://www.freebsd.org/[https://www.FreeBSD.org/] and many mirrors around the world. The web site is typically a new user's first exposure to FreeBSD. -Translation teams are responsible for translating the Handbook and web site into different languages. Manual pages are not translated at present. +Translation teams are responsible for translating the Handbook and web site into different languages. +Manual pages are not translated at present. Documentation source for the FreeBSD web site, Handbook, and FAQ is available in the documentation repository at `https://cgit.freebsd.org/doc/`. Source for manual pages is available in a separate source repository located at `https://cgit.freebsd.org/src/`. -Documentation commit messages are visible with `git log`. Commit messages are also archived at link:{git-doc-all}. +Documentation commit messages are visible with `git log`. +Commit messages are also archived at link:{git-doc-all}. Web frontends to both of these repositories are available at https://cgit.freebsd.org/doc/[] and https://cgit.freebsd.org/src/[]. -Many people have written tutorials or how-to articles about FreeBSD. Some are stored as part of the FDP files. In other cases, the author has decided to keep the documentation separate. The FDP endeavors to provide links to as much of this external documentation as possible. +Many people have written tutorials or how-to articles about FreeBSD. +Some are stored as part of the FDP files. +In other cases, the author has decided to keep the documentation separate. +The FDP endeavors to provide links to as much of this external documentation as possible. diff --git a/documentation/content/en/books/fdp-primer/po-translations/chapter.adoc b/documentation/content/en/books/fdp-primer/po-translations/_index.adoc similarity index 70% rename from documentation/content/en/books/fdp-primer/po-translations/chapter.adoc rename to documentation/content/en/books/fdp-primer/po-translations/_index.adoc index 4a7650cd25..d3625a19ff 100644 --- a/documentation/content/en/books/fdp-primer/po-translations/chapter.adoc +++ b/documentation/content/en/books/fdp-primer/po-translations/_index.adoc @@ -1,386 +1,414 @@ --- title: Chapter 9. PO Translations prev: books/fdp-primer/translations next: books/fdp-primer/manual-pages --- [[po-translations]] = PO Translations :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :skip-front-matter: :xrefstyle: basic :relfileprefix: ../ :outfilesuffix: :sectnumoffset: 9 include::shared/en/urls.adoc[] toc::[] [[po-translations-introduction]] == Introduction -The http://www.gnu.org/software/gettext/[GNU gettext] system offers translators an easy way to create and maintain translations of documents. Translatable strings are extracted from the original document into a PO (Portable Object) file. Translated versions of the strings are entered with a separate editor. The strings can be used directly or built into a complete translated version of the original document. +The http://www.gnu.org/software/gettext/[GNU gettext] system offers translators an easy way to create and maintain translations of documents. +Translatable strings are extracted from the original document into a PO (Portable Object) file. +Translated versions of the strings are entered with a separate editor. +The strings can be used directly or built into a complete translated version of the original document. [[po-translations-quick-start]] == Quick Start -The procedure shown in <> is assumed to have already been performed. The `TRANSLATOR` option is required and already enabled by default in the package:textproc/docproj[] port. +The procedure shown in crossref:overview[overview-quick-start,Quick Start] is assumed to have already been performed. +The `TRANSLATOR` option is required and already enabled by default in the package:textproc/docproj[] port. This example shows the creation of a Spanish translation of the short link:{leap-seconds}[Leap Seconds] article. [[po-translations-quick-start-install-po-editor]] [.procedure] ==== .Procedure: Install a PO Editor . A PO editor is needed to edit translation files. This example uses package:editors/poedit[]. + [source,shell] .... # cd /usr/ports/editors/poedit # make install clean .... ==== [[po-translations-quick-start-initial-setup]] [.procedure] ==== .Procedure: Initial Setup When a new translation is first created, the directory structure must be created or copied from the English original: -. Create a directory for the new translation. The English article source is in [.filename]#~/doc/en/articles/leap-seconds/#. The Spanish translation will go in [.filename]#~/doc/es/articles/leap-seconds/#. The path is the same except for the name of the language directory. +. Create a directory for the new translation. +The English article source is in [.filename]#~/doc/en/articles/leap-seconds/#. +The Spanish translation will go in [.filename]#~/doc/es/articles/leap-seconds/#. +The path is the same except for the name of the language directory. + [source,shell] .... % mkdir ~/doc/es/articles/leap-seconds/ .... . Copy the [.filename]#_index.adoc# from the original document into the translation directory: + [source,shell] .... % cp ~/doc/en/articles/leap-seconds/_index.adoc \ ~/doc/es/articles/leap-seconds/ .... ==== [[po-translations-quick-start-translation]] [.procedure] ==== .Procedure: Translation -Translating a document consists of two steps: extracting translatable strings from the original document, and entering translations for those strings. These steps are repeated until the translator feels that enough of the document has been translated to produce a usable translated document. +Translating a document consists of two steps: extracting translatable strings from the original document, and entering translations for those strings. +These steps are repeated until the translator feels that enough of the document has been translated to produce a usable translated document. . Extract the translatable strings from the original English version into a PO file: + [source,shell] .... % cd ~/doc/es/articles/leap-seconds/ % po4a-gettextize --format asciidoc --master _index.adoc --master-charset "UTF-8" >> es.pot .... + . Use a PO editor to enter translations in the PO file. There are several different editors available. [.filename]#poedit# from package:editors/poedit[] is shown here. + -The PO file name is the language region code. For Spanish, the file name is [.filename]#es.po#. +The PO file name is the language region code. +For Spanish, the file name is [.filename]#es.po#. + [source,shell] .... % poedit es.po .... ==== [[po-translations-quick-generating-a-translated-document]] [.procedure] ==== .Procedure: Generating a Translated Document . Generate the translated document: + [source,shell] .... % cd ~/doc/es/articles/leap-seconds/ % po4a-translate -f asciidoc -m document.po -l document.po --keep 0 -p es.po -M UTF-8 .... + The name of the generated document matches the name of the English original, usually [.filename]#_index.adoc#. + . Check the generated file by rendering it to HTML and viewing it with a web browser: + [source,shell] .... % make .... ==== [[po-translations-creating]] == Creating New Translations -The first step to creating a new translated document is locating or creating a directory to hold it. FreeBSD puts translated documents in a subdirectory named for their language and region in the format [.filename]#lang#. _lang_ is a two-character lowercase code. +The first step to creating a new translated document is locating or creating a directory to hold it. +FreeBSD puts translated documents in a subdirectory named for their language and region in the format [.filename]#lang#. +_lang_ is a two-character lowercase code. [[po-translations-language-names]] .Language Names [cols="1,1,1,1", frame="none", options="header"] |=== | Language | Region | Translated Directory Name | PO File Name |English |United States |[.filename]#en# |[.filename]#en.po# |Bengali |Bangladesh |[.filename]#bn# |[.filename]#bn.po# |Danish |Denmark |[.filename]#da# |[.filename]#da.po# |German |Germany |[.filename]#de# |[.filename]#de.po# |Greek |Greece |[.filename]#el# |[.filename]#el.po# |Spanish |Spain |[.filename]#es# |[.filename]#es.po# |French |France |[.filename]#fr# |[.filename]#fr.po# |Hungarian |Hungary |[.filename]#hu# |[.filename]#hu.po# |Italian |Italy |[.filename]#it# |[.filename]#it.po# |Japanese |Japan |[.filename]#ja# |[.filename]#ja.po# |Korean |Korea |[.filename]#ko# |[.filename]#ko.po# |Mongolian |Mongolia |[.filename]#mn# |[.filename]#mn.po# |Dutch |Netherlands |[.filename]#nl# |[.filename]#nl.po# |Polish |Poland |[.filename]#pl# |[.filename]#pl.po# |Portuguese |Brazil -|[.filename]#pt_BR# -|[.filename]#pt_BR.po# +|[.filename]#pt-br# +|[.filename]#pt-br.po# |Russian |Russia |[.filename]#ru# |[.filename]#ru.po# |Turkish |Turkey |[.filename]#tr# |[.filename]#tr.po# |Chinese |China -|[.filename]#zh_CN# -|[.filename]#zh_CN.po# +|[.filename]#zh-cn# +|[.filename]#zh-cn.po# |Chinese |Taiwan -|[.filename]#zh_TW# -|[.filename]#zh_TW.po# +|[.filename]#zh-tw# +|[.filename]#zh-tw.po# |=== -The translations are in subdirectories of the main documentation directory, here assumed to be [.filename]#~/doc/# as shown in <>. For example, German translations are located in [.filename]#~/doc/de/#, and French translations are in [.filename]#~/doc/fr/#. +The translations are in subdirectories of the main documentation directory, +here assumed to be [.filename]#~/doc/# as shown in crossref:overview[overview-quick-start,Quick Start]. +For example, German translations are located in [.filename]#~/doc/de/#, and French translations are in [.filename]#~/doc/fr/#. Each language directory contains separate subdirectories named for the type of documents, usually [.filename]#articles/# and [.filename]#books/#. -Combining these directory names gives the complete path to an article or book. For example, the French translation of the NanoBSD article is in [.filename]#~/doc/fr/articles/nanobsd/#, and the Mongolian translation of the Handbook is in [.filename]#~/doc/mn/books/handbook/#. +Combining these directory names gives the complete path to an article or book. +For example, the French translation of the NanoBSD article is in [.filename]#~/doc/fr/articles/nanobsd/#, +and the Mongolian translation of the Handbook is in [.filename]#~/doc/mn/books/handbook/#. -A new language directory must be created when translating a document to a new language. If the language directory already exists, only a subdirectory in the [.filename]#articles/# or [.filename]#books/# directory is needed. +A new language directory must be created when translating a document to a new language. +If the language directory already exists, only a subdirectory in the [.filename]#articles/# or [.filename]#books/# directory is needed. [[po-translations-creating-example]] .Creating a Spanish Translation of the Porter's Handbook [example] ==== -Create a new Spanish translation of the link:{porters-handbook}[Porter's Handbook]. The original is a book in [.filename]#~/doc/en/books/porters-handbook/#. +Create a new Spanish translation of the link:{porters-handbook}[Porter's Handbook]. +The original is a book in [.filename]#~/doc/en/books/porters-handbook/#. [.procedure] ====== . The Spanish language books directory [.filename]#~/doc/es/books/# already exists, so only a new subdirectory for the Porter's Handbook is needed: + [source,shell] .... % cd ~/doc/es/books/ % mkdir porters-handbook .... . Copy the content from the original book: + [source,shell] .... % cd ~/doc/es/books/porters-handbook % cp ~/doc/en/books/porters-handbook/ . .... + Now the document structure is ready for the translator to begin translating with `po4a` command. ====== ==== [[po-translations-translating]] == Translating -The gettext system greatly reduces the number of things that must be tracked by a translator. Strings to be translated are extracted from the original document into a PO file. Then a PO editor is used to enter the translated versions of each string. +The gettext system greatly reduces the number of things that must be tracked by a translator. +Strings to be translated are extracted from the original document into a PO file. +Then a PO editor is used to enter the translated versions of each string. The FreeBSD PO translation system does not overwrite PO files, so the extraction step can be run at any time to update the PO file. -A PO editor is used to edit the file. package:editors/poedit[] is shown in these examples because it is simple and has minimal requirements. Other PO editors offer features to make the job of translating easier. The Ports Collection offers several of these editors, including package:devel/gtranslator[]. +A PO editor is used to edit the file. +package:editors/poedit[] is shown in these examples because it is simple and has minimal requirements. +Other PO editors offer features to make the job of translating easier. +The Ports Collection offers several of these editors, including package:devel/gtranslator[]. -It is important to preserve the PO file. It contains all of the work that translators have done. +It is important to preserve the PO file. +It contains all of the work that translators have done. [[po-translations-translating-example]] .Translating the Porter's Handbook to Spanish [example] ==== Enter Spanish translations of the contents of the Porter's Handbook. [.procedure] ====== . Change to the Spanish Porter's Handbook directory and update the PO file. The generated PO file is called [.filename]#es_ES.po# as shown in <>. + [source,shell] .... % cd ~/doc/es/books/porters-handbook % po4a-gettextize --format asciidoc --master _index.adoc --master-charset "UTF-8" >> es.pot .... . Enter translations using a PO editor: + [source,shell] .... % poedit es.pot .... ====== ==== [[po-translations-tips]] == Tips for Translators [[po-translations-tips-xmltags]] === Preserving AsciiDoc macros Preserve AsciiDoc macros that are shown in the English original. .Preserving AsciiDoc macros [example] ==== English original: [.programlisting] .... msgid "" "This example shows the creation of a Spanish translation of the short " "link:{leap-seconds}[Leap Seconds] article." .... Spanish translation: [.programlisting] .... msgid "" "Este ejemplo muestra la creación de un artículo con poco contenido como el artículo " "link:{leap-seconds}[Leap Seconds]." .... ==== [[po-translations-tips-spaces]] === Preserving Spaces -Preserve existing spaces at the beginning and end of strings to be translated. The translated version must have these spaces also. +Preserve existing spaces at the beginning and end of strings to be translated. +The translated version must have these spaces also. [[po-translations-tips-verbatim]] === Verbatim Tags The contents of some tags should be copied verbatim, not translated: * `man:man[1]` * `package:package[]` * `link` * `image` * `include` * `Admonitions` * `id's` * `Heading tags` * `source` [[po-translations-building]] == Building a Translated Document -A translated version of the original document can be created at any time. Any untranslated portions of the original will be included in English in the resulting document. Most PO editors have an indicator that shows how much of the translation has been completed. This makes it easy for the translator to see when enough strings have been translated to make building the final document worthwhile. +A translated version of the original document can be created at any time. +Any untranslated portions of the original will be included in English in the resulting document. +Most PO editors have an indicator that shows how much of the translation has been completed. +This makes it easy for the translator to see when enough strings have been translated to make building the final document worthwhile. [[po-translations-submitting]] == Submitting the New Translation -Prepare the new translation files for submission. This includes adding the files to the version control system, setting additional properties on them, then creating a diff for submission. +Prepare the new translation files for submission. +This includes adding the files to the version control system, setting additional properties on them, then creating a diff for submission. The diff files created by these examples can be attached to a https://bugs.freebsd.org/bugzilla/enter_bug.cgi?product=Documentation[documentation bug report] or https://reviews.freebsd.org/[code review]. [[po-translations-submitting-spanish]] .Spanish Translation of the NanoBSD Article [example] ==== [.procedure] ====== . Create a diff of the new files from the [.filename]#~/doc/# base directory so the full path is shown with the filenames. This helps committers identify the target language directory. + [source,shell] .... % cd ~/doc % git diff es/articles/nanobsd/ > /tmp/es_nanobsd.diff .... ====== ==== diff --git a/documentation/content/en/books/fdp-primer/preface/chapter.adoc b/documentation/content/en/books/fdp-primer/preface/_index.adoc similarity index 90% rename from documentation/content/en/books/fdp-primer/preface/chapter.adoc rename to documentation/content/en/books/fdp-primer/preface/_index.adoc index bfa45deae5..f1ce0a6516 100644 --- a/documentation/content/en/books/fdp-primer/preface/chapter.adoc +++ b/documentation/content/en/books/fdp-primer/preface/_index.adoc @@ -1,128 +1,131 @@ --- title: Preface prev: books/fdp-primer/ next: books/fdp-primer/overview --- [preface] [[preface]] = Preface :doctype: book :toc: macro :toclevels: 1 :icons: font :source-highlighter: rouge :experimental: :skip-front-matter: :xrefstyle: basic :relfileprefix: ../ :outfilesuffix: [[preface-prompts]] == Shell Prompts -This table shows the default system prompt and superuser prompt. The examples use these prompts to indicate which type of user is running the example. +This table shows the default system prompt and superuser prompt. +The examples use these prompts to indicate which type of user is running the example. [.informaltable] [cols="1,2", frame="none", options="header"] |=== | User | Prompt |Normal user |% |`root` |# |=== [[preface-conventions]] == Typographic Conventions This table describes the typographic conventions used in this book. [.informaltable] [cols="1,2", frame="none", options="header"] |=== | Meaning | Examples |The names of commands. |Use `ls -l` to list all files. |The names of files. |Edit [.filename]#.login#. |On-screen computer output. a| [source,shell] .... You have mail. .... |What the user types, contrasted with on-screen computer output. a| [source,shell] .... % date +"The time is %H:%M" The time is 09:18 .... |Manual page references. |Use man:su[1] to change user identity. |User and group names. |Only `root` can do this. |Emphasis. |The user _must_ do this. |Text that the user is expected to replace with the actual text. |To search for a keyword in the manual pages, type `man -k _keyword_` |Environment variables. |`$HOME` is set to the user's home directory. |=== [[preface-notes]] == Notes, Tips, Important Information, Warnings, and Examples Notes, warnings, and examples appear within the text. [NOTE] ==== Notes are represented like this, and contain information to take note of, as it may affect what the user does. ==== [TIP] ==== Tips are represented like this, and contain information helpful to the user, such as showing an easier way to do something. ==== [IMPORTANT] ==== -Important information is represented like this. Typically, these show extra steps the user may need to take. +Important information is represented like this. +Typically, these show extra steps the user may need to take. ==== [WARNING] ==== -Warnings are represented like this, and contain information warning about possible damage if the instructions are not followed. This damage may be physical, to the hardware or the user, or it may be non-physical, such as the inadvertent deletion of important files. +Warnings are represented like this, and contain information warning about possible damage if the instructions are not followed. +This damage may be physical, to the hardware or the user, or it may be non-physical, such as the inadvertent deletion of important files. ==== .A Sample Example [example] ==== Examples are represented like this, and typically contain examples showing a walkthrough, or the results of a particular action. ==== [[preface-acknowledgements]] == Acknowledgments My thanks to Sue Blake, Patrick Durusau, Jon Hamilton, Peter Flynn, and Christopher Maden, who took the time to read early drafts of this document and offer many valuable comments and criticisms. diff --git a/documentation/content/en/books/fdp-primer/rosetta/chapter.adoc b/documentation/content/en/books/fdp-primer/rosetta/_index.adoc similarity index 99% rename from documentation/content/en/books/fdp-primer/rosetta/chapter.adoc rename to documentation/content/en/books/fdp-primer/rosetta/_index.adoc index 68ff034429..3a716db03f 100644 --- a/documentation/content/en/books/fdp-primer/rosetta/chapter.adoc +++ b/documentation/content/en/books/fdp-primer/rosetta/_index.adoc @@ -1,291 +1,291 @@ --- title: Chapter 7. Rosetta Stone prev: books/fdp-primer/asciidoctor-primer next: books/fdp-primer/translations --- [[rosetta]] = Rosetta Stone :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :skip-front-matter: :xrefstyle: basic :relfileprefix: ../ :outfilesuffix: :sectnumoffset: 7 toc::[] [[docbook-vs-asciidoc]] == Comparison between Docbook and AsciiDoc This rosetta stone tries to show the differences between Docbook and AsciiDoc. .Comparision between Docbook and AsciiDoc [cols="1,4,4"] |=== |Language Feature |Docbook | AsciiDoc |*Bold* |bold |\*bold* |*Italic* |Italic |\_Italic_ |*Monospace* |Monospace |\`Monospace` |*Paragraph* |This is a paragraph |This is a paragraph |*Keycap* |F11 |\kbd:[F11] |*Links* a| [source,xml] ---- Download FreeBSD ---- a| [source] ---- link:https://www.freebsd.org/where/[Download FreeBSD] ---- |*Sections* a| [source,xml] ---- Section 1 ---- a| [source] ---- [[id]] -= Section 1 +\= Section 1 ---- |*Unordered list* a| [source,xml] ---- When to build a custom kernel. How to take a hardware inventory. ---- a| [source] ---- * When to build a custom kernel. * How to take a hardware inventory. ---- |*Ordered list* a| [source,xml] ---- One Two Three Four ---- a| [source] ---- . One . Two . Three . Four ---- |*Variable list* a| [source,xml] ---- amd64 This is the most common desktop... ---- a| [source] ---- amd64:: This is the most common desktop... ---- |*Source code* a| [source,xml] ---- &prompt.root; mkdir -p /var/spool/lpd/lp ---- a| [source] .... [source,shell] ---- # mkdir -p /var/spool/lpd/lp ---- .... |*Literal block* a| [source,xml] ---- include GENERIC ident MYKERNEL options IPFIREWALL options DUMMYNET options IPFIREWALL_DEFAULT_TO_ACCEPT options IPDIVERT ---- a| [source] ---- .... include GENERIC ident MYKERNEL options IPFIREWALL options DUMMYNET options IPFIREWALL_DEFAULT_TO_ACCEPT options IPDIVERT .... ---- |*Images* a| [source,xml] ----
FreeBSD Boot Loader Menu ASCII art replacement is no longer supported. The FreeBSD loader menu, with options 1-6 to boot multi-user, boot single user, escape to loader prompt, reboot, select a kernel to load, and select boot options
---- a| [source] ---- [[bsdinstall-newboot-loader-menu]] .FreeBSD Boot Loader Menu image::bsdinstall/bsdinstall-newboot-loader-menu[The FreeBSD loader menu, with options 1-6 to boot multi-user, boot single user, escape to loader prompt, reboot, select a kernel to load, and select boot options] ---- |*Includes* |n/a a| [source] ---- \include::chapter.adoc[] ---- |*Tables* a| [source,xml] ---- Partitioning Schemes Abbreviation Description APM Apple Partition Map, used by PowerPC(R).
---- a| [source] ---- [[partition-schemes]] .Partitioning Schemes [cols="1,1", frame="none", options="header"] \|=== \| Abbreviation \| Description \|APM \|Apple Partition Map, used by PowerPC(R). \|=== ---- |*Admonitions* a| [source,xml] ---- This is a tip ---- a| [source] ---- [TIP] ==== This is a tip ==== ---- |=== diff --git a/documentation/content/en/books/fdp-primer/see-also/chapter.adoc b/documentation/content/en/books/fdp-primer/see-also/_index.adoc similarity index 87% rename from documentation/content/en/books/fdp-primer/see-also/chapter.adoc rename to documentation/content/en/books/fdp-primer/see-also/_index.adoc index 4872b32cc9..6ab1433f4b 100644 --- a/documentation/content/en/books/fdp-primer/see-also/chapter.adoc +++ b/documentation/content/en/books/fdp-primer/see-also/_index.adoc @@ -1,45 +1,46 @@ --- title: Chapter 13. See Also prev: books/fdp-primer/editor-config/ next: books/fdp-primer/examples --- [[see-also]] = See Also :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :skip-front-matter: :xrefstyle: basic :relfileprefix: ../ :outfilesuffix: :sectnumoffset: 13 include::shared/en/urls.adoc[] toc::[] -This document is deliberately not an exhaustive discussion of AsciiDoc and the FreeBSD Documentation Project. For more information about these, you are encouraged to see the following web sites. +This document is deliberately not an exhaustive discussion of AsciiDoc and the FreeBSD Documentation Project. +For more information about these, you are encouraged to see the following web sites. [[see-also-fdp]] == The FreeBSD Documentation Project * link:https://www.FreeBSD.org/docproj/[The FreeBSD Documentation Project web pages] * link:{handbook}[The FreeBSD Handbook] [[see-also-asciidoc]] == AsciiDoctor * link:https://asciidoctor.org/[AsciiDoctor] [[see-also-html]] == HTML * link:http://www.w3.org/[The World Wide Web Consortium] * link:https://dev.w3.org/html5/spec-LC/[The HTML 5 specification] * link:https://www.w3.org/Style/CSS/specs.en.html[CSS specification] diff --git a/documentation/content/en/books/fdp-primer/structure/chapter.adoc b/documentation/content/en/books/fdp-primer/structure/_index.adoc similarity index 61% rename from documentation/content/en/books/fdp-primer/structure/chapter.adoc rename to documentation/content/en/books/fdp-primer/structure/_index.adoc index 5c42cd0cc0..2f190b6dd2 100644 --- a/documentation/content/en/books/fdp-primer/structure/chapter.adoc +++ b/documentation/content/en/books/fdp-primer/structure/_index.adoc @@ -1,217 +1,247 @@ --- title: Chapter 4. Documentation Directory Structure prev: books/fdp-primer/working-copy next: books/fdp-primer/doc-build --- [[structure]] = Documentation Directory Structure :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :skip-front-matter: :xrefstyle: basic :relfileprefix: ../ :outfilesuffix: :sectnumoffset: 4 toc::[] Files and directories in the [.filename]#doc/# tree follow a structure meant to: . Make it easy to automate converting the document to other formats. . Promote consistency between the different documentation organizations, to make it easier to switch between working on different documents. . Make it easy to decide where in the tree new documentation should be placed. -In addition, the documentation tree must accommodate documents in many different languages. It is important that the documentation tree structure does not enforce any particular defaults or cultural preferences. +In addition, the documentation tree must accommodate documents in many different languages. +It is important that the documentation tree structure does not enforce any particular defaults or cultural preferences. [[structure-top]] == The Top Level, doc/ There are three sections under [.filename]#doc/#, documentation and website share the same structure. [cols="20%,80%", frame="none", options="header"] |=== | Directory | Usage |[.filename]#documentation# -|Contains all the articles and books in AsciiDoc format. Contains subdirectories to further categorize the information by languages. +|Contains all the articles and books in AsciiDoc format. +Contains subdirectories to further categorize the information by languages. |[.filename]#shared# -|Contains files that are not specific to the various translations of the documentation. Contains subdirectories to further categorize the information by languages and three files to store the authors, releases and mirrors information. This directory is shared between `documentation` and the `website`. +|Contains files that are not specific to the various translations of the documentation. +Contains subdirectories to further categorize the information by languages and three files to store the authors, releases and mirrors information. +This directory is shared between `documentation` and the `website`. |[.filename]#website# -|Contains the link:https://www.FreeBSD.org[FreeBSD website] in AsciiDoc format. Contains subdirectories to further categorize the information by languages. +|Contains the link:https://www.FreeBSD.org[FreeBSD website] in AsciiDoc format. +Contains subdirectories to further categorize the information by languages. |=== [[structure-locale]] == The Directories -These directories contain the documentation and the website. The documentation is organized into subdirectories below this level, following the link:https://gohugo.io/getting-started/directory-structure/[Hugo directory structure]. +These directories contain the documentation and the website. +The documentation is organized into subdirectories below this level, following the link:https://gohugo.io/getting-started/directory-structure/[Hugo directory structure]. [cols="20%,80%", frame="none", options="header"] |=== | Directory | Usage |[.filename]#archetypes# -|Contain templates to create new articles, books and webpages. For more information take a look link:https://gohugo.io/content-management/archetypes/[here]. +|Contain templates to create new articles, books and webpages. +For more information take a look link:https://gohugo.io/content-management/archetypes/[here]. |[.filename]#config# -|Contain the Hugo configuration files. One main file and one file per language. For more information take a look link:https://gohugo.io/getting-started/configuration/[here]. +|Contain the Hugo configuration files. +One main file and one file per language. +For more information take a look link:https://gohugo.io/getting-started/configuration/[here]. |[.filename]#content# -|Contain the books, articles and webpages. One directory exists for each available translation of the documentation, for example `en` and `zh_TW`. +|Contain the books, articles and webpages. +One directory exists for each available translation of the documentation, for example `en` and `zh-tw`. | [.filename]#data# -| Contain custom data for build the website in link:https://en.wikipedia.org/wiki/TOML[TOML] format. This directory is used to store the events, news, press, etc. For more information take a look link:https://gohugo.io/templates/data-templates/[here]. +| Contain custom data for build the website in link:https://en.wikipedia.org/wiki/TOML[TOML] format. +This directory is used to store the events, news, press, etc. +For more information take a look link:https://gohugo.io/templates/data-templates/[here]. | [.filename]#static# -| Contain static assets. Images, security advisories, the pgpkeys, etc. For more information take a look link:https://gohugo.io/content-management/static-files/[here]. +| Contain static assets. +Images, security advisories, the pgpkeys, etc. +For more information take a look link:https://gohugo.io/content-management/static-files/[here]. | [.filename]#themes# -| Contain the templates in the form of `.html` files that specify how the website looks. For more information take a look link:https://gohugo.io/templates/[here]. +| Contain the templates in the form of `.html` files that specify how the website looks. +For more information take a look link:https://gohugo.io/templates/[here]. | [.filename]#tools# -| Contain tools used to enhance the documentation build. For example to generate the Table of Contents of the books, etc. +| Contain tools used to enhance the documentation build. +For example to generate the Table of Contents of the books, etc. | [.filename]#beastie.png# | This image doesn't need an introduction ;) | [.filename]#LICENSE# | License of the documentation, shared and website. BSD 2-Clause License. | [.filename]#Makefile# | The [.filename]#Makefile# defines the build process of the documentation and the website. |=== [[structure-document]] == Document-Specific Information This section contains specific notes about particular documents managed by the FDP. [[structure-document-books]] == The Books: books/ The books are written in AsciiDoc. -The books are organized as an AsciiDoc `book`. The books are divided into ``part``s, each of which contains several ``chapter``s. ``chapter``s are further subdivided into sections (`=`) and subsections (`==`, `===`) and so on. +The books are organized as an AsciiDoc `book`. +The books are divided into ``part``s, each of which contains several ``chapter``s. +``chapter``s are further subdivided into sections (`=`) and subsections (`==`, `===`) and so on. [[structure-document-books-physical]] === Physical Organization There are a number of files and directories within the books directory, all with the same structure. [[structure-document-books-physical-index]] ==== _index.adoc The [.filename]#_index.adoc# defines some AsciiDoc variables that affect how the AsciiDoc source is converted to other formats and list the Table of Contents, Table of Examples, Table of Figures, Table of Tables and the abstract section. [[structure-document-books-physical-book]] ==== book.adoc -The [.filename]#_index.adoc# defines some AsciiDoc variables that affect how the AsciiDoc source is converted to other formats and list the Table of Contents, Table of Examples, Table of Figures, Table of Tables, the abstract section and all the chapters. This file is used to generate the PDF with `asciidoctor-pdf` and to generate the book in one `html` page. +The [.filename]#_index.adoc# defines some AsciiDoc variables that affect how the AsciiDoc source is converted to other formats and list the Table of Contents, Table of Examples, Table of Figures, Table of Tables, the abstract section and all the chapters. +This file is used to generate the PDF with `asciidoctor-pdf` and to generate the book in one `html` page. [[structure-document-books-physical-part]] ==== part*.adoc The [.filename]#part*.adoc# files stores a brief introduction of one part of the book. [[structure-document-books-physical-toc]] ==== toc*.adoc -The [.filename]#toc*.adoc# files stores the Table of Contents, Table of Figures, Table of Examples, Table of Tables and different Table of Contents for each part. All of these files are generated by the Python `tools`. *Please don't edit them.* +The [.filename]#toc*.adoc# files stores the Table of Contents, Table of Figures, Table of Examples, Table of Tables and different Table of Contents for each part. +All of these files are generated by the Python `tools`. +*Please don't edit them.* [[structure-document-books-physical-chapters-order]] ==== chapters-order.adoc The [.filename]#chapters-order.adoc# file stores the order of the book chapters. [IMPORTANT] ==== -Please be careful with this file. It is used by the Python `tools` to generate the Table of Contents of the books. In case of editing this file, first contact the mailto:doceng@freebsd.org[Documentation Engineering] team. +Please be careful with this file. +It is used by the Python `tools` to generate the Table of Contents of the books. +In case of editing this file, first contact the mailto:doceng@freebsd.org[Documentation Engineering] team. ==== [[structure-document-handbook-physical-chapters]] ==== directory/_index.adoc Each chapter in the Handbook is stored in a file called [.filename]#_index.adoc# in a separate directory from the other chapters. For example, this is an example of the header of one chapter: [.programlisting] .... --- 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 +\= Configuring the FreeBSD Kernel <.> ... .... +<.> The character at the end of the line should not be used in a production document. +This character is here to skip this title in the autogenerated [.filename]#toc-*.adoc# files. + When the HTML5 version of the Handbook is produced, this will yield [.filename]#kernelconfig/index.html#. A brief look will show that there are many directories with individual [.filename]#_index.adoc# files, including [.filename]#basics/_index.adoc#, [.filename]#introduction/_index.adoc#, and [.filename]#printing/_index.xml#. [IMPORTANT] ==== -Do not name chapters or directories after their ordering within the Handbook. This ordering can change as the content within the Handbook is reorganized. Reorganization should be possible without renaming files, unless entire chapters are being promoted or demoted within the hierarchy. +Do not name chapters or directories after their ordering within the Handbook. +This ordering can change as the content within the Handbook is reorganized. +Reorganization should be possible without renaming files, unless entire chapters are being promoted or demoted within the hierarchy. ==== -DIFFERENT TOCS - [[structure-document-articles]] == The Articles: articles/ The articles are written in AsciiDoc. -The articles are organized as an AsciiDoc `article`. The articles are divided into sections (`=`) and subsections (`==`, `===`) and so on. +The articles are organized as an AsciiDoc `article`. +The articles are divided into sections (`=`) and subsections (`==`, `===`) and so on. [[structure-document-articles-physical]] === Physical Organization There is one [.filename]#_index.adoc# file per article. [[structure-document-articles-physical-index]] ==== _index.adoc The [.filename]#_index.adoc# file contains all the AsciiDoc variables and the content. For example, this is an example of one article, the structure is pretty similar to one book chapter: [.programlisting] .... --- title: Why you should use a BSD style license for your Open Source Project authors: - author: Bruce Montague email: brucem@alumni.cse.ucsc.edu releaseinfo: "$FreeBSD$" trademarks: ["freebsd", "intel", "general"] --- -\= Why you should use a BSD style license for your Open Source Project +\= Why you should use a BSD style license for your Open Source Project <1> :doctype: article :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: ''' toc::[] [[intro]] -\== Introduction +\== Introduction <1> .... + +<1> The character at the end of the line should not be used in a production document. +This character is here to skip this title in the autogenerated [.filename]#toc-*.adoc# files. diff --git a/documentation/content/en/books/fdp-primer/tools/chapter.adoc b/documentation/content/en/books/fdp-primer/tools/_index.adoc similarity index 59% rename from documentation/content/en/books/fdp-primer/tools/chapter.adoc rename to documentation/content/en/books/fdp-primer/tools/_index.adoc index a4df2e8fc6..87f35747ac 100644 --- a/documentation/content/en/books/fdp-primer/tools/chapter.adoc +++ b/documentation/content/en/books/fdp-primer/tools/_index.adoc @@ -1,44 +1,49 @@ --- title: Chapter 2. Tools prev: books/fdp-primer/overview next: books/fdp-primer/working-copy --- [[tools]] = Tools :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :skip-front-matter: :xrefstyle: basic :relfileprefix: ../ :outfilesuffix: :sectnumoffset: 2 toc::[] -Several software tools are used to manage the FreeBSD documentation and render it to different output formats. Some of these tools are required and must be installed before working through the examples in the following chapters. Some are optional, adding capabilities or making the job of creating documentation less demanding. +Several software tools are used to manage the FreeBSD documentation and render it to different output formats. +Some of these tools are required and must be installed before working through the examples in the following chapters. +Some are optional, adding capabilities or making the job of creating documentation less demanding. [[tools-required]] == Required Tools -Install `gohugo` and `rubygem-asciidoctor` as shown in <> from the Ports Collection. These applications are required to do useful work with the FreeBSD documentation. Some further notes on particular components are given below. +Install `gohugo` and `rubygem-asciidoctor` as shown in crossref:overview[overview,the overview chapter] from the Ports Collection. +These applications are required to do useful work with the FreeBSD documentation. +Some further notes on particular components are given below. [[tools-optional]] == Optional Tools These applications are not required, but can make working on the documentation easier or add capabilities. [[tools-optional-software]] === Software Vim (package:editors/vim[]):: A popular editor for working with AsciiDoctor. Emacs (package:editors/emacs[]):: -Both of these editors include a special mode for editing documents. This mode includes commands to reduce the amount of typing needed, and help reduce the possibility of errors. +Both of these editors include a special mode for editing documents. +This mode includes commands to reduce the amount of typing needed, and help reduce the possibility of errors. diff --git a/documentation/content/en/books/fdp-primer/translations/chapter.adoc b/documentation/content/en/books/fdp-primer/translations/_index.adoc similarity index 62% rename from documentation/content/en/books/fdp-primer/translations/chapter.adoc rename to documentation/content/en/books/fdp-primer/translations/_index.adoc index 14c82e5f98..f300e85085 100644 --- a/documentation/content/en/books/fdp-primer/translations/chapter.adoc +++ b/documentation/content/en/books/fdp-primer/translations/_index.adoc @@ -1,205 +1,227 @@ --- title: Chapter 8. Translations prev: books/fdp-primer/rosetta next: books/fdp-primer/po-translations --- [[translations]] = Translations :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :skip-front-matter: :xrefstyle: basic :relfileprefix: ../ :outfilesuffix: :sectnumoffset: 8 include::shared/en/teams.adoc[] include::shared/en/mailing-lists.adoc[] toc::[] This is the FAQ for people translating the FreeBSD documentation (FAQ, Handbook, tutorials, manual pages, and others) to different languages. It is _very_ heavily based on the translation FAQ from the FreeBSD German Documentation Project, originally written by Frank Gründer mailto:elwood@mc5sys.in-berlin.de[elwood@mc5sys.in-berlin.de] and translated back to English by Bernd Warken mailto:bwarken@mayn.de[bwarken@mayn.de]. == What do i18n and l10n mean? -i18n means internationalization and l10n means localization. They are just a convenient shorthand. +i18n means internationalization and l10n means localization. +They are just a convenient shorthand. -i18n can be read as "i" followed by 18 letters, followed by "n". Similarly, l10n is "l" followed by 10 letters, followed by "n". +i18n can be read as "i" followed by 18 letters, followed by "n". +Similarly, l10n is "l" followed by 10 letters, followed by "n". == Is there a mailing list for translators? -Yes. Different translation groups have their own mailing lists. The https://www.freebsd.org/docproj/translations[list of translation projects] has more information about the mailing lists and web sites run by each translation project. In addition there is -mailto:freebsd-translators@freebsd.org[freebsd-translators@freebsd.org] for general translation discussion. +Yes. Different translation groups have their own mailing lists. +The https://www.freebsd.org/docproj/translations[list of translation projects] has more information about the mailing lists and web sites run by each translation project. +In addition there is mailto:freebsd-translators@freebsd.org[freebsd-translators@freebsd.org] for general translation discussion. == Are more translators needed? Yes. The more people that work on translation the faster it gets done, and the faster changes to the English documentation are mirrored in the translated documents. You do not have to be a professional translator to be able to help. == What languages do I need to know? Ideally, you will have a good knowledge of written English, and obviously you will need to be fluent in the language you are translating to. -English is not strictly necessary. For example, you could do a Hungarian translation of the FAQ from the Spanish translation. +English is not strictly necessary. +For example, you could do a Hungarian translation of the FAQ from the Spanish translation. == What software do I need to know? -It is strongly recommended that you maintain a local copy of the FreeBSD Git repository (at least the documentation part). This can be done by running: +It is strongly recommended that you maintain a local copy of the FreeBSD Git repository (at least the documentation part). +This can be done by running: [source,shell] .... -% git clone https://cgit.FreeBSD.org/doc.git doc +% git clone https://cgit.FreeBSD.org/doc.git ~/doc .... https://cgit.FreeBSD.org/[cgit.FreeBSD.org] is a public `git` server. [NOTE] ==== This will require the package:git-lite[] package to be installed. ==== -You should be comfortable using git. This will allow you to see what has changed between different versions of the files that make up the documentation. +You should be comfortable using git. +This will allow you to see what has changed between different versions of the files that make up the documentation. -For example, to view the differences between revisions `r33733` and `r33734` of [.filename]#content/en/books/fdp-primer/book.adoc#, run: +For example, to view the differences between revisions `832fed5c` and `11cd6edd` run: [source,shell] .... -% git diff -r33733:33734 content/en/books/fdp-primer/book.adoc +% git diff 832fed5c..11cd6edd .... -Please see the complete explanation of using Git in FreeBSD in the link:{handbook}[FreeBSD Handbook]. +Please see the complete explanation of using Git in FreeBSD in the link:{committers-guide}#git-primer[Git Primer]. == How do I find out who else might be translating to the same language? -The https://www.FreeBSD.org/docproj/translations/[Documentation Project translations page] lists the translation efforts that are currently known about. If others are already working on translating documentation to your language, please do not duplicate their efforts. Instead, contact them to see how you can help. +The https://www.FreeBSD.org/docproj/translations/[Documentation Project translations page] lists the translation efforts that are currently known about. +If others are already working on translating documentation to your language, please do not duplicate their efforts. +Instead, contact them to see how you can help. If no one is listed on that page as translating for your language, then send a message to the {freebsd-doc} in case someone else is thinking of doing a translation, but has not announced it yet. == No one else is translating to my language. What do I do? -Congratulations, you have just started the "FreeBSD _your-language-here_ Documentation Translation Project". Welcome aboard. +Congratulations, you have just started the "FreeBSD _your-language-here_ Documentation Translation Project". +Welcome aboard. -First, decide whether or not you have got the time to spare. Since you are the only person working on your language at the moment it is going to be your responsibility to publicize your work and coordinate any volunteers that might want to help you. +First, decide whether or not you have got the time to spare. +Since you are the only person working on your language at the moment it is going to be your responsibility to publicize your work and coordinate any volunteers that might want to help you. Write an email to the Documentation Project mailing list, announcing that you are going to translate the documentation, so the Documentation Project translations page can be maintained. If there is already someone in your country providing FreeBSD mirroring services you should contact them and ask if you can have some webspace for your project, and possibly an email address or mailing list services. -Then pick a document and start translating. It is best to start with something fairly small - either the FAQ, or one of the tutorials. +Then pick a document and start translating. +It is best to start with something fairly small - either the FAQ, or one of the tutorials. == I have translated some documentation, where do I send it? -That depends. If you are already working with a translation team (such as the Japanese team, or the German team) then they will have their own procedures for handling submitted documentation, and these will be outlined on their web pages. +That depends. +If you are already working with a translation team (such as the Japanese team, or the German team) then they will have their own procedures for handling submitted documentation, and these will be outlined on their web pages. If you are the only person working on a particular language (or you are responsible for a translation project and want to submit your changes back to the FreeBSD project) then you should send your translation to the FreeBSD project (see the next question). == I am the only person working on translating to this language, how do I submit my translation? -First, make sure your translation is organized properly. This means that it should drop into the existing documentation tree and build straight away. +First, make sure your translation is organized properly. +This means that it should drop into the existing documentation tree and build straight away. -Currently, the FreeBSD documentation is stored in a top level directory called [.filename]#head/#. Directories below this are named according to the language code they are written in, as defined in ISO639 ([.filename]#/usr/share/misc/iso639# on a version of FreeBSD newer than 20th January 1999). +Directories below this are named according to the language code they are written in, +as defined in ISO639 ([.filename]#/usr/share/misc/iso639# on a version of FreeBSD newer than 20th January 1999). + +[WARNING] +==== +Hugo need the language codes in lowercase. +For example, instead of `pt_BR` Hugo uses `pt-br`. +==== If your language can be encoded in different ways (for example, Chinese) then there should be directories below this, one for each encoding format you have provided. Finally, you should have directories for each document. For example, a hypothetical Swedish translation might look like: [.programlisting] .... -head/ +documentation/ content/ sv/ books/ faq/ book.adoc .... -`sv` is the name of the translation, in [.filename]#lang# form. Note the two Makefiles, which will be used to build the documentation. +`sv` is the name of the translation, in [.filename]#lang# form. +Note the two Makefiles, which will be used to build the documentation. -Use man:tar[1] and man:gzip[1] to compress up your documentation, and send it to the project. +Use git diff command to generate a diff and send it to the link:reviews.freebsd.org/[reviews system]. [source,shell] .... -% cd doc -% tar cf swedish-docs.tar sv -% gzip -9 swedish-docs.tar +% git diff > sv-faq.diff .... -Put [.filename]#swedish-docs.tar.gz# somewhere. If you do not have access to your own webspace (perhaps your ISP does not let you have any) then you can email {doceng}, and arrange to email the files when it is convenient. +Either way, you should use Bugzilla to link:https://bugs.freebsd.org/bugzilla/enter_bug.cgi[submit a report] indicating that you have submitted the documentation. +It would be very helpful if you could get other people to look over your translation and double check it first, since it is unlikely that the person committing it will be fluent in the language. -Either way, you should use Bugzilla to submit a report indicating that you have submitted the documentation. It would be very helpful if you could get other people to look over your translation and double check it first, since it is unlikely that the person committing it will be fluent in the language. - -Someone (probably the Documentation Project Manager, currently {doceng}) will then take your translation and confirm that it builds. In particular, the following things will be looked at: +Someone (probably the Documentation Project Manager, currently {doceng}) will then take your translation and confirm that it builds. +In particular, the following things will be looked at: . Does `make` in the [.filename]#root# directory work correctly? If there are any problems then whoever is looking at the submission will get back to you to work them out. If there are no problems your translation will be committed as soon as possible. == Can I include language or country specific text in my translation? We would prefer that you did not. For example, suppose that you are translating the Handbook to Korean, and want to include a section about retailers in Korea in your Handbook. -There is no real reason why that information should not be in the English (or German, or Spanish, or Japanese, or ...) versions as well. It is feasible that an English speaker in Korea might try to pick up a copy of FreeBSD whilst over there. It also helps increase FreeBSD's perceived presence around the globe, which is not a bad thing. +There is no real reason why that information should not be in the English (or German, or Spanish, or Japanese, or ...) versions as well. +It is feasible that an English speaker in Korea might try to pick up a copy of FreeBSD whilst over there. +It also helps increase FreeBSD's perceived presence around the globe, which is not a bad thing. If you have country specific information, please submit it as a change to the English Handbook (using Bugzilla) and then translate the change back to your language in the translated Handbook. Thanks. === Addressing the reader In the English documents, the reader is addressed as "you", there is no formal/informal distinction as there is in some languages. -If you are translating to a language which does distinguish, use whichever form is typically used in other technical documentation in your language. If in doubt, use a mildly polite form. +If you are translating to a language which does distinguish, use whichever form is typically used in other technical documentation in your language. +If in doubt, use a mildly polite form. === Do I need to include any additional information in my translations? Yes. The header of the English version of each document will look something like this: [.programlisting] .... --- title: Why you should use a BSD style license for your Open Source Project releaseinfo: "$FreeBSD: head/en_US.ISO8859-1/articles/bsdl-gpl/article.xml 53942 2020-03-01 12:23:40Z carlavilla $" trademarks: ["freebsd", "intel", "general"] --- -= Why you should use a BSD style license for your Open Source Project +\= Why you should use a BSD style license for your Open Source Project .... -The exact boilerplate may change, but it will always include a $FreeBSD$ line and the phrase `The FreeBSD Documentation Project`. Note that the $FreeBSD$ part is expanded automatically by Git, so it should be empty (just `$FreeBSD$`) for new files. +The exact boilerplate may change, but it will always include a $FreeBSD$ line and the phrase `The FreeBSD Documentation Project`. +Note that the $FreeBSD$ part is expanded automatically by Git, so it should be empty (just `$FreeBSD$`) for new files. Your translated documents should include their own FreeBSD line, and change the `FreeBSD Documentation Project` line to `The FreeBSD _language_ Documentation Project`. In addition, you should add a third line which indicates which revision of the English text this is based on. So, the Spanish version of this file might start: [.programlisting] .... --- title: Soporte para segundos intercalares en FreeBSD releaseinfo: "$FreeBSD: head/es_ES.ISO8859-1/articles/leap-seconds/article.xml 53090 2019-06-01 17:52:59Z carlavilla $" --- -= Soporte para segundos intercalares en FreeBSD +\= Soporte para segundos intercalares en FreeBSD .... - diff --git a/documentation/content/en/books/fdp-primer/working-copy/_index.adoc b/documentation/content/en/books/fdp-primer/working-copy/_index.adoc new file mode 100644 index 0000000000..facb05af1d --- /dev/null +++ b/documentation/content/en/books/fdp-primer/working-copy/_index.adoc @@ -0,0 +1,134 @@ +--- +title: Chapter 3. The Working Copy +prev: books/fdp-primer/tools +next: books/fdp-primer/structure +--- + +[[working-copy]] += The Working Copy +:doctype: book +:toc: macro +:toclevels: 1 +:icons: font +:sectnums: +:sectnumlevels: 6 +:source-highlighter: rouge +:experimental: +:skip-front-matter: +:xrefstyle: basic +:relfileprefix: ../ +:outfilesuffix: +:sectnumoffset: 3 + +toc::[] + +The _working copy_ is a copy of the FreeBSD repository documentation tree downloaded onto the local computer. +Changes are made to the local working copy, tested, and then submitted as patches to be committed to the main repository. + +A full copy of the documentation tree can occupy 550 megabytes of disk space. +Allow for a full gigabyte of space to have room for temporary files and test versions of various output formats. + +link:https://git-scm.com/[Git] is used to manage the FreeBSD documentation files. +It is obtained by installing the Git package: + +[source,shell] +.... +# pkg install git-lite +.... + +[[working-copy-doc-and-src]] +== Documentation and Manual Pages + +FreeBSD documentation is not just books and articles. +Manual pages for all the commands and configuration files are also part of the documentation, and part of the FDP's territory. +Two repositories are involved: `doc` for the books and articles, and `src` for the operating system and manual pages. +To edit manual pages, the `src` repository must be checked out separately. + +Repositories may contain multiple versions of documentation and source code. +New modifications are almost always made only to the latest version, called `main`. + +[[working-copy-choosing-directory]] +== Choosing a Directory + +FreeBSD documentation is traditionally stored in [.filename]#/usr/doc/#, and system source code with manual pages in [.filename]#/usr/src/#. +These directory trees are relocatable, and users may want to put the working copies in other locations to avoid interfering with existing information in the main directories. +The examples that follow use [.filename]#~/doc# and [.filename]#~/src#, both subdirectories of the user's home directory. + +[[working-copy-checking-out]] +== Checking Out a Copy + +A download of a working copy from the repository is called a _clone_, and done with `git clone`. +This example clones a copy of the latest version (`main`) of the main documentation tree: + +[source,shell] +.... +% git clone https://git.FreeBSD.org/doc.git ~/doc +.... + +A checkout of the source code to work on manual pages is very similar: + +[source,shell] +.... +% git clone https://git.FreeBSD.org/src.git ~/src +.... + +[[working-copy-updating]] +== Updating a Working Copy + +The documents and files in the FreeBSD repository change daily. +People modify files and commit changes frequently. +Even a short time after an initial checkout, there will already be differences between the local working copy and the main FreeBSD repository. +To update the local version with the changes that have been made to the main repository, use `git pull` on the directory containing the local working copy: + +[source,shell] +.... +% git pull ~/doc +.... + +Get in the protective habit of using `git pull` before editing document files. +Someone else may have edited that file very recently, and the local working copy will not include the latest changes until it has been updated. +Editing the newest version of a file is much easier than trying to combine an older, edited local file with the newer version from the repository. + +[[working-copy-revert]] +== Reverting Changes + +Sometimes it turns out that changes were not necessary after all, or the writer just wants to start over. +Files can be "reset" to their unchanged form with `git restore`. +For example, to erase the edits made to [.filename]#_index.adoc# and reset it to unmodified form: + +[source,shell] +.... +% git restore _index.adoc +.... + +[[working-copy-making-diff]] +== Making a Diff + +After edits to a file or group of files are completed, the differences between the local working copy and the version on the FreeBSD repository must be collected into a single file for submission. +These _diff_ files are produced by redirecting the output of `git diff` into a file: + +[source,shell] +.... +% cd ~/doc +% git diff doc-fix-spelling.diff +.... + +Give the file a meaningful name that identifies the contents. +The example above is for spelling fixes to the whole documentation tree. + +If the diff file is to be submitted with the web "link:https://bugs.FreeBSD.org/bugzilla/enter_bug.cgi[Submit a FreeBSD problem report]" interface, add a [.filename]#.txt# extension to give the earnest and simple-minded web form a clue that the contents are plain text. + +Be careful: `git diff` includes all changes made in the current directory and any subdirectories. +If there are files in the working copy with edits that are not ready to be submitted yet, provide a list of only the files that are to be included: + +[source,shell] +.... +% cd ~/doc +% git diff disks/_index.adoc printers/_index.adoc disks-printers.diff +.... + +[[working-copy-git-references]] +== Git References + +These examples show very basic usage of Git. +More detail is available in the https://git-scm.com/book/en/v2[Git Book] and the https://git-scm.com/doc[Git documentation]. diff --git a/documentation/content/en/books/fdp-primer/working-copy/chapter.adoc b/documentation/content/en/books/fdp-primer/working-copy/chapter.adoc deleted file mode 100644 index 4f5bf8c27a..0000000000 --- a/documentation/content/en/books/fdp-primer/working-copy/chapter.adoc +++ /dev/null @@ -1,113 +0,0 @@ ---- -title: Chapter 3. The Working Copy -prev: books/fdp-primer/tools -next: books/fdp-primer/structure ---- - -[[working-copy]] -= The Working Copy -:doctype: book -:toc: macro -:toclevels: 1 -:icons: font -:sectnums: -:sectnumlevels: 6 -:source-highlighter: rouge -:experimental: -:skip-front-matter: -:xrefstyle: basic -:relfileprefix: ../ -:outfilesuffix: -:sectnumoffset: 3 - -toc::[] - -The _working copy_ is a copy of the FreeBSD repository documentation tree downloaded onto the local computer. Changes are made to the local working copy, tested, and then submitted as patches to be committed to the main repository. - -A full copy of the documentation tree can occupy 700 megabytes of disk space. Allow for a full gigabyte of space to have room for temporary files and test versions of various output formats. - -link:https://git-scm.com/[Git] is used to manage the FreeBSD documentation files. It is obtained by installing the Git package: - -[source,shell] -.... -# pkg install git-lite -.... - -[[working-copy-doc-and-src]] -== Documentation and Manual Pages - -FreeBSD documentation is not just books and articles. Manual pages for all the commands and configuration files are also part of the documentation, and part of the FDP's territory. Two repositories are involved: `doc` for the books and articles, and `src` for the operating system and manual pages. To edit manual pages, the `src` repository must be checked out separately. - -Repositories may contain multiple versions of documentation and source code. New modifications are almost always made only to the latest version, called `main`. - -[[working-copy-choosing-directory]] -== Choosing a Directory - -FreeBSD documentation is traditionally stored in [.filename]#/usr/doc/#, and system source code with manual pages in [.filename]#/usr/src/#. These directory trees are relocatable, and users may want to put the working copies in other locations to avoid interfering with existing information in the main directories. The examples that follow use [.filename]#~/doc# and [.filename]#~/src#, both subdirectories of the user's home directory. - -[[working-copy-checking-out]] -== Checking Out a Copy - -A download of a working copy from the repository is called a _clone_, and done with `git clone`. This example clones a copy of the latest version (`main`) of the main documentation tree: - -[source,shell] -.... -% git clone https://git.FreeBSD.org/doc.git ~/doc -.... - -A checkout of the source code to work on manual pages is very similar: - -[source,shell] -.... -% git clone https://git.FreeBSD.org/src.git ~/src -.... - -[[working-copy-updating]] -== Updating a Working Copy - -The documents and files in the FreeBSD repository change daily. People modify files and commit changes frequently. Even a short time after an initial checkout, there will already be differences between the local working copy and the main FreeBSD repository. To update the local version with the changes that have been made to the main repository, use `git pull` on the directory containing the local working copy: - -[source,shell] -.... -% git pull ~/doc -.... - -Get in the protective habit of using `git pull` before editing document files. Someone else may have edited that file very recently, and the local working copy will not include the latest changes until it has been updated. Editing the newest version of a file is much easier than trying to combine an older, edited local file with the newer version from the repository. - -[[working-copy-revert]] -== Reverting Changes - -Sometimes it turns out that changes were not necessary after all, or the writer just wants to start over. Files can be "reset" to their unchanged form with `git restore`. For example, to erase the edits made to [.filename]#_index.adoc# and reset it to unmodified form: - -[source,shell] -.... -% git restore _index.adoc -.... - -[[working-copy-making-diff]] -== Making a Diff - -After edits to a file or group of files are completed, the differences between the local working copy and the version on the FreeBSD repository must be collected into a single file for submission. These _diff_ files are produced by redirecting the output of `git diff` into a file: - -[source,shell] -.... -% cd ~/doc -% git diff doc-fix-spelling.diff -.... - -Give the file a meaningful name that identifies the contents. The example above is for spelling fixes to the whole documentation tree. - -If the diff file is to be submitted with the web "link:https://bugs.FreeBSD.org/bugzilla/enter_bug.cgi[Submit a FreeBSD problem report]" interface, add a [.filename]#.txt# extension to give the earnest and simple-minded web form a clue that the contents are plain text. - -Be careful: `git diff` includes all changes made in the current directory and any subdirectories. If there are files in the working copy with edits that are not ready to be submitted yet, provide a list of only the files that are to be included: - -[source,shell] -.... -% cd ~/doc -% git diff disks/_index.adoc printers/_index.adoc disks-printers.diff -.... - -[[working-copy-git-references]] -== Git References - -These examples show very basic usage of Git. More detail is available in the https://git-scm.com/book/en/v2[Git Book] and the https://git-scm.com/doc[Git documentation]. diff --git a/documentation/content/en/books/fdp-primer/writing-style/_index.adoc b/documentation/content/en/books/fdp-primer/writing-style/_index.adoc new file mode 100644 index 0000000000..afb1494d6a --- /dev/null +++ b/documentation/content/en/books/fdp-primer/writing-style/_index.adoc @@ -0,0 +1,231 @@ +--- +title: Chapter 11. Writing Style +prev: books/fdp-primer/manual-pages +next: books/fdp-primer/editor-config +--- + +[[writing-style]] += Writing Style +:doctype: book +:toc: macro +:toclevels: 1 +:icons: font +:sectnums: +:sectnumlevels: 6 +:source-highlighter: rouge +:experimental: +:skip-front-matter: +:xrefstyle: basic +:relfileprefix: ../ +:outfilesuffix: +:sectnumoffset: 11 + +include::shared/en/mailing-lists.adoc[] + +toc::[] + +[[writing-style-tips]] +== Tips + +Technical documentation can be improved by consistent use of several principles. +Most of these can be classified into three goals: _be clear_, _be complete_, and _be concise_. +These goals can conflict with each other. Good writing consists of a balance between them. + +[[writing-style-be-clear]] +=== Be Clear + +Clarity is extremely important. +The reader may be a novice, or reading the document in a second language. +Strive for simple, uncomplicated text that clearly explains the concepts. + +Avoid flowery or embellished speech, jokes, or colloquial expressions. +Write as simply and clearly as possible. +Simple text is easier to understand and translate. + +Keep explanations as short, simple, and clear as possible. +Avoid empty phrases like "in order to", which usually just means "to". +Avoid potentially patronizing words like "basically". +Avoid Latin terms like "i.e.," or "cf.", which may be unknown outside of academic or scientific groups. + +Write in a formal style. +Avoid addressing the reader as "you". +For example, say "copy the file to [.filename]#/tmp#" rather than "you can copy the file to [.filename]#/tmp#". + +Give clear, correct, _tested_ examples. +A trivial example is better than no example. +A good example is better yet. +Do not give bad examples, identifiable by apologies or sentences like "but really it should never be done that way". +Bad examples are worse than no examples. +Give good examples, because _even when warned not to use the example as shown_, +the reader will usually just use the example as shown. + +Avoid _weasel words_ like "should", "might", "try", or "could". +These words imply that the speaker is unsure of the facts, and create doubt in the reader. + +Similarly, give instructions as imperative commands: not "you should do this", but merely "do this". + +[[writing-style-be-complete]] +=== Be Complete + +Do not make assumptions about the reader's abilities or skill level. +Tell them what they need to know. +Give links to other documents to provide background information without having to recreate it. +Put yourself in the reader's place, anticipate the questions they will ask, and answer them. + +[[writing-style-be-concise]] +=== Be Concise + +While features should be documented completely, +sometimes there is so much information that the reader cannot easily find the specific detail needed. +The balance between being complete and being concise is a challenge. +One approach is to have an introduction, +then a "quick start" section that describes the most common situation, +followed by an in-depth reference section. + +[[writing-style-guidelines]] +== Guidelines + +To promote consistency between the myriad authors of the FreeBSD documentation, +some guidelines have been drawn up for authors to follow. + +Use American English Spelling:: +There are several variants of English, with different spellings for the same word. +Where spellings differ, use the American English variant. +"color", not "colour", "rationalize", not "rationalise", and so on. ++ +[NOTE] +==== +The use of British English may be accepted in the case of a contributed article, +however the spelling must be consistent within the whole document. +The other documents such as books, web site, manual pages, etc. will have to use American English. +==== + +Do not use contractions:: +Do not use contractions. +Always spell the phrase out in full. +"Don't use contractions" is wrong. ++ +Avoiding contractions makes for a more formal tone, is more precise, and is slightly easier for translators. + +Use the serial comma:: +In a list of items within a paragraph, separate each item from the others with a comma. +Separate the last item from the others with a comma and the word "and". ++ +For example: ++ +This is a list of one, two and three items. ++ +Is this a list of three items, "one", "two", and "three", or a list of two items, "one" and "two and three"? ++ +It is better to be explicit and include a serial comma: ++ +This is a list of one, two, and three items. +Avoid redundant phrases:: +Do not use redundant phrases. +In particular, "the command", "the file", and "man command" are often redundant. ++ +For example, commands: ++ +Wrong: Use the `git` command to update sources. ++ +Right: Use `git` to update sources. ++ +Filenames: ++ +Wrong: ... in the filename [.filename]#/etc/rc.local#... ++ +Right: ... in [.filename]#/etc/rc.local#... ++ +Manual page references (the second example uses `citerefentry` with the man:csh[1] entity):. ++ +Wrong: See `man csh` for more information. ++ +Right: See man:csh[1]. + +For more information about writing style, see http://www.bartleby.com/141/[Elements of Style], by William Strunk. + +[[writing-style-guide]] +== Style Guide + +To keep the source for the documentation consistent when many different people are editing it, please follow these style conventions. + +[[one-sentence-per-line]] +== One sentence per line + +Use Semantic Line Breaks in the documentation, a technique called "one sentence per line". +The idea of this technique is to help the users to write and read documentation. +To get more information about this technique read the link:https://sembr.org/[Semantic Line Breaks] page. + +This is an example which don't use "one sentence per line". + +.... +All human beings are born free and equal in dignity and rights. They are endowed with reason and conscience and should act towards one another in a spirit of brotherhood. +.... + +And this is an example which uses the technique. + +.... +All human beings are born free and equal in dignity and rights. +They are endowed with reason and conscience and should act towards one another in a spirit of brotherhood. +.... + +[[writing-style-acronyms]] +=== Acronyms + +Acronyms should be defined the first time they appear in a document, as in: "Network Time Protocol (NTP)". +After the acronym has been defined, use the acronym alone unless it makes more sense contextually to use the whole term. +Acronyms are usually defined only once per chapter or per document. + +All acronyms should be enclosed using the ` character. + +[[writing-style-special-characters]] +== Special Character List + +This list of special characters shows the correct syntax and the output when used in FreeBSD documentation. +If a character is not on this list, ask about it on the {freebsd-doc}. + +[.informaltable] +[cols="1,1,1", frame="none", options="header"] +|=== +| Name +| Syntax +| Rendered + + +| Copyright +| +(C)+ +| (C) + +| Registered +| +(R)+ +| (R) + +| Trademark +| +(TM)+ +| (TM) + +| Em dash +| +--+ +| -- + +| Ellipses +| +...+ +| ... + +| Single right arrow +| +->+ +| -> + +| Double right arrow +| +=>+ +| => + +| Single left arrow +| +<-+ +| <- + +| Double left arrow +| +<=+ +| <= + +|=== diff --git a/documentation/content/en/books/fdp-primer/writing-style/chapter.adoc b/documentation/content/en/books/fdp-primer/writing-style/chapter.adoc deleted file mode 100644 index 525be21594..0000000000 --- a/documentation/content/en/books/fdp-primer/writing-style/chapter.adoc +++ /dev/null @@ -1,173 +0,0 @@ ---- -title: Chapter 11. Writing Style -prev: books/fdp-primer/manual-pages -next: books/fdp-primer/editor-config ---- - -[[writing-style]] -= Writing Style -:doctype: book -:toc: macro -:toclevels: 1 -:icons: font -:sectnums: -:sectnumlevels: 6 -:source-highlighter: rouge -:experimental: -:skip-front-matter: -:xrefstyle: basic -:relfileprefix: ../ -:outfilesuffix: -:sectnumoffset: 11 - -include::shared/en/mailing-lists.adoc[] - -toc::[] - -[[writing-style-tips]] -== Tips - -Technical documentation can be improved by consistent use of several principles. Most of these can be classified into three goals: _be clear_, _be complete_, and _be concise_. These goals can conflict with each other. Good writing consists of a balance between them. - -[[writing-style-be-clear]] -=== Be Clear - -Clarity is extremely important. The reader may be a novice, or reading the document in a second language. Strive for simple, uncomplicated text that clearly explains the concepts. - -Avoid flowery or embellished speech, jokes, or colloquial expressions. Write as simply and clearly as possible. Simple text is easier to understand and translate. - -Keep explanations as short, simple, and clear as possible. Avoid empty phrases like "in order to", which usually just means "to". Avoid potentially patronizing words like "basically". Avoid Latin terms like "i.e.," or "cf.", which may be unknown outside of academic or scientific groups. - -Write in a formal style. Avoid addressing the reader as "you". For example, say "copy the file to [.filename]#/tmp#" rather than "you can copy the file to [.filename]#/tmp#". - -Give clear, correct, _tested_ examples. A trivial example is better than no example. A good example is better yet. Do not give bad examples, identifiable by apologies or sentences like "but really it should never be done that way". Bad examples are worse than no examples. Give good examples, because _even when warned not to use the example as shown_, the reader will usually just use the example as shown. - -Avoid _weasel words_ like "should", "might", "try", or "could". These words imply that the speaker is unsure of the facts, and create doubt in the reader. - -Similarly, give instructions as imperative commands: not "you should do this", but merely "do this". - -[[writing-style-be-complete]] -=== Be Complete - -Do not make assumptions about the reader's abilities or skill level. Tell them what they need to know. Give links to other documents to provide background information without having to recreate it. Put yourself in the reader's place, anticipate the questions they will ask, and answer them. - -[[writing-style-be-concise]] -=== Be Concise - -While features should be documented completely, sometimes there is so much information that the reader cannot easily find the specific detail needed. The balance between being complete and being concise is a challenge. One approach is to have an introduction, then a "quick start" section that describes the most common situation, followed by an in-depth reference section. - -[[writing-style-guidelines]] -== Guidelines - -To promote consistency between the myriad authors of the FreeBSD documentation, some guidelines have been drawn up for authors to follow. - -Use American English Spelling:: -There are several variants of English, with different spellings for the same word. Where spellings differ, use the American English variant. "color", not "colour", "rationalize", not "rationalise", and so on. -+ -[NOTE] -==== -The use of British English may be accepted in the case of a contributed article, however the spelling must be consistent within the whole document. The other documents such as books, web site, manual pages, etc. will have to use American English. -==== - -Do not use contractions:: -Do not use contractions. Always spell the phrase out in full. "Don't use contractions" is wrong. -+ -Avoiding contractions makes for a more formal tone, is more precise, and is slightly easier for translators. - -Use the serial comma:: -In a list of items within a paragraph, separate each item from the others with a comma. Separate the last item from the others with a comma and the word "and". -+ -For example: -+ -This is a list of one, two and three items. -+ -Is this a list of three items, "one", "two", and "three", or a list of two items, "one" and "two and three"? -+ -It is better to be explicit and include a serial comma: -+ -This is a list of one, two, and three items. -Avoid redundant phrases:: -Do not use redundant phrases. In particular, "the command", "the file", and "man command" are often redundant. -+ -For example, commands: -+ -Wrong: Use the `git` command to update sources. -+ -Right: Use `git` to update sources. -+ -Filenames: -+ -Wrong: ... in the filename [.filename]#/etc/rc.local#... -+ -Right: ... in [.filename]#/etc/rc.local#... -+ -Manual page references (the second example uses `citerefentry` with the man:csh[1] entity):. -+ -Wrong: See `man csh` for more information. -+ -Right: See man:csh[1]. - -For more information about writing style, see http://www.bartleby.com/141/[Elements of Style], by William Strunk. - -[[writing-style-guide]] -== Style Guide - -To keep the source for the documentation consistent when many different people are editing it, please follow these style conventions. - -[[writing-style-acronyms]] -=== Acronyms - -Acronyms should be defined the first time they appear in a document, as in: "Network Time Protocol (NTP)". After the acronym has been defined, use the acronym alone unless it makes more sense contextually to use the whole term. Acronyms are usually defined only once per chapter or per document. - -All acronyms should be enclosed using the ` character. - -[[writing-style-special-characters]] -== Special Character List - -This list of special characters shows the correct syntax and the output when used in FreeBSD documentation. If a character is not on this list, ask about it on the {freebsd-doc}. - -[.informaltable] -[cols="1,1,1", frame="none", options="header"] -|=== -| Name -| Syntax -| Rendered - - -| Copyright -| +(C)+ -| (C) - -| Registered -| +(R)+ -| (R) - -| Trademark -| +(TM)+ -| (TM) - -| Em dash -| +--+ -| -- - -| Ellipses -| +...+ -| ... - -| Single right arrow -| +->+ -| -> - -| Double right arrow -| +=>+ -| => - -| Single left arrow -| +<-+ -| <- - -| Double left arrow -| +<=+ -| <= - -|===