docs/145644: Add artical about creating manpage from scratch
Joe Barbish
fbsd1 at a1poweruser.com
Mon Apr 12 09:40:08 UTC 2010
>Number: 145644
>Category: docs
>Synopsis: Add artical about creating manpage from scratch
>Confidential: no
>Severity: non-critical
>Priority: low
>Responsible: freebsd-doc
>State: open
>Quarter:
>Keywords:
>Date-Required:
>Class: doc-bug
>Submitter-Id: current-users
>Arrival-Date: Mon Apr 12 09:40:01 UTC 2010
>Closed-Date:
>Last-Modified:
>Originator: Joe Barbish
>Release: 8.0 release
>Organization:
none
>Environment:
>Description:
The FreeBSD documentation environment is lacking instructions on how to
create “man page” manuals. I have written a ‘How To’ document titled;
Creating a manpage from scratch. It’s too big for the FAQ list,
but fits nicely into the article size.
You can read it online at
http://www.daemonforums.org/showthread.php?t=4602
I am donating it to the FreeBSD document team with the hopes you will take
the text file I have attached and convert it to SGML and add it as an article.
>How-To-Repeat:
>Fix:
Patch attached with submission follows:
Creating a manpage from scratch.
What is a manpage?
The FreeBSD documentation manuals system is comprised on many manuals that
are intended to by displayed on-line from the command line using the
“man” command. Every Base RELEASE command has it’s own manual as well as
the commands introduced by the ports system. The layout of the manual is
standardized by the use of groff_mdoc(7) documentation macro markup
language. The files containing the source for each manual are located in
the /usr/share/man/manX/ directory tree, where the X of manX is one of
the following sections.
Under FreeBSD 8.0, the following sections are defined:
1 FreeBSD General Commands Manual
2 FreeBSD System Calls Manual
3 FreeBSD Library Functions Manual
4 FreeBSD Kernel Interfaces Manual
5 FreeBSD File Formats Manual
6 FreeBSD Games Manual
7 FreeBSD Miscellaneous Information Manual
8 FreeBSD System Manager's Manual
9 FreeBSD Kernel Developer's Manual
So you would see this
/usr/share/man/man1/
/usr/share/man/man2/
/usr/share/man/man3/
/usr/share/man/man4/
/usr/share/man/man5/
/usr/share/man/man6/
/usr/share/man/man7/
/usr/share/man/man8/
/usr/share/man/man9/
Manual File Naming Standard.
There is a standardized naming convention in place for manpage files:
name.X.gz
Where name = the name of the command being documented.
X = the manual section its in from the above path list.
gz = means the file has been compress with gzip(1) command.
The file itself is a text file with the documentation being prefixed and
sometimes enclosed with formatting macros from groff_mdoc(7) markup language.
Take note; The macro text file should contain no blank lines in it.
Creating The Manual Source File.
The best way to get started is to just copy a man page from the base system
and edit it to taste. As the system administrator I always login as user
root so the following command examples and manual sample are developed in /root.
The manual for the jail(8) command will be used as the template for my new manual ezjail.
cd /root
cp /usr/share/man/man8/jail.8.gz /root/ # get my own copy of file.
mv jail.8.gz ezjail.8.gz # rename the file.
gunzip ezjail.8.gz # unzip the file.
ee ezjail.8 # edit the text file.
The start of the text file has the standard FreeBSD copyright comments. Delete all
these comments. All groff_mdoc(7) documentation line macros begin with an period “.”
Then an uppercase letter followed by a lowercase letter. The following discussion
has comments to the right and these comments are not part of the macro command syntax,
but put here to explain what’s happening. So starting the new ezjail manpage text file is;
# Setup the manual format section
.Dd July 22, 2010 # Date displayed on center of last line.
.Dt EZJAIL 8 # Name and section of this manpage,
# has to be in uppercase letters,
# displays left & right corners of top line.
.Os # Displays RELEASE version in left & right
# corners of last line.
# This is how the man command displays the first and last lines
EZJAIL(8) FreeBSD System Manager's Manual EZJAIL(8)
FreeBSD 8.0 July 22, 2010 FreeBSD 8.0
# Setup the highlighted first two lines you see.
.Sh NAME # Section header name in uppercase letters.
.Nm ezjail # Name to display.
.Nd “description” # short description of command.
# This is what is displayed by the man command
NAME
ezjail -- description
# Setup the command syntax section
.Sh SYNOPSIS # Section header name in uppercase letters.
.Nm # Display saved name.
# The following macros format the flags in bold and/or with brackets
# and with white background / black letters.
.Op Fl dhi
.Op Fl J Ar jid_file
.Op Fl l u Ar username | Fl U Ar username
.Op Fl c | m
.Br
.Nm
.Op Fl hi
.Op Fl n Ar jailname
.Op Fl J Ar jid_file
.Op Fl s Ar securelevel
.Op Fl l u Ar username | Fl U Ar username
.Op Ar path hostname [ip[,..]] command ...
# This is what is displayed by the man command
SYNOPSIS
jail [-dhi] [-J jid_file] [-l -u username | -U username] [-c | -m]
jail [-hi] [-n jailname] [-J jid_file] [-s securelevel]
[-l -u username | -U username] [path hostname [ip[,..]]
# This is a real pain to play with. So I used the short method like this.
It displays the text just as written with no bold and no white boxes.
This method is simpler and makes the manpage easier to read without all
those white-boxed words. The layout will be the same as what is shown above.
.Sh SYNOPSIS
.Nm
[-dhi] [-J jid_file] [-l -u username | -U username] [-c | -m]
.Nm
[-hi] [-n jailname] [-J jid_file] [-s securelevel]
.Br # this means next line
[-l -u username | -U username] [path hostname [ip[,..]]
# The description section with the meaning of the flags comes next.
.Sh DESCRIPTION
The jail utility creates a new jail or modifies an existing jail,
imprisoning the current process (and future descendants) inside it.
.Pp # blank line position holder.
The options are as follows:
.Bl -tag -width indent # indent everything that follows.
.It Fl d # adds the dash and bolds them both.
Allow making changes to a dying jail.
.It Fl h # adds the dash and bolds them both.
Resolve the host.hostname parameter (or hostname) and add
all IP addresses returned by the resolver to the list of
ip addresses for this jail.
.El # end the indented section.
# This is what is displayed by the man command
DESCRIPTION
The jail utility creates a new jail or modifies an existing jail,
optionally imprisoning the current process (and future
descendants) inside it.
The options are as follows:
-d Allow making changes to a dying jail.
-h Resolve the host.hostname parameter (or hostname) and add
all IP addresses returned by the resolver to the list of
ip addresses for this jail.
# The short method I used like this.
.Sh DESCRIPTION
The jail utility creates a new jail or modifies an existing jail,
imprisoning the current process (and future descendants) inside it.
.Pp # blank line position holder
The options are as follows:
.Bl -tag -width indent # indent everything that follows
.It \fB-d\fR # adds the bold
Allow making changes to a dying jail.
.It \fB-h\fR # adds the bold
Resolve the host.hostname parameter (or hostname) and add
all IP addresses returned by the resolver to the list of
ip addresses for this jail
.El # End the indented section.
# This is an example of the special enclosure macro that bolds any word
or words its wrapped around. \fB 10.0.10.2 \fR will display as 10.0.10.2
General format notes.
The manual standards specify the following sections as mandatory.
.Sh NAME
.Sh SYNOPSIS
.Sh DESCRIPTION
Which have been covered all ready. At the end of the manpage there are a
few more mandatory sections required in all manpages.
.Sh FILES # Section header name in uppercase letters.
/usr/local/etc/ezjail.conf
.br
/usr/local/bin/ezjail
.Sh SEE ALSO # Section header name in uppercase letters.
.Xr killall 1 ,
.Xr lsvfs 1 ,
.Xr newaliases 1 ,
# or you could just say
killall(1), lsvfs(1), newaliases(1)
.Sh AUTHORS # Section header name in uppercase letters.
.An Tom Jones
.Aq tjones at home.com
# or you could just use
Tom Jones tjones at home.com
Now in between the Description section and the FILES section you can make
as many sections as you want by using the .Sh macro. Example
.Sh USAGE EXAMPLES
.Sh HISTORY
.Sh BACKGROUND
Testing method.
I have found it convenient to use 2 sessions for testing.
In the F1 session I cycle through these commands
gunzip ezjail.8.gz
ee ezjail.8
gzip ezjail.8
cp ezjail.8.gz /usr/local/man/man8/
And then from the F2 session I issue
man 8 ezjail
I can then read my new manpage looking for format, word spacing, sentence
wrapping, and verifying that all special bolding is working.
Swapping between the edit of the manpage text source on the F1 session
and the view of the displayed manpage on the F2 session making any changes
to the source as necessary. Then ending the edit, gziping the file and
coping it to it’s running location. Where in the F2 session I enter ctlr-c
to close the old manpage view and then man 8 ezjail again to view the
just update version.
I have found that sometimes it’s convenient to render the groff source as
pure ascii text. Groff will complain if the raw macro source has blank
lines in it and gives you the line number of macros with syntax errors.
groff -mdoc -Tascii ezjail.8 | more
groff -mdoc -Tascii ezjail.8 > ezjail.raw.text
gzcat ezjail.8.gz | groff -mdoc -Tascii | less
>Release-Note:
>Audit-Trail:
>Unformatted:
More information about the freebsd-doc
mailing list