FreeBSD Documentation Project Primer for New Contributors

This table shows the default system prompt and superuser prompt. The examples use these prompts to indicate which type of user is running the example.

This table describes the typographic conventions used in this book.

Notes, warnings, and examples appear within the text.

My thanks to Sue Blake, Patrick Durusau, Jon Hamilton, Peter Flynn, and Christopher Maden, who took the time to read early drafts of this document and offer many valuable comments and criticisms.

All documents are for the benefit of their readers, not their writers or caretakers. They should adapt to the reader and not expect the reader to adapt to them.

Never blame the reader for:

Instead, acknowledge that the document is:

Then, make the document:

Use the following methods:

Some preparatory steps must be taken before editing the FreeBSD documentation. First, subscribe to the FreeBSD documentation project mailing list. Some team members also interact on the #bsddocs IRC channel on EFnet. These people can help with questions or problems involving the documentation.

The FDP is responsible for four categories of FreeBSD documentation.

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 Commit messages for all branches of the doc repository.

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.

Install docproj meta-port as shown in the overview chapter from the Ports Collection. These applications are required to do useful work with the FreeBSD documentation. Some further notes on particular components are given below.

These applications are not required, but can make working on the documentation easier or add capabilities.

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.

FreeBSD documentation is traditionally stored in /usr/doc/, and system source code with manual pages in /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 ~/doc and ~/src, both subdirectories of the user’s home directory.

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:

A checkout of the source code to work on manual pages is very similar:

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:

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.

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 _index.adoc and reset it to unmodified form:

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:

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 "Submit a FreeBSD problem report" interface, add a .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:

These examples show very basic usage of Git. More detail is available in the Git Book and the Git documentation.

There are three sections under doc/, documentation and website share the same structure.

These directories contain the documentation and the website. The documentation is organized into subdirectories below this level, following the Hugo directory structure.

This section contains specific notes about particular documents managed by the FDP.

The books are written in AsciiDoc.

For each FreeBSD book, the AsciiDoc document type (aka doctype) is book. Books have parts, each of which contains several chapters.

When the document is converted to HTML 5 (using the built-in html5 backend):

– and so on. Reference: Section Titles and Levels | Asciidoctor Docs.

The articles are written in AsciiDoc.

The articles are organized as an AsciiDoc article. The articles are divided into sections (=) and subsections (==, ===) and so on.

Different types of output can be produced from a single AsciiDoc source file.

These are the tools used to build and install the FDP documentation.

There are three Makefile files for building some or all of the documentation project.

The 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.

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 /tmp/foo, use rm(1).

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:

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.

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.

Asciidoctor supports a few types of lists, the most common are ordered and unordered. To get more information about lists, see AsciiDoc Syntax Quick Reference.

Images and icons play a crucial role in enhancing the overall user experience. These visual elements are strategically integrated to convey information, clarify concepts, and provide a visually engaging interface.

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).

This rosetta stone tries to show the differences between Docbook and AsciiDoc.

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".

Yes. Different translation groups have their own mailing lists. The list of translation projects has more information about the mailing lists and web sites run by each translation project. In addition there is freebsd-translators@freebsd.org for general translation discussion.

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.

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.

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:

git.FreeBSD.org is a public git server.

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 abff932fe8 and 2191c44469 of documentation/content/en/articles/committers-guide/_index.adoc, run:

Please see the complete explanation of using Git in FreeBSD in the FreeBSD Handbook.

The 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 documentation project mailing list in case someone else is thinking of doing a translation, but has not announced it yet.

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.

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).

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 (/usr/share/misc/iso639 on a version of FreeBSD newer than 20th January 1999).

Currently, the FreeBSD documentation is stored in a top level directory called documentation/. Directories below this are named according to the language code they are written in, as defined in ISO639 (/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:

sv is the name of the translation, in 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 reviews system.

You should use Bugzilla to 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 Documentation Engineering Team <doceng@FreeBSD.org>) will then take your translation and confirm that it builds. In particular, the following things will be looked at:

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.

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.

The 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.

The procedure shown in Quick Start is assumed to have already been performed. The TRANSLATOR option is required and already enabled by default in the textproc/docproj port.

This example shows the creation of a Spanish translation of the short Leap Seconds article.

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 lang. lang is a two-character lowercase code.

The translations are in subdirectories of the main documentation directory, here assumed to be ~/doc/documentation/ as shown in Quick Start. For example, German translations are located in ~/doc/documentation/content/de/, and French translations are in ~/doc/documentation/content/fr/.

