Page MenuHomeFreeBSD
Files F152983157

D29573.diff
No OneTemporary
Actions

D29573.diff
View Options

diff --git a/documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc b/documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc
--- a/documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc
+++ b/documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc
@@ -133,7 +133,7 @@
== 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
--- 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 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
--- a/documentation/content/en/books/fdp-primer/overview/_index.adoc
+++ b/documentation/content/en/books/fdp-primer/overview/_index.adoc
@@ -80,7 +80,7 @@
+
[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
--- 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 @@
+
[source,shell]
....
-# cd /usr/ports/editors/poedit
-# make install clean
+# pkg install poedit
....
====
@@ -61,22 +60,22 @@
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 @@
+
[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 @@
+
[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 @@
+
[source,shell]
....
+% cd ~/doc/documentation
% make
....
====
@@ -143,113 +157,94 @@
| 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 @@
[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 @@
+
[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 @@
.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 @@
[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
--- a/documentation/content/en/books/fdp-primer/translations/_index.adoc
+++ b/documentation/content/en/books/fdp-primer/translations/_index.adoc
@@ -65,10 +65,10 @@
[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 @@
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 @@
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 @@
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
--- 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 @@
[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 @@
[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 @@
[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]]

File Metadata

Mime Type
text/plain
Expires
Sun, Apr 19, 11:33 AM (3 h, 29 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
31765844
Default Alt Text
D29573.diff (14 KB)

Event Timeline