diff --git a/documentation/content/en/books/fdp-primer/book.adoc b/documentation/content/en/books/fdp-primer/book.adoc index 151fec0747..e7bf44db97 100644 --- a/documentation/content/en/books/fdp-primer/book.adoc +++ b/documentation/content/en/books/fdp-primer/book.adoc @@ -1,99 +1,101 @@ --- title: FreeBSD Documentation Project Primer for New Contributors authors: - author: The FreeBSD Documentation Project copyright: 1998-2023 The FreeBSD Documentation Project description: Everything you need to know in order to start contributing to the FreeBSD Documentation Project trademarks: ["freebsd", "general", "git"] tags: ["FDP", "documentation", "FreeBSD", "Index"] add_split_page_link: true --- = FreeBSD Documentation Project Primer for New Contributors :doctype: book :toc: macro :toclevels: 2 :icons: font :sectnums: :sectnumlevels: 6 :partnums: :source-highlighter: rouge :experimental: :book: true :pdf: false :images-path: books/fdp-primer/ ifdef::env-beastie[] ifdef::backend-html5[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] :chapters-path: content/{{% lang %}}/books/fdp-primer/ endif::[] ifdef::backend-pdf,backend-epub3[] :chapters-path: include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] :chapters-path: include::../../../../../shared/asciidoctor.adoc[] endif::[] [.abstract-title] Abstract Thank you for becoming a part of the FreeBSD Documentation Project. Your contribution is extremely valuable, and we appreciate it. This primer covers details needed to start contributing to the FreeBSD Documentation Project, or FDP, including tools, software, and the philosophy behind the Documentation Project. This is a work in progress. Corrections and additions are always welcome. ''' toc::[] :sectnums!: include::{chapters-path}preface/_index.adoc[leveloffset=+1] :sectnums: include::{chapters-path}overview/_index.adoc[leveloffset=+1] include::{chapters-path}tools/_index.adoc[leveloffset=+1] include::{chapters-path}working-copy/_index.adoc[leveloffset=+1] include::{chapters-path}structure/_index.adoc[leveloffset=+1] include::{chapters-path}doc-build/_index.adoc[leveloffset=+1] include::{chapters-path}asciidoctor-primer/_index.adoc[leveloffset=+1] include::{chapters-path}rosetta/_index.adoc[leveloffset=+1] include::{chapters-path}translations/_index.adoc[leveloffset=+1] include::{chapters-path}po-translations/_index.adoc[leveloffset=+1] +include::{chapters-path}weblate/_index.adoc[leveloffset=+1] + include::{chapters-path}manual-pages/_index.adoc[leveloffset=+1] include::{chapters-path}writing-style/_index.adoc[leveloffset=+1] include::{chapters-path}editor-config/_index.adoc[leveloffset=+1] include::{chapters-path}trademarks/_index.adoc[leveloffset=+1] include::{chapters-path}see-also/_index.adoc[leveloffset=+1] :sectnums!: include::{chapters-path}examples/_index.adoc[leveloffset=+1] :sectnums: diff --git a/documentation/content/en/books/fdp-primer/editor-config/_index.adoc b/documentation/content/en/books/fdp-primer/editor-config/_index.adoc index b0378594b0..c1e8e3fa3f 100644 --- a/documentation/content/en/books/fdp-primer/editor-config/_index.adoc +++ b/documentation/content/en/books/fdp-primer/editor-config/_index.adoc @@ -1,347 +1,347 @@ --- -title: Chapter 12. Editor Configuration +title: Chapter 13. Editor Configuration prev: books/fdp-primer/writing-style next: books/fdp-primer/trademarks description: Configuration used in the texts editors in the FreeBSD Documentation Project tags: ["editor", "configuration", "vim", "emacs", "FreeBSD"] showBookMenu: true weight: 13 path: "/books/fdp-primer/" --- [[editor-config]] = Editor Configuration :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 12 +:sectnumoffset: 13 :partnums: :source-highlighter: rouge :experimental: :images-path: books/fdp-primer/ ifdef::env-beastie[] ifdef::backend-html5[] :imagesdir: ../../../../images/{images-path} endif::[] ifndef::book[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] toc::[] endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] toc::[] include::../../../../../shared/asciidoctor.adoc[] endif::[] Adjusting your text editor configuration can make working on document files quicker and easier, and help documents conform to FDP guidelines. [[editor-config-vim]] == Vim Install from package:editors/vim[], or package:editors/vim-console[], then follow the configuration instructions in <>. More advanced users can use a proper linter like link:https://github.com/dense-analysis/ale[Ale] which can also act as a Vim link:https://langserver.org/[Language Server Protocol] client. [[editor-config-vim-use]] === Use Manual page writers can use the following keyboard shortcuts to reformat: * Press kbd:[P] to reformat paragraphs or text that has been selected in Visual mode. * Press kbd:[T] to replace groups of eight spaces with a tab. A linter named link:https://vale.sh[Vale] has been introduced to check grammatical and cosmetic errors on the documents. Vale has support for various editors and IDEs. Vale may already be installed as a dependency of the package:textproc/docproj[] meta-port. If not, install package:textproc/vale[] with: [source,console] .... $ pkg install vale .... Install link:https://github.com/dense-analysis/ale[Ale] to integrate into package:editors/vim[], for using package:textproc/vale[]. [source,console?prompt=%] .... % mkdir -p ~/.vim/pack/vendor/start % git clone --depth 1 https://github.com/dense-analysis/ale.git ~/.vim/pack/vendor/start/ale .... Users who are using plugin managers for package:editors/vim[] do not need the above and should follow the instructions of that plugin manager to install link:https://github.com/dense-analysis/ale[Ale]. At this moment due to a bug in link:https://vale.sh[Vale] it is necessary to copy the link:https://vale.sh[Vale] configuration to the home directory. Considering the repository was cloned into [.filename]#~/doc# copy as following: [source,console?prompt=%] .... % cp -R ~/doc/.vale* ~/ .... [[editor-config-vim-config]] === Configuration Edit [.filename]#~/.vimrc#, adding these lines to the end of the file: [source.programlisting,viml] .`~/.vimrc` .... if has("autocmd") au BufNewFile,BufRead *.adoc call Set_ADOC() au BufNewFile,BufRead *.[1-9] call Set_MAN() endif " has(autocmd) function Set_Highlights() "match ExtraWhitespace /^\s* \s*\|\s\+$/ return 0 endfunction " Set_Highlights_Adoc() function Set_Highlights_MAN() highlight default link OverLength ErrorMsg match OverLength /\%71v.\+/ return 0 endfunction " Set_Highlights_MAN() function ShowSpecial() setlocal list listchars=tab:>>,trail:*,eol:$ hi def link nontext ErrorMsg return 0 endfunction " ShowSpecial() function Set_COMMON() setlocal number setlocal shiftwidth=2 setlocal tabstop=8 setlocal softtabstop=2 setlocal formatprg="fmt -p" setlocal autoindent setlocal smartindent call ShowSpecial() call Set_Highlights() return 0 endfunction " Set_COMMON() function Set_ADOC() setlocal syntax=asciidoc setlocal filetype=asciidoc call Set_COMMON() return 0 endfunction " Set_ADOC() function Set_MAN() setlocal syntax=man setlocal filetype=man setlocal textwidth=70 " Rewrap paragraphs noremap P gqj " Replace spaces with tabs noremap T :s/ /\t/ call Set_COMMON() call Set_Highlights_MAN() return 0 endfunction " Set_Man() let g:ale_fixers = { \ '*': ['remove_trailing_lines', 'trim_whitespace'], \} let g:ale_linters = { \ 'asciidoc': ['vale'], \} let g:ale_fix_on_save = 1 .... [IMPORTANT] ====== Above configuration will automatically remove trailing line, trailing space and multiple spaces which might display additional unwanted changes in `git diff` output. In such cases properly mention that in the commit log. ====== [[editor-config-emacs]] == Emacs Install from package:editors/emacs[] or package:editors/emacs-devel[]. [[editor-config-emacs-validation]] === Validation Emacs's nxml-mode uses compact relax NG schemas for validating XML. A compact relax NG schema for FreeBSD's extension to DocBook 5.0 is included in the documentation repository. To configure nxml-mode to validate using this schema, create [.filename]#~/.emacs.d/schema/schemas.xml# and add these lines to the file: [source,xml] .`~/.emacs.d/schema/schemas.xml` .... .... [[editor-config-emacs-igor]] === Automated Proofreading with Flycheck and Igor The link:https://www.flycheck.org/[Flycheck] package is available from link:https://melpa.org/[Milkypostman's Emacs Lisp Package Archive] (MELPA). If MELPA is not already in Emacs's packages-archives, it can be added by evaluating [source,emacs-lisp] .... (add-to-list 'package-archives '("melpa" . "http://stable.melpa.org/packages/") t) .... Add the line to Emacs's initialization file (one of [.filename]#~/.emacs#, [.filename]#~/.emacs.el#, or [.filename]#~.emacs.d/init.el#) to make this change permanent. To install Flycheck, evaluate [source,emacs-lisp] .... (package-install 'flycheck) .... Create a Flycheck checker for package:textproc/igor[] by evaluating [source,emacs-lisp] .... (flycheck-define-checker igor "FreeBSD Documentation Project sanity checker. See URLs https://www.freebsd.org/docproj/ and http://www.freshports.org/textproc/igor/." :command ("igor" "-X" source-inplace) :error-parser flycheck-parse-checkstyle :modes (nxml-mode) :standard-input t) (add-to-list 'flycheck-checkers 'igor 'append) .... Again, add these lines to Emacs's initialization file to make the changes permanent. [[editor-config-emacs-specifc]] === FreeBSD Documentation Specific Settings To apply settings specific to the FreeBSD documentation project, create [.filename]#.dir-locals.el# in the root directory of the documentation repository and add these lines to the file: .... ;;; Directory Local Variables ;;; For more information see (info "(emacs) Directory Variables") ((nxml-mode (eval . (turn-on-auto-fill)) (fill-column . 70) (eval . (require 'flycheck)) (eval . (flycheck-mode 1)) (flycheck-checker . igor) (eval . (add-to-list 'rng-schema-locating-files "~/.emacs.d/schema/schemas.xml")))) .... [[editor-config-nano]] == nano Install from package:editors/nano[] or package:editors/nano-devel[]. [[editor-config-nano-config]] === Configuration Currently there is no adoc/asciidoc syntax highlight file with nano distribution. So let's create one from scratch and use an editor to create new file or add lines in the [.filename]#~/.nanorc# with these contents: [source] .`~/.nanorc` .... syntax "asciidoc" "\.(adoc|asc|asciidoc)$" # main header color red "^====+$" # h1 color red "^==[[:space:]].*$" color red "^----+$" # h2 color magenta "^===[[:space:]].*$" color magenta "^~~~~+$" # h4 color green "^====[[:space:]].*$" color green "^\^\^\^\^+$" # h5 color brightblue "^=====[[:space:]].*$" color brightblue "^\+\+\+\++$" # attributes color brightgreen ":.*:" color brightred "\{[a-z0-9]*\}" color red "\\\{[a-z0-9]*\}" color red "\+\+\+\{[a-z0-9]*\}\+\+\+" # Paragraph Title color yellow "^\..*$" # source color magenta "^\[(source,.+|NOTE|TIP|IMPORTANT|WARNING|CAUTION)\]" # Other markup color yellow ".*[[:space:]]\+$" color yellow "_[^_]+_" color yellow "\*[^\*]+\*" color yellow "\+[^\+]+\+" color yellow "`[^`]+`" color yellow "\^[^\^]+\^" color yellow "~[^~]+~" color yellow "'[^']+'" color cyan "`{1,2}[^']+'{1,2}" # bullets color brightmagenta "^[[:space:]]*[\*\.-]{1,5}[[:space:]]" # anchors color brightwhite "\[\[.*\]\]" color brightwhite "<<.*>>" # trailing whitespace color ,blue "[[:space:]]+$" # multiples of eight spaces at the start a line # (after zero or more tabs) should be a tab color ,blue "^([TAB]*[ ]{8})+" # tabs after spaces color ,yellow "( )+TAB" # highlight indents that have an odd number of spaces color ,red "^(([ ]{2})+|(TAB+))*[ ]{1}[^ ]{1}" .... Process the file to create embedded tabs: [source,console?prompt=%] .... % perl -i'' -pe 's/TAB/\t/g' ~/.nanorc .... [[editor-config-nano-use]] === Use Specify additional helpful options when running the editor: [source,console?prompt=%] .... % nano -AKipwz -T8 _index.adoc .... Users of man:csh[1] can define an alias in [.filename]#~/.cshrc# to automate these options: [source,shell] .... alias nano "nano -AKipwz -r 70 -T8" .... After the alias is defined, the options will be added automatically: [source,console?prompt=%] .... % nano _index.adoc .... diff --git a/documentation/content/en/books/fdp-primer/manual-pages/_index.adoc b/documentation/content/en/books/fdp-primer/manual-pages/_index.adoc index c2336f5b14..206704c902 100644 --- a/documentation/content/en/books/fdp-primer/manual-pages/_index.adoc +++ b/documentation/content/en/books/fdp-primer/manual-pages/_index.adoc @@ -1,561 +1,561 @@ --- -title: Chapter 10. Manual Pages -prev: books/fdp-primer/po-translations +title: Chapter 11. Manual Pages +prev: books/fdp-primer/weblate next: books/fdp-primer/writing-style description: How to work with the FreeBSD Manual Pages tags: ["manual pages", "introduction", "guide", "reference"] showBookMenu: true weight: 11 path: "/books/fdp-primer/" --- [[manual-pages]] = Manual Pages :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 10 +:sectnumoffset: 11 :partnums: :source-highlighter: rouge :experimental: :images-path: books/fdp-primer/ ifdef::env-beastie[] ifdef::backend-html5[] :imagesdir: ../../../../images/{images-path} endif::[] ifndef::book[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] toc::[] endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] toc::[] include::../../../../../shared/asciidoctor.adoc[] endif::[] [[manual-pages-introduction]] == Introduction _Manual pages_, commonly shortened to _man pages_, were conceived as readily-available reminders for command syntax, device driver details, or configuration file formats. They have become an extremely valuable quick-reference from the command line for users, system administrators, and programmers. Although intended as reference material rather than tutorials, the EXAMPLES sections of manual pages often provide detailed use case. Manual pages are generally shown interactively by the man:man[1] command. When the user types `man ls`, a search is performed for a manual page matching `ls`. The first matching result is displayed. [[manual-pages-sections]] == Sections Manual pages are grouped into _sections_. Each section contains manual pages for a specific category of documentation: [.informaltable] [cols="1,8", options="header"] |=== | Section Number | Category |1 |General Commands |2 |System Calls |3 |Library Functions |4 |Kernel Interfaces |5 |File Formats |6 |Games |7 |Miscellaneous |8 |System Manager |9 |Kernel Developer |=== [[manual-pages-markup]] == Markup Various markup forms and rendering programs have been used for manual pages. FreeBSD has used man:groff[7] and the newer man:mandoc[1]. Most existing FreeBSD manual pages, and all new ones, use the man:mdoc[7] form of markup. This is a simple line-based markup that is reasonably expressive. It is mostly semantic: parts of text are marked up for what they are, rather than for how they should appear when rendered. There is some appearance-based markup which is usually best avoided. Manual page source is usually interpreted and displayed to the screen interactively. The source files can be ordinary text files or compressed with man:gzip[1] to save space. Manual pages can also be rendered to other formats, including PostScript for printing or PDF generation. See man:man[1]. [[manual-pages-markup-sections]] === Manual Page Sections Manual pages are composed of several standard sections. Each section has a title in upper case, and the sections for a particular type of manual page appear in a specific order. For a category 1 General Command manual page, the sections are: [.informaltable] [cols="2,4", options="header"] |=== | Section Name | Description |NAME |Name of the command |SYNOPSIS |Format of options and arguments |DESCRIPTION |Description of purpose and usage |ENVIRONMENT |Environment settings that affect operation |EXIT STATUS |Error codes returned on exit |EXAMPLES |Examples of usage |COMPATIBILITY |Compatibility with other implementations |SEE ALSO |Cross-reference to related manual pages |STANDARDS |Compatibility with standards like POSIX |HISTORY |History of implementation |BUGS |Known bugs |AUTHORS |People who created the command or wrote the manual page. |=== Some sections are optional, and the combination of sections for a specific type of manual page vary. Examples of the most common types are shown later in this chapter. [[manual-pages-markup-macros]] === Macros man:mdoc[7] markup is based on _macros_. Lines that begin with a dot contain macro commands, each two or three letters long. For example, consider this portion of the man:ls[1] manual page: [.programlisting] .... .Dd December 1, 2015 <.> .Dt LS 1 .Sh NAME <.> .Nm ls .Nd list directory contents .Sh SYNOPSIS <.> .Nm <.> .Op Fl -libxo <.> .Op Fl ABCFGHILPRSTUWZabcdfghiklmnopqrstuwxy1, <.> .Op Fl D Ar format <.> .Op Ar <.> .Sh DESCRIPTION <.> For each operand that names a .Ar file of a type other than directory, .Nm displays its name as well as any requested, associated information. For each operand that names a .Ar file of type directory, .Nm displays the names of files contained within that directory, as well as any requested, associated information. .... <.> A _Document date_ and _Document title_ are defined. <.> A _Section header_ for the NAME section is defined. Then the _Name_ of the command and a one-line _Name description_ are defined. <.> The SYNOPSIS section begins. This section describes the command-line options and arguments accepted. <.> _Name_ (`.Nm`) has already been defined, and repeating it here just displays the defined value in the text. <.> An _Optional_ _Flag_ called `-libxo` is shown. The `Fl` macro adds a dash to the beginning of flags, so this appears in the manual page as `--libxo`. <.> A long list of optional single-character flags are shown. <.> An optional `-D` flag is defined. If the `-D` flag is given, it must be followed by an _Argument_. The argument is a _format_, a string that tells man:ls[1] what to display and how to display it. Details on the format string are given later in the manual page. <.> A final optional argument is defined. Since no name is specified for the argument, the default of `file ...` is used. <.> The _Section header_ for the DESCRIPTION section is defined. When rendered with the command `man ls`, the result displayed on the screen looks like this: [.programlisting] .... LS(1) FreeBSD General Commands Manual LS(1) NAME ls - list directory contents SYNOPSIS ls [--libxo] [-ABCFGHILPRSTUWZabcdfghiklmnopqrstuwxy1,] [-D format] [file ...] DESCRIPTION For each operand that names a file of a type other than directory, ls displays its name as well as any requested, associated information. For each operand that names a file of type directory, ls displays the names of files contained within that directory, as well as any requested, associated information. .... Optional values are shown inside square brackets. [[manual-pages-markup-guidelines]] === Markup Guidelines The man:mdoc[7] markup language is not very strict. For clarity and consistency, the FreeBSD Documentation project adds some additional style guidelines: Only the first letter of macros is upper case:: Always use upper case for the first letter of a macro and lower case for the remaining letters. Begin new sentences on new lines:: Start a new sentence on a new line, do not begin it on the same line as an existing sentence. Update `.Dd` when making non-trivial changes to a manual page:: The _Document date_ informs the reader about the last time the manual page was updated. It is important to update whenever non-trivial changes are made to the manual pages. Trivial changes like spelling or punctuation fixes that do not affect usage can be made without updating `.Dd`. Give examples:: Show the reader examples when possible. Even trivial examples are valuable, because what is trivial to the writer is not necessarily trivial to the reader. Three examples are a good goal. A trivial example shows the minimal requirements, a serious example shows actual use, and an in-depth example demonstrates unusual or non-obvious functionality. Include the BSD license:: Include the BSD license on new manual pages. The preferred license is available from the extref:{committers-guide}[Committer's Guide]. [[manual-pages-markup-tricks]] === Markup Tricks Add a space before punctuation on a line with macros. Example: [.programlisting] .... .Sh SEE ALSO .Xr geom 4 , .Xr boot0cfg 8 , .Xr geom 8 , .Xr gptboot 8 .... Note how the commas at the end of the `.Xr` lines have been placed after a space. The `.Xr` macro expects two parameters to follow it, the name of an external manual page, and a section number. The space separates the punctuation from the section number. Without the space, the external links would incorrectly point to section `4,` or `8,`. [[manual-pages-markup-important-macros]] === Important Macros Some very common macros will be shown here. For more usage examples, see man:mdoc[7], man:groff_mdoc[7], or search for actual use in [.filename]#/usr/share/man/man*# directories. For example, to search for examples of the `.Bd` _Begin display_ macro: [source,shell] .... % find /usr/share/man/man* | xargs zgrep '.Bd' .... [[manual-pages-markup-important-macros-organizational]] ==== Organizational Macros Some macros are used to define logical blocks of a manual page. [.informaltable] [cols="1,8", options="header"] |=== | Organizational Macro | Use |`.Sh` |Section header. Followed by the name of the section, traditionally all upper case. Think of these as chapter titles. |`.Ss` |Subsection header. Followed by the name of the subsection. Used to divide a `.Sh` section into subsections. |`.Bl` |Begin list. Start a list of items. |`.El` |End a list. |`.Bd` |Begin display. Begin a special area of text, like an indented area. |`.Ed` |End display. |=== [[manual-pages-markup-important-macros-inline]] ==== Inline Macros Many macros are used to mark up inline text. [.informaltable] [cols="1,8", options="header"] |=== | Inline Macro | Use |`.Nm` |Name. Called with a name as a parameter on the first use, then used later without the parameter to display the name that has already been defined. |`.Pa` |Path to a file. Used to mark up filenames and directory paths. |=== [[manual-pages-sample-structures]] == Sample Manual Page Structures This section shows minimal desired man page contents for several common categories of manual pages. [[manual-pages-sample-structures-section-1-8]] === Section 1 or 8 Command The preferred basic structure for a section 1 or 8 command: [.programlisting] .... .Dd August 25, 2017 .Dt EXAMPLECMD 8 .Os .Sh NAME .Nm examplecmd .Nd "command to demonstrate section 1 and 8 man pages" .Sh SYNOPSIS .Nm .Op Fl v .Sh DESCRIPTION The .Nm utility does nothing except demonstrate a trivial but complete manual page for a section 1 or 8 command. .Sh SEE ALSO .Xr exampleconf 5 .Sh AUTHORS .An Firstname Lastname Aq Mt flastname@example.com .... [[manual-pages-sample-structures-section-4]] === Section 4 Device Driver The preferred basic structure for a section 4 device driver: [.programlisting] .... .Dd August 25, 2017 .Dt EXAMPLEDRIVER 4 .Os .Sh NAME .Nm exampledriver .Nd "driver to demonstrate section 4 man pages" .Sh SYNOPSIS To compile this driver into the kernel, add this line to the kernel configuration file: .Bd -ragged -offset indent .Cd "device exampledriver" .Ed .Pp To load the driver as a module at boot, add this line to .Xr loader.conf 5 : .Bd -literal -offset indent exampledriver_load="YES" .Ed .Sh DESCRIPTION The .Nm driver provides an opportunity to show a skeleton or template file for section 4 manual pages. .Sh HARDWARE The .Nm driver supports these cards from the aptly-named Nonexistent Technologies: .Pp .Bl -bullet -compact .It NT X149.2 (single and dual port) .It NT X149.8 (single port) .El .Sh DIAGNOSTICS .Bl -diag .It "flashing green light" Something bad happened. .It "flashing red light" Something really bad happened. .It "solid black light" Power cord is unplugged. .El .Sh SEE ALSO .Xr example 8 .Sh HISTORY The .Nm device driver first appeared in .Fx 49.2 . .Sh AUTHORS .An Firstname Lastname Aq Mt flastname@example.com .... [[manual-pages-sample-structures-section-5]] === Section 5 Configuration File The preferred basic structure for a section 5 configuration file: [.programlisting] .... .Dd August 25, 2017 .Dt EXAMPLECONF 5 .Os .Sh NAME .Nm example.conf .Nd "config file to demonstrate section 5 man pages" .Sh DESCRIPTION .Nm is an example configuration file. .Sh SEE ALSO .Xr example 8 .Sh AUTHORS .An Firstname Lastname Aq Mt flastname@example.com .... [[manual-pages-testing]] == Testing Testing a new manual page can be challenging. Fortunately there are some tools that can assist in the task. Some of them, like man:man[1], do not look in the current directory. It is a good idea to prefix the filename with `./` if the new manual page is in the current directory. An absolute path can also be used. Use man:mandoc[1]'s linter to check for parsing errors: [source,shell] .... % mandoc -T lint ./mynewmanpage.8 .... Use package:textproc/igor[] to proofread the manual page: [source,shell] .... % igor ./mynewmanpage.8 .... Use man:man[1] to check the final result of your changes: [source,shell] .... % man ./mynewmanpage.8 .... You can use man:col[1] to filter the output of man:man[1] and get rid of the backspace characters before loading the result in your favorite editor for spell checking: [source,shell] .... % man ./mynewmanpage.8 | col -b | vim -R - .... Spell-checking with fully-featured dictionaries is encouraged, and can be accomplished by using package:textproc/hunspell[] or package:textproc/aspell[] combined with package:textproc/en-hunspell[] or package:textproc/en-aspell[], respectively. For instance: [source,shell] .... % aspell check --lang=en --mode=nroff ./mynewmanpage.8 .... [[manual-pages-examples-as-templates]] == Example Manual Pages to Use as Templates Some manual pages are suitable as in-depth examples. [.informaltable] [cols="1,4", options="header"] |=== | Manual Page | Path to Source Location |man:cp[1] |[.filename]#/usr/src/bin/cp/cp.1# |man:vt[4] |[.filename]#/usr/src/share/man/man4/vt.4# |man:crontab[5] |[.filename]#/usr/src/usr.sbin/cron/crontab/crontab.5# |man:gpart[8] |[.filename]#/usr/src/sbin/geom/class/part/gpart.8# |=== [[manual-pages-resources]] == Resources Resources for manual page writers: * man:man[1] * man:mandoc[1] * man:groff_mdoc[7] * http://manpages.bsd.lv/mdoc.html[Practical UNIX Manuals: mdoc] * http://manpages.bsd.lv/history.html[History of UNIX Manpages] diff --git a/documentation/content/en/books/fdp-primer/po-translations/_index.adoc b/documentation/content/en/books/fdp-primer/po-translations/_index.adoc index fc6da5fcb8..8531b11576 100644 --- a/documentation/content/en/books/fdp-primer/po-translations/_index.adoc +++ b/documentation/content/en/books/fdp-primer/po-translations/_index.adoc @@ -1,441 +1,394 @@ --- title: Chapter 9. PO Translations prev: books/fdp-primer/translations -next: books/fdp-primer/manual-pages +next: books/fdp-primer/weblate description: How to work with PO translation in the FreeBSD Documentation Project tags: ["po", "translations", "tutorial", "quick start"] showBookMenu: true -weight: 10 +weight: 9 path: "/books/fdp-primer/" --- [[po-translations]] = PO Translations :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :sectnumoffset: 9 :partnums: :source-highlighter: rouge :experimental: :images-path: books/fdp-primer/ ifdef::env-beastie[] ifdef::backend-html5[] :imagesdir: ../../../../images/{images-path} endif::[] ifndef::book[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] toc::[] endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] toc::[] include::../../../../../shared/asciidoctor.adoc[] endif::[] [[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 extref:{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] .... # 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. 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/documentation/content/es/articles/leap-seconds .... -. Copy the [.filename]#_index.adoc# from the original document into the translation directory: +. Copy the [.filename]#_index.po# from the original document into the translation directory: + [source,shell] .... -% cp ~/doc/documentation/content/en/articles/leap-seconds/_index.adoc \ +% cp ~/doc/documentation/content/en/articles/leap-seconds/_index.po \ ~/doc/documentation/content/es/articles/leap-seconds/ .... + +Suppose the document or language is also being translated via Weblate. +In that case, it is good to get the `.po` file from there and upload the translation document back into the platform, centralizing the translating efforts via Weblate to avoid rework. + +See how to download the `.po` files in the crossref:weblate[weblate-translating-offline,Translating Offline on Weblate] chapter. ==== [[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. +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. -. Extract the translatable strings from the original English version into a PO file: -+ -[source,shell] -.... -% cd ~/doc -% po4a-gettextize \ - --format asciidoc \ - --option compat=asciidoctor \ - --option yfm_keys=title,part,description \ - --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. -+ [source,shell] .... % 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 -% po4a-translate \ - --format asciidoc \ - --option compat=asciidoctor \ - --option yfm_keys=title,part,description \ - --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 +% ./tools/translate.sh documentation es articles/leap-seconds .... + 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", frame="none", options="header"] |=== | Language | Region | Translated Directory Name |English |United States |[.filename]#en# |Bengali |Bangladesh |[.filename]#bn-bd# |Danish |Denmark |[.filename]#da# |German |Germany |[.filename]#de# |Greek |Greece |[.filename]#el# |Spanish |Spain |[.filename]#es# |French |France |[.filename]#fr# |Hungarian |Hungary |[.filename]#hu# |Italian |Italy |[.filename]#it# |Japanese |Japan |[.filename]#ja# |Korean |Korea |[.filename]#ko# |Mongolian |Mongolia |[.filename]#mn# |Dutch |Netherlands |[.filename]#nl# |Polish |Poland |[.filename]#pl# |Portuguese |Brazil |[.filename]#pt-br# |Russian |Russia |[.filename]#ru# |Turkish |Turkey |[.filename]#tr# |Chinese |China |[.filename]#zh-cn# |Chinese |Taiwan |[.filename]#zh-tw# |=== The translations are in subdirectories of the main documentation directory, here assumed to be [.filename]#~/doc/documentation/# as shown in crossref:overview[overview-quick-start, 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/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 extref:{porters-handbook}[Porter's Handbook]. The original is a book in [.filename]#~/doc/documentation/content/en/books/porters-handbook/#. [.procedure] ====== . 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/documentation/content/es/books % mkdir porters-handbook .... . Copy the content from the original book: + [source,shell] .... % 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] +[IMPORTANT] ==== - -[.procedure] -====== -. Change to the base directory and update all PO files. -+ -[source,shell] -.... -% cd ~/doc -% po4a-gettextize \ - --format asciidoc \ - --option compat=asciidoctor \ - --option yfm_keys=title,part,description \ - --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 documentation/content/es/books/porters-handbook/_index.po -.... -====== - -These steps are necessary for all `.adoc` files, excluding `chapters-order.adoc` and `toc-*.adoc`. - +Translating documents online proves to be the easiest method for document translation on FreeBSD, as it allows multiple users to collaborate on the same file, distributing the workload effectively. +For more details, please refer to the next chapter, crossref:weblate[weblate-introduction,Weblate Translations]. ==== [[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 " "extref:{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 " "extref:{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. +The Weblate chapter provides a complete example of how to crossref:weblate[weblate-building,Build the Translated Document]. + [[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 documentation/content/es/articles/nanobsd/ > /tmp/es_nanobsd.diff .... ====== +The Weblate chapter provides a complete example of how to crossref:weblate[weblate-submitting-translations,Submit the New Translation]. + ==== diff --git a/documentation/content/en/books/fdp-primer/see-also/_index.adoc b/documentation/content/en/books/fdp-primer/see-also/_index.adoc index 89905aa28d..a7312e980d 100644 --- a/documentation/content/en/books/fdp-primer/see-also/_index.adoc +++ b/documentation/content/en/books/fdp-primer/see-also/_index.adoc @@ -1,77 +1,77 @@ --- -title: Chapter 14. See Also +title: Chapter 15. See Also prev: books/fdp-primer/trademarks/ next: books/fdp-primer/examples description: More information about the FreeBSD Documentation Project tags: ["additional information", "AsciiDoctor", "HTML"] showBookMenu: true weight: 15 path: "/books/fdp-primer/" --- [[see-also]] = See Also :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 14 +:sectnumoffset: 15 :partnums: :source-highlighter: rouge :experimental: :images-path: books/fdp-primer/ ifdef::env-beastie[] ifdef::backend-html5[] :imagesdir: ../../../../images/{images-path} endif::[] ifndef::book[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] toc::[] endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] toc::[] include::../../../../../shared/asciidoctor.adoc[] endif::[] This document is deliberately not an exhaustive discussion of AsciiDoc and the FreeBSD Documentation Project. For more information about these, you are encouraged to see the following web sites. [[see-also-fdp]] == The FreeBSD Documentation Project * link:https://www.FreeBSD.org/docproj/[The FreeBSD Documentation Project web pages] * extref:{handbook}[The FreeBSD Handbook] [[see-also-hugo]] == Hugo * link:https://gohugo.io/[Hugo] * link:https://gohugo.io/documentation/[Hugo documentation] [[see-also-asciidoc]] == AsciiDoctor * link:https://asciidoctor.org/[AsciiDoctor] * link:https://docs.asciidoctor.org/[AsciiDoctor Documentation Portal] [[see-also-html]] == HTML * link:http://www.w3.org/[The World Wide Web Consortium] * link:https://dev.w3.org/html5/spec-LC/[The HTML 5 specification] * link:https://www.w3.org/Style/CSS/specs.en.html[CSS specification] * link:https://sass-lang.com/[Sass] diff --git a/documentation/content/en/books/fdp-primer/trademarks/_index.adoc b/documentation/content/en/books/fdp-primer/trademarks/_index.adoc index a57a2755c8..476716295a 100644 --- a/documentation/content/en/books/fdp-primer/trademarks/_index.adoc +++ b/documentation/content/en/books/fdp-primer/trademarks/_index.adoc @@ -1,97 +1,97 @@ --- -title: Chapter 13. Trademarks +title: Chapter 14. Trademarks prev: books/fdp-primer/editor-config/ next: books/fdp-primer/see-also description: Guidelines for trademarks in the FreeBSD Documentation Project tags: ["trademarks", "AsciiDoctor", "HTML"] showBookMenu: true weight: 14 path: "/books/fdp-primer/" --- [[trademarks]] = Trademarks :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 13 +:sectnumoffset: 14 :partnums: :source-highlighter: rouge :experimental: :images-path: books/fdp-primer/ ifdef::env-beastie[] ifdef::backend-html5[] :imagesdir: ../../../../images/{images-path} endif::[] ifndef::book[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] toc::[] endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] toc::[] include::../../../../../shared/asciidoctor.adoc[] endif::[] For all documents on the FreeBSD Documentation Project, citing registered trademarks is necessary and other trademarks is customary, and that is a requirement for every writer and contributor. [[trademark-symbols]] == Trademark Symbols Append a trademark symbol ((TM), (R), or other) to the first occurrence of the trademarked name, and always when using logos. Use the extref:{fdp-primer}/writing-style/#writing-style-special-characters[equivalent ASCII sequence], which will be rendered as the actual Unicode character. Also, write the trademarked name following its trademark guidelines. When in doubt, research the trademark owner's website, the product's website, and or the link:https://www.uspto.gov/trademarks[United States Patent and Trademark Office trademark search website]. [[trademark-citing]] == Trademark Citing The FreeBSD Documentation Project provides a template for citing trademarks, which also avoids duplicating trademarks in the documents. First, look for the trademark in the link:https://cgit.freebsd.org/doc/tree/documentation/themes/beastie/i18n/en.toml#n328[Copyright section in the project's template], then add it to the trademarks tag on the `Front Matter` section of the document, located at the beginning of each document. The following is an example of the `Front Matter` of the extref:{contributing}[Contributing to FreeBSD] article: .... --- title: Contributing to FreeBSD authors: - author: Jordan Hubbard - author: Sam Lawrance - author: Mark Linimon description: How to contribute to the FreeBSD Project trademarks: ["freebsd", "ieee", "general"] weight: 15 tags: ["Contributing", "FreeBSD", "Non-Programmer Tasks", "Programmer Tasks"] --- .... The trademark tags `freebsd`, `ieee`, and `general` will be automatically rendered when building the document like this: .... FreeBSD is a registered trademark of the FreeBSD Foundation. IEEE, POSIX, and 802 are registered trademarks of Institute of Electrical and Electronics Engineers, Inc. in the United States. Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this document, and the FreeBSD Project was aware of the trademark claim, the designations have been followed by the “™” or the “®” symbol. .... If a trademark is not present in the project's template, it must be submitted. Any developer or contributor can update the trademarks. The `freebsd` and `general` trademark tags are usually present in all documents. diff --git a/documentation/content/en/books/fdp-primer/weblate/_index.adoc b/documentation/content/en/books/fdp-primer/weblate/_index.adoc new file mode 100644 index 0000000000..83b234910c --- /dev/null +++ b/documentation/content/en/books/fdp-primer/weblate/_index.adoc @@ -0,0 +1,487 @@ +--- +title: Chapter 10. Weblate Translations +prev: books/fdp-primer/po-translations +next: books/fdp-primer/manual-pages +description: "How to join the FreeBSD translators team and translate online on Weblate" +tags: ["weblate", "po", "translations", "tutorial", "quick start"] +showBookMenu: true +weight: 10 +path: "/books/fdp-primer/" +--- + +[[weblate-translations]] += Weblate Translations +:doctype: book +:toc: macro +:toclevels: 1 +:icons: font +:sectnums: +:sectnumlevels: 6 +:sectnumoffset: 10 +:partnums: +:source-highlighter: rouge +:experimental: +:images-path: books/fdp-primer/ + +ifdef::env-beastie[] +ifdef::backend-html5[] +:imagesdir: ../../../../images/{images-path} +endif::[] +ifndef::book[] +include::shared/authors.adoc[] +include::shared/mirrors.adoc[] +include::shared/releases.adoc[] +include::shared/attributes/attributes-{{% lang %}}.adoc[] +include::shared/{{% lang %}}/teams.adoc[] +include::shared/{{% lang %}}/mailing-lists.adoc[] +include::shared/{{% lang %}}/urls.adoc[] +toc::[] +endif::[] +ifdef::backend-pdf,backend-epub3[] +include::../../../../../shared/asciidoctor.adoc[] +endif::[] +endif::[] + +ifndef::env-beastie[] +toc::[] +include::../../../../../shared/asciidoctor.adoc[] +endif::[] + +[[weblate-introduction]] +== Introduction + +This chapter describes some basic steps for joining the FreeBSD translators team, translating online on Weblate or offline, and some simple suggestions on translating, proofreading, and testing. +It's focused on the translation part. + +The original documents (articles and books) are in the {main-site}[documentation portal]. + +https://weblate.org/en/[Weblate] is web-based open-source software focused on localization; the FreeBSD project runs a local instance. + +[[weblate-become-translator]] +== How to Become a FreeBSD Translator + +Following are simple steps to start translating articles and books of the FreeBSD Documentation Project. + +. Create an account on the https://translate-dev.freebsd.org/[FreeBSD Weblate instance] with an email address or your GitHub account. +. Subscribe to the {freebsd-translators}. +. Introduce yourself and ask to join a language team. +If the language team does not exist, ask to create it. +The self-introduction is essential. +It raises your chances of being approved for write access. +. Login to https://translate-dev.freebsd.org/[Weblate] with the new account. +. Find the language team and choose an initial document to translate. +. Create a Bugzilla account to submit the translations after finishing a document. +The Documentation project is also accepting GitHub Pull Requests with translation submissions. + +[WARNING] +==== +All translation files and documents must follow https://www.freebsd.org/copyright/freebsd-doc-license/[The FreeBSD Documentation License]; if this is unacceptable, please do not sign up or send any patches or translations. +==== + +[[weblate-introduce-yourself]] +== Introduce Yourself + +Please provide a brief self-introduction on the {freebsd-translators} to initiate the process of granting access. +This will enable a language coordinator or administrator to provide the necessary permissions for the new user of Weblate to start translating. + +Following is an example of how such an email could look. + +[.programlisting] +.... +Subject: Self-Introduction: Name and language + +Name: Name (use preferred name) +Location: City, country (optional) +Login: username or email (essential) +Language: Language to translate (essential) +Profession or student status: (optional) +About You: (free format -- info which you feel comfortable sharing with + others: company, school, other affiliation, historical qualifications, other + projects you have worked on, level and type of computer skills, other relevant skills, + etc.) +You and the FreeBSD Project: (free format: other FreeBSD projects of + interest, comments, etc.) +.... + +[[weblate-login]] +== Login to Weblate + +Open https://translate-dev.freebsd.org/[] and `Sign in`. + +image::weblate-login.webp[Weblate Login,800] + +Use a username, email address, or GitHub account to log in. + +The user profile contains your preferences, name, and email address. +The name and address will be used in commits; keep this information accurate. + +On the FreeBSD Weblate instance, all translations will be committed to https://github.com/freebsd/freebsd-doc-translate[freebsd-doc-translate] (an intermediate repository on GitHub), not directly to https://github.com/freebsd/freebsd-doc[freebsd-doc]. +Translators must take the PO gettext files (`.po`), converting them to `.adoc` and submit it via https://bugs.freebsd.org/bugzilla/[Bugzilla] or https://github.com/freebsd/freebsd-doc/pulls[GitHub] to get the translated document published or updated in the documentation portal. +See more in the following sections. + +Weblate will commit daily, at least to `freebsd-doc-translate`, if any new strings are translated. + +[[weblate-find-language-team]] +== Find a Language Team to Join In + +Click `Projects`, choose `Documentation`, then click `Languages`, and see all the available languages. + +image::weblate-languages.webp[Weblate Languages,500] + +Note that some languages and translated documents already exist in the documentation portal and repositories. + +If the desired language for translation is not available in Weblate, please contact the https://www.freebsd.org/docproj/translations/[language coordinators] before asking to create a new language. +If there is no answer, then write to the {doceng}. + +[[weblate-translating-online]] +== Translating Online on Weblate + +Translating documents online proves to be the easiest method for document translation on FreeBSD, as it allows users to collaborate on the same file, distributing the workload. + +Once a coordinator or administrator grants access to a specific language for a username, the save button will be enabled, so that this user can start translating. + +image::weblate-documents.webp[Weblate Documents,800] +image::weblate-translate.webp[Weblate Translate,800] + +Weblate has a set of links that lead to actual translation. +The translation is further divided into individual checks, like `Untranslated` or `Needing review`. +If the whole document is translated without any error, `All translations` link is still available in case a review is necessary. +Alternatively, the search field can be used to find a specific string or term. + +In the https://docs.weblate.org/en/latest/user/translating.html#translation-projects[Weblate documentation], there is more info about translations, like keyboard shortcuts and other tips about the translation tool. + +[[weblate-translating-offline]] +== Translating Offline + +Weblate on FreeBSD uses PO gettext files for translations. +Users familiar with PO gettext files that want to translate offline can download and upload the translations through the document page on Weblate by clicking in the `Files` section. + +image::weblate-offline.webp[Weblate Offline,800] + +[[weblate-automatic-suggestions]] +== Translation based on Automatic Suggestions + +Languages using Weblate before the migration to Hugo/Asciidoctor can use this feature from Weblate to save time. + +This feature from Weblate uses the Translation Memory generated by the other components and projects on the same server. +The former Weblate translations are hosted on the same server as read-only for that. + +Strings that match `100/100` in similarity can be copied and saved directly. +Other strings will need at least minor adjustment. + +Some examples: + +image::weblate_automatic_suggestion_01.webp[Weblate Automatic Suggestions 01,800] + +With the migration to Hugo/Asciidoctor, documents use UTF-8. +Some HTML entities should be replaced. +Some strings, such as links, require changes to markup. + +image::weblate_automatic_suggestion_02.webp[Weblate Automatic Suggestions 02,800] + +Links: + +image::weblate_automatic_suggestion_03.webp[Weblate Automatic Suggestions 03,800] + +[[weblate-proofreading-qa]] +== Proofreading and Weblate Quality Checks + +The document dashboard `Project/Language/Document` shows the translation status and string status for that document. +This page is handy for proofreading and quality checks. + +image::weblate-revision1.webp[Weblate Revision 01,800] + +In this example, two strings are missing the full stop; following that link will show only those strings to be revised/translated. + +image::weblate-revision2.webp[Weblate Revision 02,800] + +Translators and reviewers often value observing translated strings in context. + +[[weblate-building]] +== Building the Translated Document + +The project does not use continuous integration and continuous delivery to build translations. +There are studies to make it available. + +[NOTE] +==== +The following example uses GitHub, as Weblate is also on GitHub. +Note that this repository is a read-only mirror, but Pull Requests are accepted. +==== + +To build the translation locally, follow these steps: + +[[weblate-clone-repositories]] + +[.procedure] +==== +.Procedure: Clone the necessary repositories +. Clone the `freebsd-doc` repository: ++ +[source,console?prompt=%] +.... +% git clone https://github.com/freebsd/freebsd-doc.git ~/freebsd-doc +.... + +. Clone the `freebsd-doc-translate` repository: ++ +[source,console?prompt=%] +.... +% git clone https://github.com/freebsd/freebsd-doc-translate.git ~/freebsd-doc-translate +.... +==== + +[[weblate-copy-translation]] + +[.procedure] +==== +.Procedure: Copy a translation file to `freebsd-doc` + +With both repositories in place, copy the translation from `freebsd-doc-translate` to `freebsd-doc`. +Example of the Committer's Guide article translation in Spanish. + +[source,console?prompt=%] +.... +% cp ~/freebsd-doc-translate/documentation/content/es/articles/committers-guide/_index.po \ +~/freebsd-doc/documentation/content/es/articles/committers-guide/ +.... +==== + +[[weblate-translate]] + +[.procedure] +==== +.Procedure: Convert a translation file (`.po`) to `.adoc` + +Go to the root of `freebsd-doc`. + +[source,console?prompt=%] +.... +% cd ~/freebsd-doc +.... + +Translate (convert) the `.po` file to `.adoc` + +[source,console?prompt=%] +.... +% ./tools/translate.sh documentation es articles/committers-guide +.... + +By default: only files with more than eighty percent of strings translated will be converted to `.adoc`. + +To ignore that limit: + +[source,console?prompt=%] +.... +% KEEP_ENV=0 ./tools/translate.sh documentation es articles/committers-guide +.... + +==== + +Some documents, like books, have many PO gettext files. +Always copy all of them when translating and building. +Files that weren't translated will be converted with the source (English) strings. + +[WARNING] +==== +The directory structure is fundamental. +Always follow the English document directory structure. +==== + +[[weblate-build]] + +[.procedure] +==== +.Procedure: Build the translated document + +Last, the building part. + +Enter the documentation directory because there is no need to build the FreeBSD website. + +[source,console?prompt=%] +.... +% cd documentation +.... + +And build the documentation. +Note that `en` is always added by default when building any other language. + +[source,console?prompt=%] +.... +% DOC_LANG=es make +.... + +This command will build only the English and Spanish documents of the FreeBSD documentation portal. +The output will be in the [.filename]#public# directory; open that in a browser. +Note that some index files can redirect the browser to the online page. + +Another good option is to build and serve the content with Hugo's internal webserver: + +[source,console?prompt=%] +.... +% DOC_LANG=es make run +.... + +By default, the webserver listens on `localhost`; To override this behavior, specify the desired IP address in the `BIND` parameter value. + +[source,console?prompt=%] +.... +% DOC_LANG=es make run BIND=192.168.15.10 +.... + +This builds and serves the content with Hugo's internal webserver and lets it open, and if any file changes, it rebuilds them automatically. +==== + +To make any necessary adjustments in the translation, follow the steps below to re-sync all components: + +- Fix the translation string on https://translate-dev.freebsd.org/[Weblate]. +- Force Weblate to commit the changes on `Document/Manage/Commit` section. +- Sync the local Weblate repository `freebsd-doc-translate` with a `git pull origin main` command. +- Copy the translation again to `freebsd-doc`. +- Convert the translation to .adoc with the `./tools/translate.sh` script. +- Hugo will rebuild the file and not build the entire set if `make run` was used; or re-execute `make`. + +[IMPORTANT] +==== +Follow the previous steps as many times as is necessary until the document is ready to be published. +==== + +The crossref:doc-build[doc-build-rendering,Documentation Build Process] chapter includes information about rendering to HTML and PDF. + +[[weblate-submitting-translations]] +== Submitting Translations + +Example of submitting an update to the Brazilian Portuguese article Committer's Guide. + + +[[weblate-git-repo-status]] + +[.procedure] +==== +.Check the repository + +After following the steps in crossref:weblate[weblate-building,Building the Translated Document], go to the root of `freebsd-doc` and preview what's to be committed. +For an overview of files to be changed, and differences in file content: + +[source,console?prompt=%] +.... +% git status +% git diff +.... + +Review the output, and if any files unrelated to the Committer's Guide translation update were changed or added, take the appropriate action of reverting or removing them, respectively, before proceeding further. + +Always include the PO gettext file (`.po`) and the translated document in Hugo/Asciidoctor (`.adoc`). +==== + +[[weblate-git-new-branch]] + +[.procedure] +==== +.Create a new branch and commit + +Create another branch to separate the work, which will help with future updates in the local repository. + +[source,console?prompt=%] +.... +% git checkout -b committers-guide_pt-br +.... + +Register the local commit. + +[source,console?prompt=%] +.... +% git add . +% git commit +.... + +Example of commit messages for translations: + +[.programlisting] +.... +pt-br/committers-guide: Sync with en XXXXXXX +.... + +Where `XXXXXXX` is the man:git[1] revision stored in the Weblate repository [.filename]#~/freebsd-doc-translate/revision.txt#. + +If it is the first translation of an article: + +[.programlisting] +.... +Add Korean translation of Leap Seconds article +.... + +A message will be displayed after the commit if man:git[1] has not been configured previously. +Please follow the instructions and provide the name and email address used on Weblate. +This step is crucial to proper crediting of contributors. + +Then check the entire commit, review changes, and author name and email. + +[source,console?prompt=%] +.... +% git show +.... +==== + +[[weblate-git-patch-submit]] + +[.procedure] +==== +.Generate a patch + +Next, generate a man:git-format-patch[1] file. + +[source,console?prompt=%] +.... +% git format-patch main +0001-pt-br-committers-guide-Sync-with-en-XXXXXXX.patch +.... +==== + +Attach the patch [.filename]#0001-pt-br-committers-guide-Sync-with-en-XXXXXXX.patch# to a problem report in https://bugs.freebsd.org/bugzilla/[FreeBSD Bugzilla]. + +Include the following information in the report: + +[[weblate-bugzilla-fields]] +.Bugzilla Fields +[cols="1,1", frame="none", options="header"] +|=== +| Field +| Value + +| *product* +| Documentation + +| *Component* +| Books & Articles + +| *Summary* +| Same as the local commit + +| *Description* +| State that instructions in this guide were followed, including proofreading and other necessary steps. +Include things that may help with triage and progression of the report. + + +| *CC* (Optional) +| If the language has coordinators, include their email addresses in the CC field. +|=== + +For people familiar with man:git[1] and GitHub: instead of submitting the patch through https://bugs.freebsd.org/bugzilla/[Bugzilla], a https://github.com/freebsd/freebsd-doc/pulls[GitHub pull request] can be used (use the name and address that you use with Weblate). + +https://github.com/freebsd/freebsd-doc/ is a secondary mirror. +Changes to the `doc` tree can be made only by people who have a `doc` commit bit. + +When translators keep sending good-quality patches, they can be nominated by other committers to receive write-access (a extref:{committers-guide}[doc commit bit, committer.types] for translations), a FreeBSD account, and associated perks. + +The list of extref:{contributors}[Additional FreeBSD Contributors, contrib-additional] includes non-committers whose contributions are committed to the `doc` tree. + +If in doubt about any procedure, write to the {freebsd-translators}. + +[[weblate-faq]] +== FAQ (Frequently Asked Questions) + +[[weblate-copyrights]] +=== Is it necessary to translate all the Copyright messages? + +Every language team decides this for their language; in `pt-br` (Brazilian Portuguese) team, it was decided not to translate those messages. diff --git a/documentation/content/en/books/fdp-primer/writing-style/_index.adoc b/documentation/content/en/books/fdp-primer/writing-style/_index.adoc index fe9d704a8b..1cd3c92736 100644 --- a/documentation/content/en/books/fdp-primer/writing-style/_index.adoc +++ b/documentation/content/en/books/fdp-primer/writing-style/_index.adoc @@ -1,377 +1,377 @@ --- -title: Chapter 11. Writing Style +title: Chapter 12. Writing Style prev: books/fdp-primer/manual-pages next: books/fdp-primer/editor-config description: Writing Style and some conventions used in the FreeBSD Documentation Project tags: ["writing", "style", "typos", "one sentence per line"] showBookMenu: true weight: 12 path: "/books/fdp-primer/" --- [[writing-style]] = Writing Style :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 11 +:sectnumoffset: 12 :partnums: :source-highlighter: rouge :experimental: :images-path: books/fdp-primer/ ifdef::env-beastie[] ifdef::backend-html5[] :imagesdir: ../../../../images/{images-path} endif::[] ifndef::book[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] toc::[] endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] toc::[] include::../../../../../shared/asciidoctor.adoc[] endif::[] [[writing-style-tips]] == Tips Technical documentation can be improved by consistent use of several principles. Most of these can be classified into three goals: _be clear_, _be complete_, and _be concise_. These goals can conflict with each other. Good writing consists of a balance between them. [[writing-style-be-clear]] === Be Clear Clarity is extremely important. The reader may be a novice, or reading the document in a second language. Strive for simple, uncomplicated text that clearly explains the concepts. Avoid flowery or embellished speech, jokes, or colloquial expressions. Write as simply and clearly as possible. Simple text is easier to understand and translate. Keep explanations as short, simple, and clear as possible. Avoid empty phrases like "in order to", which usually just means "to". Avoid potentially patronizing words like "basically". Avoid Latin terms like "i.e.," or "cf.", which may be unknown outside of academic or scientific groups. Write in a formal style. Avoid addressing the reader as "you". For example, say "copy the file to [.filename]#/tmp#" rather than "you can copy the file to [.filename]#/tmp#". Give clear, correct, _tested_ examples. A trivial example is better than no example. A good example is better yet. Do not give bad examples, identifiable by apologies or sentences like "but really it should never be done that way". Bad examples are worse than no examples. Give good examples, because _even when warned not to use the example as shown_, the reader will usually just use the example as shown. Avoid _weasel words_ like "should", "might", "try", or "could". These words imply that the speaker is unsure of the facts, and create doubt in the reader. Similarly, give instructions as imperative commands: not "you should do this", but merely "do this". [[writing-style-be-complete]] === Be Complete Do not make assumptions about the reader's abilities or skill level. Tell them what they need to know. Give links to other documents to provide background information without having to recreate it. Put yourself in the reader's place, anticipate the questions they will ask, and answer them. [[writing-style-be-concise]] === Be Concise While features should be documented completely, sometimes there is so much information that the reader cannot easily find the specific detail needed. The balance between being complete and being concise is a challenge. One approach is to have an introduction, then a "quick start" section that describes the most common situation, followed by an in-depth reference section. [[writing-style-guidelines]] == Guidelines To promote consistency between the myriad authors of the FreeBSD documentation, some guidelines have been drawn up for authors to follow. Use American English Spelling:: There are several variants of English, with different spellings for the same word. Where spellings differ, use the American English variant. "color", not "colour", "rationalize", not "rationalise", and so on. + [NOTE] ==== The use of British English may be accepted in the case of a contributed article, however the spelling must be consistent within the whole document. The other documents such as books, web site, manual pages, etc. must use American English. ==== Do not use contractions:: Do not use contractions. Always spell the phrase out in full. "Don't use contractions" is wrong. + Avoiding contractions makes for a more formal tone, is more precise, and is slightly easier for translators. Use the serial comma:: In a list of items within a paragraph, separate each item from the others with a comma. Separate the last item from the others with a comma and the word "and". + For example: + This is a list of one, two and three items. + Is this a list of three items, "one", "two", and "three", or a list of two items, "one" and "two and three"? + It is better to be explicit and include a serial comma: + This is a list of one, two, and three items. Avoid redundant phrases:: Do not use redundant phrases. In particular, "the command", "the file", and "man command" are often redundant. + For example, commands: + Wrong: Use the `git` command to update sources. + Right: Use `git` to update sources. + Filenames: + Wrong: ... in the filename [.filename]#/etc/rc.local#... + Right: ... in [.filename]#/etc/rc.local#... + Manual page references (the second example uses `citerefentry` with the man:csh[1] entity): + Wrong: See `man csh` for more information. + Right: See man:csh[1]. For more information about writing style, see http://www.bartleby.com/141/[Elements of Style] by William Strunk. [[writing-style-guide]] == Style Guide To keep the source for the documentation consistent when many different people are editing it, please follow these style conventions. [[one-sentence-per-line]] == One sentence per line Use Semantic Line Breaks in the documentation, a technique called "one sentence per line". The idea of this technique is to help the users to write and read documentation. To get more information about this technique read the link:https://sembr.org/[Semantic Line Breaks] page. This is an example which does not use "one sentence per line". .... All human beings are born free and equal in dignity and rights. They are endowed with reason and conscience and should act towards one another in a spirit of brotherhood. .... And this is an example which uses the technique. .... All human beings are born free and equal in dignity and rights. They are endowed with reason and conscience and should act towards one another in a spirit of brotherhood. .... [[writing-style-acronyms]] == Acronyms Acronyms should be defined the first time they appear in a document, as in: "Network Time Protocol (NTP)". After the acronym has been defined, use the acronym alone unless it makes more sense contextually to use the whole term. Acronyms are usually defined only once per chapter or per document. All acronyms should be enclosed using the ` character. [[writing-style-special-characters]] == Special Character List This list of special characters shows the correct syntax and the output when used in FreeBSD documentation. If a character is not on this list, ask about it on the {freebsd-doc}. [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Name | Syntax | Rendered | Copyright | +(C)+ | (C) | Registered | +(R)+ | (R) | Trademark | +(TM)+ | (TM) | Em dash | +--+ | -- | Ellipses | +...+ | ... | Single right arrow | +->+ | -> | Double right arrow | +=>+ | => | Single left arrow | +<-+ | <- | Double left arrow | +<=+ | <= |=== [[writing-style-linting-vale]] == Linting with Vale To maintain clarity and consistency across all documentation and website pages, link:https://vale.sh[Vale] styles have been introduced in the documentation tree. link:https://vale.sh[Vale] is a powerful linter for writing customized rules and can be used in multiple scenarios. Currently link:https://vale.sh[Vale] can be used as a command line tool, for CI/CD pipelines, and integrated into an editor of choice. The following table describes the current rule names and their respective severity. [.informaltable] [cols="1,1", frame="none", options="header"] |=== | Name | Severity | FreeBSD.BrandTerms | error | FreeBSD.ConsciousLanguage | warning | FreeBSD.Contractions | suggestion | FreeBSD.EOLSpacing | warning | FreeBSD.Hang | warning | FreeBSD.Hyphens | warning | FreeBSD.Spacing | error | FreeBSD.SuperfluousOptArgInLinks | suggestion | Vale.Avoid | error | Vale.Repetition | error | Vale.Spelling | error | Vale.Terms | error |=== [[writing-style-linting-vale-rules]] === Current Vale Rules . FreeBSD.BrandTerms: According to the copyright rules of The FreeBSD Foundation, *freebsd* should be written as *FreeBSD*. Similarly, every major vendor and company has specific rules on writing their brand names and trademarks. Care should be taken to be respectful to the brand value of others and to take time to write PostgreSQL, Node.js, Let's Encrypt etc. Missing brand names should be added to the [.filename]#.vale/styles/FreeBSD/BrandTerms.yml# in the `doc` repository. . FreeBSD.ConsciousLanguage: This rule proposes use of conscious language so that sensitive words pointing to the color, age, race, or sexual orientation of people are avoided where possible. . FreeBSD.Contractions: Contracted words should not be used. This rule avoids all contractions and suggests full words. . FreeBSD.EOLSpacing: In most of the documents EOL spacing is present which is not the desirable situation. . FreeBSD.Hang: `Hang` is often used to mean that the application has stopped responding. This rule proposes better wording. . FreeBSD.Hyphens: Often adverbs ending with 'ly' are added with a hyphen which is wrong. . FreeBSD.Spacing: Often double spaces are hard to catch with the naked eye and this is addressed here. . FreeBSD.SuperfluousOptArgInLinks: Suggest to empty square brackets in `link:` macros when the displayed text coincides with the URL. . Vale.Avoid: Enforces the *DO NOT USE* vocabulary terms for The FreeBSD Project. If any word is found that should not be in the documentation, the word should be added to [.filename]#.vale/styles/Vocab/Terms/reject.txt# in the `doc` repository. The list is empty at the moment. . Vale.Repetition: Same words are often typed twice when leaving the keyboard and rejoining the work again. This rule finds repeated words and warns the users. . Vale.Spelling: At the moment there is a mix of en_US and en_GB spellings in the documentation and website. Vale comes with an in built dictionary from which uses strictly en_US and do not accept the en_GB variant of any words. . Vale.Terms: Enforces the *PREFERRED* vocabulary terms for The FreeBSD Project. At the moment the list of terms is empty and the FreeBSD specific terms will be added gradually. If any word is found to be correct and not available in the dictionary the word should be added to the [.filename]#.vale/styles/Vocab/Terms/accept.txt# in the `doc` repository. More rules will be introduced in the upcoming days when and where required. [[writing-style-using-vale]] === Using Vale link:https://vale.sh[Vale] can be used from the command line and from within an editor or IDE. package:textproc/vale[] can be installed as following: [source, shell] .... $ pkg install vale .... [[writing-style-using-vale-commandline]] ==== Using Vale on the command line Assuming that the `doc` repository was cloned into [.filename]#~/doc# the following commands are required to run: [source, shell] .... % cd ~/doc % vale . .... [NOTE] ====== link:https://vale.sh[Vale] is a CPU and memory intensive program due to the nature of the application and can take a while to show any output on the screen. A better way to run the application is on specific folders or files rather than the entire `doc` repository as that is already done in the CI pipeline. ====== [[writing-style-using-vale-editors]] ==== Using Vale in editors link:https://vale.sh[Vale] works with major mainstream editors like package:editors/vim[], package:editors/emacs[], package:editors/vscode[]. At the moment the necessary configuration for package:editors/vim[] is described in crossref:editor-config[editor-config-vim, Vim]. A configuration for package:editors/emacs[] is being worked on. diff --git a/documentation/static/images/books/fdp-primer/weblate-commit.webp b/documentation/static/images/books/fdp-primer/weblate-commit.webp new file mode 100644 index 0000000000..e5df1bcdb0 Binary files /dev/null and b/documentation/static/images/books/fdp-primer/weblate-commit.webp differ diff --git a/documentation/static/images/books/fdp-primer/weblate-documents.webp b/documentation/static/images/books/fdp-primer/weblate-documents.webp new file mode 100644 index 0000000000..866e33cb7f Binary files /dev/null and b/documentation/static/images/books/fdp-primer/weblate-documents.webp differ diff --git a/documentation/static/images/books/fdp-primer/weblate-languages.webp b/documentation/static/images/books/fdp-primer/weblate-languages.webp new file mode 100644 index 0000000000..cb1b65a788 Binary files /dev/null and b/documentation/static/images/books/fdp-primer/weblate-languages.webp differ diff --git a/documentation/static/images/books/fdp-primer/weblate-login.webp b/documentation/static/images/books/fdp-primer/weblate-login.webp new file mode 100644 index 0000000000..a947159de9 Binary files /dev/null and b/documentation/static/images/books/fdp-primer/weblate-login.webp differ diff --git a/documentation/static/images/books/fdp-primer/weblate-offline.webp b/documentation/static/images/books/fdp-primer/weblate-offline.webp new file mode 100644 index 0000000000..4ea4999f9a Binary files /dev/null and b/documentation/static/images/books/fdp-primer/weblate-offline.webp differ diff --git a/documentation/static/images/books/fdp-primer/weblate-revision1.webp b/documentation/static/images/books/fdp-primer/weblate-revision1.webp new file mode 100644 index 0000000000..939eb0b335 Binary files /dev/null and b/documentation/static/images/books/fdp-primer/weblate-revision1.webp differ diff --git a/documentation/static/images/books/fdp-primer/weblate-revision2.webp b/documentation/static/images/books/fdp-primer/weblate-revision2.webp new file mode 100644 index 0000000000..54242fa930 Binary files /dev/null and b/documentation/static/images/books/fdp-primer/weblate-revision2.webp differ diff --git a/documentation/static/images/books/fdp-primer/weblate-translate.webp b/documentation/static/images/books/fdp-primer/weblate-translate.webp new file mode 100644 index 0000000000..d9c3a76973 Binary files /dev/null and b/documentation/static/images/books/fdp-primer/weblate-translate.webp differ diff --git a/documentation/static/images/books/fdp-primer/weblate_automatic_suggestion_01.webp b/documentation/static/images/books/fdp-primer/weblate_automatic_suggestion_01.webp new file mode 100644 index 0000000000..6f760b2337 Binary files /dev/null and b/documentation/static/images/books/fdp-primer/weblate_automatic_suggestion_01.webp differ diff --git a/documentation/static/images/books/fdp-primer/weblate_automatic_suggestion_02.webp b/documentation/static/images/books/fdp-primer/weblate_automatic_suggestion_02.webp new file mode 100644 index 0000000000..ae12522ca0 Binary files /dev/null and b/documentation/static/images/books/fdp-primer/weblate_automatic_suggestion_02.webp differ diff --git a/documentation/static/images/books/fdp-primer/weblate_automatic_suggestion_03.webp b/documentation/static/images/books/fdp-primer/weblate_automatic_suggestion_03.webp new file mode 100644 index 0000000000..0c1aadeb73 Binary files /dev/null and b/documentation/static/images/books/fdp-primer/weblate_automatic_suggestion_03.webp differ