Each language directory contains separate subdirectories named for the type of documents, usually articles/ and 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 ~/doc/documentation/content/fr/articles/nanobsd/, and the Mongolian translation of the Handbook is in ~/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 articles/ or books/ directory is needed.

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. 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 devel/gtranslator.

It is important to preserve the PO file. It contains all of the work that translators have done.

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 Build the Translated Document.

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 documentation bug report or code review.

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 documentation portal.

Weblate is web-based open-source software focused on localization; the FreeBSD project runs a local instance.

Following are simple steps to start translating articles and books of the FreeBSD Documentation Project.

Please provide a brief self-introduction on the FreeBSD translators mailing list 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.

Open https://translate-dev.freebsd.org/ and Sign in.

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 freebsd-doc-translate (an intermediate repository on GitHub), not directly to freebsd-doc. Translators must take the PO gettext files (.po), converting them to .adoc and submit it via Bugzilla or 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.

Click Projects, choose Documentation, then click Languages, and see all the available languages.

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 language coordinators before asking to create a new language. If there is no answer, then write to the Documentation Engineering Team <doceng@FreeBSD.org>.

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.

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 Weblate documentation, there is more info about translations, like keyboard shortcuts and other tips about the translation tool.

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.

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:

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.

Links:

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.

In this example, two strings are missing the full stop; following that link will show only those strings to be revised/translated.

Translators and reviewers often value observing translated strings in context.

The project does not use continuous integration and continuous delivery to build translations. There are studies to make it available.

To build the translation locally, follow these steps:

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.

To make any necessary adjustments in the translation, follow the steps below to re-sync all components:

The Documentation Build Process chapter includes information about rendering to HTML and PDF.

Example of submitting an update to the Brazilian Portuguese article Committer’s Guide.

Attach the patch 0001-pt-br-committers-guide-Sync-with-en-XXXXXXX.patch to a problem report in FreeBSD Bugzilla.

Include the following information in the report:

For people familiar with git(1) and GitHub: instead of submitting the patch through Bugzilla, a 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 doc commit bit for translations), a FreeBSD account, and associated perks.

The list of Additional FreeBSD Contributors includes non-committers whose contributions are committed to the doc tree.

If in doubt about any procedure, write to the FreeBSD translators mailing list.

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(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 are grouped into sections. Each section contains manual pages for a specific category of documentation:

Various markup forms and rendering programs have been used for manual pages. FreeBSD has used groff(7) and the newer mandoc(1). Most existing FreeBSD manual pages, and all new ones, use the 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 gzip(1) to save space.

Manual pages can also be rendered to other formats, including PostScript for printing or PDF generation. See man(1).

This section shows minimal desired man page contents for several common categories of manual pages.

Testing a new manual page can be challenging. Fortunately there are some tools that can assist in the task. Some of them, like 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 mandoc(1)'s linter to check for parsing errors:

Use textproc/igor to proofread the manual page:

Another useful tool is textproc/vale. It does not support the mdoc(7) syntax but the rendered manual page can be read from standard input:

textproc/vale is highly configurable. It is advised to read its documentation.

Use man(1) to check the final result of your changes:

You can use col(1) to filter the output of man(1) and get rid of the backspace characters before loading the result in your favorite editor for spell checking:

Spell-checking with fully-featured dictionaries is encouraged, and can be accomplished by using textproc/hunspell or textproc/aspell combined with textproc/en-hunspell or textproc/en-aspell, respectively. For instance:

Some manual pages are suitable as in-depth examples.

Resources for manual page writers:

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.

To promote consistency between the myriad authors of the FreeBSD documentation, some guidelines have been drawn up for authors to follow.

For more information about writing style, see Elements of Style by William Strunk.

To keep the source for the documentation consistent when many different people are editing it, please follow these style conventions.

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 Semantic Line Breaks page.

This is an example which does not use "one sentence per line".

And this is an example which uses the technique.

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.

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 documentation project mailing list.

To maintain clarity and consistency across all documentation and website pages, Vale styles have been introduced in the documentation tree. Vale is a powerful linter for writing customized rules and can be used in multiple scenarios. Currently 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.

Install from editors/vim, or editors/vim-console, then follow the configuration instructions in Configuration. More advanced users can use a proper linter like Ale which can also act as a Vim Language Server Protocol client.

Install from editors/emacs or editors/emacs-devel.

Install from editors/nano or editors/nano-devel.

Append a trademark symbol (™, ®, or other) to the first occurrence of the trademarked name, and always when using logos. Use the 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 United States Patent and Trademark Office trademark search website.

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 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 Contributing to FreeBSD article:

The trademark tags freebsd, ieee, and general will be automatically rendered when building the document like this:

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.