Date: Sat, 10 Apr 2021 14:46:08 GMT From: Sergio Carlavilla Delgado <carlavilla@FreeBSD.org> To: doc-committers@FreeBSD.org, dev-commits-doc-all@FreeBSD.org Subject: git: a237bc3c64 - main - Fix outdated information in FDP Message-ID: <202104101446.13AEk8qJ008496@gitrepo.freebsd.org>
next in thread | raw e-mail | index | archive | help
The branch main has been updated by carlavilla: URL: https://cgit.FreeBSD.org/doc/commit/?id=a237bc3c647392fee48479ddf67a6b86c2677f4a commit a237bc3c647392fee48479ddf67a6b86c2677f4a Author: Sergio Carlavilla Delgado <carlavilla@FreeBSD.org> AuthorDate: 2021-04-10 14:44:30 +0000 Commit: Sergio Carlavilla Delgado <carlavilla@FreeBSD.org> CommitDate: 2021-04-10 14:44:30 +0000 Fix outdated information in FDP Submitted by: dbaio@ Approved by: bcr@, crees@, gjb@ Differential Revision: https://reviews.freebsd.org/D29573 --- .../fdp-primer/asciidoctor-primer/_index.adoc | 2 +- .../en/books/fdp-primer/doc-build/_index.adoc | 17 +++- .../en/books/fdp-primer/overview/_index.adoc | 2 +- .../books/fdp-primer/po-translations/_index.adoc | 102 +++++++++++---------- .../en/books/fdp-primer/translations/_index.adoc | 15 +-- .../en/books/fdp-primer/working-copy/_index.adoc | 7 +- 6 files changed, 82 insertions(+), 63 deletions(-) diff --git a/documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc b/documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc index 947a42ca45..6f689de0d1 100644 --- 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 diff --git a/documentation/content/en/books/fdp-primer/doc-build/_index.adoc b/documentation/content/en/books/fdp-primer/doc-build/_index.adoc index 04a3398b20..83dc26045a 100644 --- 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 .... ==== diff --git a/documentation/content/en/books/fdp-primer/overview/_index.adoc b/documentation/content/en/books/fdp-primer/overview/_index.adoc index dbb08df9ce..ba37cba76e 100644 --- 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": diff --git a/documentation/content/en/books/fdp-primer/po-translations/_index.adoc b/documentation/content/en/books/fdp-primer/po-translations/_index.adoc index d3625a19ff..c160fbd9cb 100644 --- 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 .... ====== diff --git a/documentation/content/en/books/fdp-primer/translations/_index.adoc b/documentation/content/en/books/fdp-primer/translations/_index.adoc index f300e85085..c257293d6a 100644 --- 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. diff --git a/documentation/content/en/books/fdp-primer/working-copy/_index.adoc b/documentation/content/en/books/fdp-primer/working-copy/_index.adoc index facb05af1d..b6375a6e55 100644 --- 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]]
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?202104101446.13AEk8qJ008496>