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 @@ -1,224 +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] +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/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 @@ -1,271 +1,282 @@ --- 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. |=== [[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. +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 .... ==== [[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. [[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 --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 --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. <.> `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/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 @@ -1,124 +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. 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. 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. [.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 crossref:working-copy[working-copy,The Working Copy]). + [source,shell] .... % git clone https://git.FreeBSD.org/doc.git ~/doc .... + . 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. + . *_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 +% 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. . 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. 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}. 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. 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 @@ -1,414 +1,418 @@ --- 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. [[po-translations-quick-start]] == Quick Start 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 +# pkg install poedit .... ==== [[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. +. 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/ .... ==== [[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. . 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 +% 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 .... ==== [[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 +% 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#. + . Check the generated file by rendering it to HTML and viewing it with a web browser: + [source,shell] .... +% cd ~/doc/documentation % 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. [[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# |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 <>. +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. [[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/#. +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 .... . Copy the content from the original book: + [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. ====== ==== [[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 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[]. 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 <>. +. 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]] == 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. [[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. [[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. 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 +% 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 @@ -1,227 +1,230 @@ --- 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 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. == 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. == 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: [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] ==== 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? 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. 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. == 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. 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. 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`. ==== +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. For example, a hypothetical Swedish translation might look like: [.programlisting] .... documentation/ content/ sv/ books/ faq/ - book.adoc + _index.adoc .... `sv` is the name of the translation, in [.filename]#lang# form. Note the two Makefiles, which will be used to build the documentation. Use git diff command to generate a diff and send it to the link:reviews.freebsd.org/[reviews system]. [source,shell] .... % git diff > sv-faq.diff .... 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. 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. 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. === 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 .... 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 .... 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 @@ -1,134 +1,135 @@ --- 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 +% cd ~/doc +% git pull --ff-only .... 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 +% 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 +% 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].