It is easy 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. For this we need markup.

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.

AsciiDoctor support six headings levels. If the document type is `article` only one level 0 (`=`) can be used. If the document type is `book` can be multiple level 0 (`=`).

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.

For example, this is a heading with two paragraphs

For example, this is a heading with two paragraphs.

This is the firts paragraph.

This is the first paragraph.

AsciiDoctor support two type of lists ordered and unordered. To get more information about lists check link:https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/#lists[AsciiDoc Syntax Quick Reference]

AsciiDoctor supports two type of lists: ordered and unordered. To get more information about lists check link:https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/#lists[AsciiDoc Syntax Quick Reference]

For example this is an unordered lists.

For example this is an unordered list.

As the AsciiDoctor documentation points the `link` macro is not required when the target starts with a URL scheme like `https`. But is a good practice to ensure that AsciiDoctor renders correctly the link. Specially in non-latin languages like Japanese.

As the AsciiDoctor documentation describes, the `link` macro is not required when the target starts with a URL scheme like `https`. However, it is a good practice to do this anyway to ensure that AsciiDoctor renders the link correctly, especially in non-latin languages like Japanese.

That 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 is the conclusion of this AsciiDoctor primer. For reasons of space and complexity, several things have not been covered in depth (or at all).

<.> `all` target generate the books TOCs, builds the documentation and puts the result in [.filename]#~/doc/documentation/public#.

<.> `all` target generates the books' tables of contents ("TOCs"), builds the documentation and puts the result in [.filename]#~/doc/documentation/public#.

<.> `run` runs hugo webserver in a random free port.

<.> `run` runs hugo webserver on port 1313, or a random free port if that is already in use.

This [.filename]#Makefile# take the form of:

This [.filename]#Makefile# takes the form of:

<.> `all` target generate the books TOCs, builds the documentation and puts the result in [.filename]#~/doc/website/public#.

<.> `all` target builds the website and puts the result in [.filename]#~/doc/website/public#.

<.> `run` runs hugo webserver on a random free port.

<.> `run` runs hugo webserver on port 1313, or a random free port if that is already in use.

Adjusting text editor configuration can make working on document files quicker and easier, and help documents conform to FDP guidelines.

Adjusting your text editor configuration can make working on document files quicker and easier, and help documents conform to FDP guidelines.

These examples are not exhaustive-they do not contain all the elements that might be desirable to use, particularly in a document's front matter. For more examples of AsciiDoctor, examine the AsciiDoc source for this and other documents available in the Git `doc` repository, or available online starting at link:https://cgit.freebsd.org/doc/[https://cgit.freebsd.org/doc/].

These examples are not exhaustive - they do not contain all the elements that might be desirable to use, particularly in a document's front matter. For more examples of AsciiDoctor, examine the AsciiDoc source for this and other documents available in the Git `doc` repository, or available online starting at link:https://cgit.freebsd.org/doc/[https://cgit.freebsd.org/doc/].

% find /usr/shared/man/man* | xargs zgrep '.Bd'

% find /usr/share/man/man* | xargs zgrep '.Bd'

|[.filename]#/usr/src/shared/man/man4/vt.4#

|[.filename]#/usr/src/share/man/man4/vt.4#

make generate

make

Tips are represented like this, and contain information helpful to the user, like showing an easier way to do something.

Tips are represented like this, and contain information helpful to the user, such as showing an easier way to do something.

|Contains all the articles and books in AsciiDoc format. Contains subdirectories to further categorize the information by languages

|Contains all the articles and books in AsciiDoc format. Contains subdirectories to further categorize the information by languages.

These directories contain the documentation and the website. The documentation is split into up to some directories this level. Following the link:https://gohugo.io/getting-started/directory-structure/[Hugo directory structure].

These directories contain the documentation and the website. The documentation is organized into subdirectories below this level, following the link:https://gohugo.io/getting-started/directory-structure/[Hugo directory structure].

Please be careful with this file. Is used by the Python `tools` to generate the Table of Contents of the books. In case of editing this file, first contact the mailto:doceng@freebsd.org[Documentation Engineering] team.

Please be careful with this file. It is used by the Python `tools` to generate the Table of Contents of the books. In case of editing this file, first contact the mailto:doceng@freebsd.org[Documentation Engineering] team.

There are a one [.filename]#_index.adoc# file per article.

There is one [.filename]#_index.adoc# file per article.

Yes. The more people work on translation the faster it gets done, and the faster changes to the English documentation are mirrored in the translated documents.

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.

% git clone https://git.FreeBSD.org/doc.git doc

% git clone https://cgit.FreeBSD.org/doc.git doc

Then pick a document and start translating. It is best to start with something fairly small-either the FAQ, or one of the tutorials.

Then pick a document and start translating. It is best to start with something fairly small - either the FAQ, or one of the tutorials.

[[writing-style-word-list]]

[[writing-style-special-characters]]

== Word List

== Special Character List

This list of words shows the correct spelling and capitalization when used in FreeBSD documentation. If a word is not on this list, ask about it on the {freebsd-doc}.

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