Index: head/en_US.ISO8859-1/books/fdp-primer/Makefile
===================================================================
--- head/en_US.ISO8859-1/books/fdp-primer/Makefile (revision 50997)
+++ head/en_US.ISO8859-1/books/fdp-primer/Makefile (revision 50998)
@@ -1,54 +1,59 @@
#
# $FreeBSD$
#
# Build the FreeBSD Documentation Project Primer.
#
MAINTAINER=doc@FreeBSD.org
DOC?= book
FORMATS?= html-split html
INSTALL_COMPRESSED?= gz
INSTALL_ONLY_COMPRESSED?=
#
# SRCS lists the individual XML files that make up the document. Changes
# to any of these files will force a rebuild
#
# XML content
SRCS= book.xml
SRCS+= overview/chapter.xml
SRCS+= tools/chapter.xml
SRCS+= working-copy/chapter.xml
SRCS+= structure/chapter.xml
SRCS+= doc-build/chapter.xml
SRCS+= the-website/chapter.xml
SRCS+= xml-primer/chapter.xml
SRCS+= xhtml-markup/chapter.xml
SRCS+= docbook-markup/chapter.xml
SRCS+= stylesheets/chapter.xml
SRCS+= translations/chapter.xml
SRCS+= po-translations/chapter.xml
+SRCS+= manpages/chapter.xml
SRCS+= writing-style/chapter.xml
SRCS+= editor-config/chapter.xml
SRCS+= see-also/chapter.xml
SRCS+= examples/appendix.xml
# Images from the cross-document image library
IMAGES_LIB= callouts/1.png
IMAGES_LIB+= callouts/2.png
IMAGES_LIB+= callouts/3.png
IMAGES_LIB+= callouts/4.png
IMAGES_LIB+= callouts/5.png
+IMAGES_LIB+= callouts/6.png
+IMAGES_LIB+= callouts/7.png
+IMAGES_LIB+= callouts/8.png
+IMAGES_LIB+= callouts/9.png
# Entities
SRCS+= chapters.ent
URL_RELPREFIX?= ../../../..
DOC_PREFIX?= ${.CURDIR}/../../..
.include "${DOC_PREFIX}/share/mk/doc.project.mk"
Index: head/en_US.ISO8859-1/books/fdp-primer/book.xml
===================================================================
--- head/en_US.ISO8859-1/books/fdp-primer/book.xml (revision 50997)
+++ head/en_US.ISO8859-1/books/fdp-primer/book.xml (revision 50998)
@@ -1,271 +1,272 @@
%chapters;
]>
FreeBSD Documentation Project Primer for New
ContributorsThe FreeBSD Documentation Project19981999200020012002200320042005200620072008200920102011201220132014201520162017DocEng
&legalnotice;
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.PrefaceShell PromptsThis table shows the default system prompt and
superuser prompt. The examples use these prompts to
indicate which type of user is running the example.UserPromptNormal user&prompt.user;root&prompt.root;Typographic ConventionsThis table describes the typographic conventions
used in this book.MeaningExamplesThe names of commands.Use ls -l to list all
files.The names of files.Edit .login.On-screen computer output.You have mail.What the user types, contrasted with on-screen
computer output.&prompt.user; date +"The time is %H:%M"
The time is 09:18Manual 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
keywordEnvironment variables.$HOME is set to the user's home
directory.Notes, Tips, Important Information, Warnings, and
ExamplesNotes, warnings, and examples appear within the
text.Notes are represented like this, and contain information
to take note of, as it may affect what the user
does.Tips are represented like this, and contain information
helpful to the user, like showing an easier way to do
something.Important information is represented like this.
Typically, these show extra steps the user may need to
take.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 ExampleExamples are represented like this, and typically
contain examples showing a walkthrough, or
the results of a particular action.AcknowledgmentsMy 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.
&chap.overview;
&chap.tools;
&chap.working-copy;
&chap.structure;
&chap.doc-build;
&chap.the-website;
&chap.xml-primer;
&chap.xhtml-markup;
&chap.docbook-markup;
&chap.stylesheets;
&chap.translations;
&chap.po-translations;
+ &chap.manpages;
&chap.writing-style;
&chap.editor-config;
&chap.see-also;
&app.examples;
Index: head/en_US.ISO8859-1/books/fdp-primer/chapters.ent
===================================================================
--- head/en_US.ISO8859-1/books/fdp-primer/chapters.ent (revision 50997)
+++ head/en_US.ISO8859-1/books/fdp-primer/chapters.ent (revision 50998)
@@ -1,29 +1,30 @@
+
Index: head/en_US.ISO8859-1/books/fdp-primer/manpages/chapter.xml
===================================================================
--- head/en_US.ISO8859-1/books/fdp-primer/manpages/chapter.xml (nonexistent)
+++ head/en_US.ISO8859-1/books/fdp-primer/manpages/chapter.xml (revision 50998)
@@ -0,0 +1,718 @@
+
+
+
+
+ Manual Pages
+
+
+ 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.
+
+
+
+ Sections
+
+ Manual pages are grouped into sections.
+ Each section contains manual pages for a specific category of
+ documentation:
+
+
+
+
+
+ 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
+
+
+
+
+
+
+
+ Markup
+
+ Various markup forms and rendering programs have been used
+ for manual pages. &os; has used &man.groff.7; and the newer
+ &man.mandoc.1;. Most existing &os; 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 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;.
+
+
+ Testing a new manual page can be challenging when it is
+ not located in the normal manual page search path.
+ &man.man.1; also does not look in the current directory. If
+ the new manual page is in the current directory, prefix
+ the filename with a ./:
+
+ &prompt.user; man ./mynewmanpage.8
+
+ An absolute path can also be used:
+
+ &prompt.user; man /home/xsmith/mynewmanpage.8
+
+
+
+
+ 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:
+
+
+
+
+
+ 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.
+
+
+
+ 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:
+
+
+.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. Because 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:
+
+ 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.
+
+
+
+ Markup Guidelines
+
+ The &man.mdoc.7; markup language is not very strict. For
+ clarity and consistency, the &os; 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 Committer's
+ Guide.
+
+
+
+
+
+
+ Markup Tricks
+
+ Add a space before punctuation on a line with
+ macros. Example:
+
+ .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 spacee, the external links would
+ incorrectly point to section 4, or
+ 8,.
+
+
+
+ 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
+ /usr/share/man/man* directories. For
+ example, to search for examples of the .Bd
+ Begin display macro:
+
+ &prompt.user; find /usr/share/man/man* | xargs zgrep '.Bd'
+
+
+ Organizational Macros
+
+ Some macros are used to define logical blocks of a
+ manual page.
+
+
+
+
+
+ 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.
+
+
+
+
+
+
+
+ Inline Macros
+
+ Many macros are used to mark up inline text.
+
+
+
+
+
+ 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.
+
+
+
+
+
+
+
+
+
+ Sample Manual Page Structures
+
+ This section shows minimal desired man page contents for
+ several common categories of manual pages.
+
+
+ Section 1 or 8 Command
+
+ The preferred basic structure for a section 1 or 8
+ command:
+
+ .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
+
+
+
+ Section 4 Device Driver
+
+ The preferred basic structure for a section 4 device
+ driver:
+
+ .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
+
+
+
+ Section 5 Configuration File
+
+ The preferred basic structure for a section 5
+ configuration file:
+
+ .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
+
+
+
+
+ Example Manual Pages to use as Templates
+
+ Some manual pages are suitable as in-depth examples.
+
+
+
+
+
+ Manual Page
+ Path to Source Location
+
+
+
+
+
+ &man.cp.1;
+ /usr/src/bin/cp/cp.1
+
+
+
+ &man.vt.4;
+ /usr/src/share/man/man4/vt.4
+
+
+
+ &man.crontab.5;
+ /usr/src/usr.sbin/cron/crontab/crontab.5
+
+
+
+ &man.gpart.8;
+ /usr/src/sbin/geom/class/part/gpart.8
+
+
+
+
+
+
+
+ Resources
+
+ Resources for manual page writers:
+
+
+
+ &man.man.1;
+
+
+
+ &man.mandoc.1;
+
+
+
+ &man.groff.mdoc.7;
+
+
+
+ Practical
+ UNIX Manuals: mdoc
+
+
+
+ History
+ of UNIX Manpages
+
+
+
+
Property changes on: head/en_US.ISO8859-1/books/fdp-primer/manpages/chapter.xml
___________________________________________________________________
Added: fbsd:nokeywords
## -0,0 +1 ##
+nokeywords
\ No newline at end of property
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Added: svn:mime-type
## -0,0 +1 ##
+text/xml
\ No newline at end of property