Fix outdated information in FDP

Submitted by: dbaio@ Approved by: bcr@, crees@, gjb@ Differential Revision: https://reviews.freebsd.org/D29573
2021-04-10 16:44:30 +02:00 · 2021-04-10 16:44:30 +02:00 · a237bc3c64
parent aef48a9185
commit a237bc3c64
6 changed files with 82 additions and 63 deletions
--- a/documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc
+++ b/documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc
@ -133,7 +133,7 @@ And this is the second paragraph.
 == 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]
+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
--- a/documentation/content/en/books/fdp-primer/doc-build/_index.adoc
+++ b/documentation/content/en/books/fdp-primer/doc-build/_index.adoc
@ -92,15 +92,26 @@ To render the documentation and the website to `html` use one of the following e

 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.
+In order to export the document correctly all the extensions should be passed using the `-r` argument.

 [[document-pdf-example]]
-.Build the entire documentation project
+.Build a document in pdf
 [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
+% cd ~/doc/documentation
+% 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 \
+  -o /tmp/handbook.pdf
+  content/en/books/handbook/book.adoc
 ....
 ====

--- a/documentation/content/en/books/fdp-primer/overview/_index.adoc
+++ b/documentation/content/en/books/fdp-primer/overview/_index.adoc
@ -80,7 +80,7 @@ Repeat until all of the errors are resolved.
 +
 [source,shell]
 ....
-make
+% make
 ....
 +
 . When changes are complete and tested, generate a "diff file":
--- a/documentation/content/en/books/fdp-primer/po-translations/_index.adoc
+++ b/documentation/content/en/books/fdp-primer/po-translations/_index.adoc
@ -49,8 +49,7 @@ This example shows the creation of a Spanish translation of the short link:{leap
 +
 [source,shell]
 ....
-# cd /usr/ports/editors/poedit
-# make install clean
+# pkg install poedit
 ....
 ====

@ -61,22 +60,22 @@ This example shows the creation of a Spanish translation of the short link:{leap

 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.
+. Create a directory for the new translation. The English article source is in [.filename]#~/doc/documentation/content/en/articles/leap-seconds/#. The Spanish translation will go in [.filename]#~/doc/documentation/content/es/articles/leap-seconds/#. The path is the same except for the name of the language directory.
 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/
+% mkdir ~/doc/documentation/content/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/
+% cp ~/doc/documentation/content/en/articles/leap-seconds/_index.adoc \
+  ~/doc/documentation/content/es/articles/leap-seconds/
 ....
 ====

@ -92,18 +91,23 @@ These steps are repeated until the translator feels that enough of the document
 +
 [source,shell]
 ....
-% cd ~/doc/es/articles/leap-seconds/
-% po4a-gettextize --format asciidoc --master _index.adoc --master-charset "UTF-8" >> es.pot
+% cd ~/doc
+% po4a-gettextize \
+  --format asciidoc \
+  --option compat=asciidoctor \
+  --option yfm_keys=title,part \
+  --master "documentation/content/en/articles/leap-seconds/_index.adoc" \
+  --master-charset "UTF-8" \
+  --copyright-holder "The FreeBSD Project" \
+  --package-name "FreeBSD Documentation" \
+  --po "documentation/content/es/articles/leap-seconds/_index.po"
 ....
 +
 . 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#.
-+
 [source,shell]
 ....
-% poedit es.po
+% poedit documentation/content/es/articles/leap-seconds/_index.po
 ....
 ====

@ -115,8 +119,17 @@ For Spanish, the file name is [.filename]#es.po#.
 +
 [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
+% cd ~/doc
+% po4a-translate \
+  --format asciidoc \
+  --option compat=asciidoctor \
+  --option yfm_keys=title,part \
+  --master "documentation/content/en/articles/leap-seconds/_index.adoc" \
+  --master-charset "UTF-8" \
+  --po "documentation/content/es/articles/leap-seconds/_index.po" \
+  --localized "documentation/content/es/articles/leap-seconds/_index.adoc" \
+  --localized-charset "UTF-8" \
+  --keep 0
 ....
 + 
 The name of the generated document matches the name of the English original, usually [.filename]#_index.adoc#.
@ -125,6 +138,7 @@ The name of the generated document matches the name of the English original, usu
 +
 [source,shell]
 ....
+% cd ~/doc/documentation
 % make
 ....
 ====
@ -143,113 +157,94 @@ _lang_ is a two-character lowercase code.
 | 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#

 |Russian
 |Russia
 |[.filename]#ru#
-|[.filename]#ru.po#

 |Turkish
 |Turkey
 |[.filename]#tr#
-|[.filename]#tr.po#

 |Chinese
 |China
 |[.filename]#zh-cn#
-|[.filename]#zh-cn.po#

 |Chinese
 |Taiwan
 |[.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 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/#.
+here assumed to be [.filename]#~/doc/documentation/# as shown in <<overview-quick-start>>.
+For example, German translations are located in [.filename]#~/doc/documentation/content/de/#,
+and French translations are in [.filename]#~/doc/documentation/content/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/#.
+For example, the French translation of the NanoBSD article is in [.filename]#~/doc/documentation/content/fr/articles/nanobsd/#,
+and the Mongolian translation of the Handbook is in [.filename]#~/doc/documentation/content/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.
@ -259,16 +254,16 @@ If the language directory already exists, only a subdirectory in the [.filename]
 [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/#.
+The original is a book in [.filename]#~/doc/documentation/content/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:
+. The Spanish language books directory [.filename]#~/doc/documentation/content/es/books/# already exists, so only a new subdirectory for the Porter's Handbook is needed:
 +
 [source,shell]
 ....
-% cd ~/doc/es/books/
+% cd ~/doc/documentation/content/es/books
 % mkdir porters-handbook
 ....

@ -276,8 +271,8 @@ The original is a book in [.filename]#~/doc/en/books/porters-handbook/#.
 +
 [source,shell]
 ....
-% cd ~/doc/es/books/porters-handbook
-% cp ~/doc/en/books/porters-handbook/ .
+% cd porters-handbook
+% cp -R ~/doc/documentation/content/en/books/porters-handbook/* .
 ....
 + 
 Now the document structure is ready for the translator to begin translating with `po4a` command.
@ -305,26 +300,35 @@ It contains all of the work that translators have done.
 .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 <<po-translations-language-names>>.
+. Change to the base directory and update all PO files.
 +
 [source,shell]
 ....
-% cd ~/doc/es/books/porters-handbook
-% po4a-gettextize --format asciidoc --master _index.adoc --master-charset "UTF-8" >> es.pot
+% cd ~/doc
+% po4a-gettextize \
+  --format asciidoc \
+  --option compat=asciidoctor \
+  --option yfm_keys=title,part \
+  --master "documentation/content/en/books/porters-handbook/_index.adoc" \
+  --master-charset "UTF-8" \
+  --copyright-holder "The FreeBSD Project" \
+  --package-name "FreeBSD Documentation" \
+  --po "documentation/content/es/books/porters-handbook/_index.po"
 ....

 . Enter translations using a PO editor:
 +
 [source,shell]
 ....
-% poedit es.pot
+% poedit documentation/content/es/books/porters-handbook/_index.po
 ....
 ======

+These steps are necessary for all `.adoc` files, excluding `chapters-order.adoc` and `toc-*.adoc`.
+
 ====

 [[po-translations-tips]]
@ -407,7 +411,7 @@ The diff files created by these examples can be attached to a https://bugs.freeb
 [source,shell]
 ....
 % cd ~/doc
-% git diff es/articles/nanobsd/ > /tmp/es_nanobsd.diff
+% git diff documentation/content/es/articles/nanobsd/ > /tmp/es_nanobsd.diff
 ....
 ======

--- a/documentation/content/en/books/fdp-primer/translations/_index.adoc
+++ b/documentation/content/en/books/fdp-primer/translations/_index.adoc
@ -65,10 +65,10 @@ This can be done by running:

 [source,shell]
 ....
-% git clone https://cgit.FreeBSD.org/doc.git ~/doc
+% git clone https://git.FreeBSD.org/doc.git ~/doc
 ....

-https://cgit.FreeBSD.org/[cgit.FreeBSD.org] is a public `git` server.
+https://git.FreeBSD.org/[git.FreeBSD.org] is a public `git` server.

 [NOTE]
 ====
@ -78,14 +78,14 @@ 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.

-For example, to view the differences between revisions `832fed5c` and `11cd6edd` run:
+For example, to view the differences between revisions `abff932fe8` and `2191c44469` of [.filename]#documentation/content/en/articles/committers-guide/_index.adoc#, run:

 [source,shell]
 ....
-% git diff 832fed5c..11cd6edd
+% git diff abff932fe8 2191c44469 documentation/content/en/articles/committers-guide/_index.adoc
 ....

-Please see the complete explanation of using Git in FreeBSD in the link:{committers-guide}#git-primer[Git Primer].
+Please see the complete explanation of using Git in FreeBSD in the link:{handbook}mirrors/#git[FreeBSD Handbook].

 == How do I find out who else might be translating to the same language?

@ -131,6 +131,9 @@ Hugo need the language codes in lowercase.
 For example, instead of `pt_BR` Hugo uses `pt-br`.
 ====

+Currently, the FreeBSD documentation is stored in a top level directory called [.filename]#documentation/#.
+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).
+
 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.
@ -144,7 +147,7 @@ documentation/
    sv/
      books/
        faq/
-          book.adoc
+          _index.adoc
 ....

 `sv` is the name of the translation, in [.filename]#lang# form.
--- a/documentation/content/en/books/fdp-primer/working-copy/_index.adoc
+++ b/documentation/content/en/books/fdp-primer/working-copy/_index.adoc
@ -82,7 +82,8 @@ To update the local version with the changes that have been made to the main rep

 [source,shell]
 ....
-% git pull ~/doc
+% cd ~/doc
+% git pull --ff-only
 ....

 Get in the protective habit of using `git pull` before editing document files.
@ -110,7 +111,7 @@ These _diff_ files are produced by redirecting the output of `git diff` into a f
 [source,shell]
 ....
 % cd ~/doc
-% git diff  doc-fix-spelling.diff
+% git diff > doc-fix-spelling.diff
 ....

 Give the file a meaningful name that identifies the contents.
@ -124,7 +125,7 @@ If there are files in the working copy with edits that are not ready to be submi
 [source,shell]
 ....
 % cd ~/doc
-% git diff disks/_index.adoc printers/_index.adoc  disks-printers.diff
+% git diff disks/_index.adoc printers/_index.adoc > disks-printers.diff
 ....

 [[working-copy-git-references]]