How To: Create a manpage from scratch.
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
/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/
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.
sometimes enclosed with formatting macros from groff_mdoc(7) markup language.
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.
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.
EZJAIL(8) FreeBSD System Manager's Manual EZJAIL(8) FreeBSD 8.0 July 22, 2010 FreeBSD 8.0
.Sh NAME # Section header name in uppercase letters. .Nm ezjail # Name to display. .Nd “description” # short description of command.
NAME ezjail -- description
.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[,..]]
.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.
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.
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 email@example.com # or you could just use Tom Jones firstname.lastname@example.org
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
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/
man 8 ezjail
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
FreeBSD Install Guide www.a1poweruser.com
Last edited by FBSD; 12th April 2010 at 08:09 AM.
|Thread||Thread Starter||Forum||Replies||Last Post|
|OpenBSD: create user sh script||J65nko||Guides||3||31st January 2010 08:29 PM|
|Manpage colorization on the terminal||JMJ_coder||NetBSD General||2||17th February 2009 09:17 PM|
|Trouble reading manpage||IIMarckus||OpenBSD General||3||18th October 2008 05:08 AM|
|Tried to create new partition using sysinstall but change is not permanent||disappearedng||FreeBSD General||7||6th July 2008 10:00 PM|
|Installing 64bit from scratch on a 32bit live system||an0r0c||FreeBSD Installation and Upgrading||1||11th May 2008 04:16 AM|