diff --git a/documentation/content/en/books/fdp-primer/manual-pages/chapter.adoc b/documentation/content/en/books/fdp-primer/manual-pages/chapter.adoc index 024e3891da..9d5a142a64 100644 --- a/documentation/content/en/books/fdp-primer/manual-pages/chapter.adoc +++ b/documentation/content/en/books/fdp-primer/manual-pages/chapter.adoc @@ -1,488 +1,488 @@ --- title: Chapter 10. Manual Pages prev: books/fdp-primer/po-translations next: books/fdp-primer/writing-style --- [[manual-pages]] = Manual Pages :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :skip-front-matter: :xrefstyle: basic :relfileprefix: ../ :outfilesuffix: :sectnumoffset: 10 toc::[] [[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,1", options="header"] +[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="1,1", options="header"] +[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 link:{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/shared/man/man*# directories. For example, to search for examples of the `.Bd`_Begin display_ macro: [source,bash] .... % find /usr/shared/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,1", options="header"] +[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,1", options="header"] +[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,bash] .... % mandoc -T lint ./mynewmanpage.8 .... Use package:textproc/igor[] to proofread the manual page: [source,bash] .... % igor ./mynewmanpage.8 .... Use man:man[1] to check the final result of your changes: [source,bash] .... % 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,bash] .... % 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,bash] .... % 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,1", options="header"] +[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/shared/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/preface/chapter.adoc b/documentation/content/en/books/fdp-primer/preface/chapter.adoc index 3f37526090..a12b9582df 100644 --- a/documentation/content/en/books/fdp-primer/preface/chapter.adoc +++ b/documentation/content/en/books/fdp-primer/preface/chapter.adoc @@ -1,128 +1,128 @@ --- title: Preface prev: books/fdp-primer/ next: books/fdp-primer/overview --- [preface] [[preface]] = Preface :doctype: book :toc: macro :toclevels: 1 :icons: font :source-highlighter: rouge :experimental: :skip-front-matter: :xrefstyle: basic :relfileprefix: ../ :outfilesuffix: [[preface-prompts]] == Shell Prompts 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. [.informaltable] -[cols="50%,50%", frame="none", options="header"] +[cols="1,2", frame="none", options="header"] |=== | User | Prompt |Normal user |% |`root` |# |=== [[preface-conventions]] == Typographic Conventions This table describes the typographic conventions used in this book. [.informaltable] -[cols="1,1", frame="none", options="header"] +[cols="1,2", frame="none", options="header"] |=== | Meaning | Examples |The names of commands. |Use `ls -l` to list all files. |The names of files. |Edit [.filename]#.login#. |On-screen computer output. a| [source,bash] .... You have mail. .... |What the user types, contrasted with on-screen computer output. a| [source,bash] .... % date +"The time is %H:%M" The time is 09:18 .... |Manual page references. |Use man:su[1] to change user identity. |User and group names. |Only `root` can do this. |Emphasis. |The user _must_ do this. |Text that the user is expected to replace with the actual text. |To search for a keyword in the manual pages, type `man -k _keyword_` |Environment variables. |`$HOME` is set to the user's home directory. |=== [[preface-notes]] == Notes, Tips, Important Information, Warnings, and Examples Notes, warnings, and examples appear within the text. [NOTE] ==== Notes are represented like this, and contain information to take note of, as it may affect what the user does. ==== [TIP] ==== Tips are represented like this, and contain information helpful to the user, like showing an easier way to do something. ==== [IMPORTANT] ==== Important information is represented like this. Typically, these show extra steps the user may need to take. ==== [WARNING] ==== Warnings are represented like this, and contain information warning about possible damage if the instructions are not followed. This damage may be physical, to the hardware or the user, or it may be non-physical, such as the inadvertent deletion of important files. ==== .A Sample Example [example] ==== Examples are represented like this, and typically contain examples showing a walkthrough, or the results of a particular action. ==== [[preface-acknowledgements]] == Acknowledgments 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. diff --git a/documentation/content/en/books/fdp-primer/rosetta/chapter.adoc b/documentation/content/en/books/fdp-primer/rosetta/chapter.adoc index 2fa69ca71f..6226cfe221 100644 --- a/documentation/content/en/books/fdp-primer/rosetta/chapter.adoc +++ b/documentation/content/en/books/fdp-primer/rosetta/chapter.adoc @@ -1,283 +1,283 @@ --- title: Chapter 7. Rosetta Stone prev: books/fdp-primer/asciidoctor-primer next: books/fdp-primer/translations --- [[rosetta]] = Rosetta Stone :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :skip-front-matter: :xrefstyle: basic :relfileprefix: ../ :outfilesuffix: :sectnumoffset: 7 toc::[] [[docbook-vs-asciidoc]] == Comparision between Docbook and AsciiDoc This rosetta stone tries to show the differences between Docbook and AsciiDoc. .Comparision between Docbook and AsciiDoc -[cols="1,1,1"] +[cols="1,4,4"] |=== |Language Feature |Docbook | AsciiDoc |*Bold* |bold |\*bold* |*Italic* |Italic |\_Italic_ |*Monospace* |Monospace |\`Monospace` |*Paragraph* |This is a paragraph |This is a paragraph |*Keycap* |F11 |\kbd:[F11] |*Links* a| [source,xml] ---- Download FreeBSD ---- a| [source] ---- link:https://www.freebsd.org/where/[Download FreeBSD] ---- |*Sections* a| [source,xml] ---- Section 1 ---- a| [source] ---- [[id]] = Section 1 ---- |*Unordered list* a| [source,xml] ---- When to build a custom kernel. How to take a hardware inventory. ---- a| [source] ---- * When to build a custom kernel. * How to take a hardware inventory. ---- |*Ordered list* a| [source,xml] ---- One Two Three Four ---- a| [source] ---- . One . Two . Three . Four ---- |*Variable list* a| [source,xml] ---- amd64 This is the most common desktop... ---- a| [source] ---- amd64:: This is the most common desktop... ---- |*Source code* a| [source,xml] ---- &prompt.root; mkdir -p /var/ ---- a| [source] .... [source,bash] ---- # mkdir -p /var/spool/lpd/lp ---- .... |*Literal block* a| [source,xml] ---- include GENERIC ident MYKERNEL options IPFIREWALL options DUMMYNET options IPFIREWALL_DEFAULT_TO_ACCEPT options IPDIVERT ---- a| [source] ---- .... include GENERIC ident MYKERNEL options IPFIREWALL options DUMMYNET options IPFIREWALL_DEFAULT_TO_ACCEPT options IPDIVERT .... ---- |*Images* a| [source,xml] ----
FreeBSD Boot Loader Menu
---- a| [source] ---- [[bsdinstall-newboot-loader-menu]] .FreeBSD Boot Loader Menu image::bsdinstall/bsdinstall-newboot-loader-menu ---- |*Includes* |n/a a| [source] ---- \include::chapter.adoc[] ---- |*Tables* a| [source,xml] ---- Partitioning Schemes Abbreviation Description APM Apple Partition Map, used by PowerPC(R).
---- a| [source] ---- [[partition-schemes]] .Partitioning Schemes [cols="1,1", frame="none", options="header"] \|=== \| Abbreviation \| Description \|APM \|Apple Partition Map, used by PowerPC(R). \|=== ---- |*Admonitions* a| [source,xml] ---- This is a tip ---- a| [source] ---- [TIP] ==== This is a tip ==== ---- |===