DaemonForums  

Go Back   DaemonForums > Miscellaneous > Guides

Guides All Guides and HOWTO's.

Reply
 
Thread Tools Display Modes
  #1   (View Single Post)  
Old 12th April 2010
FBSD FBSD is offline
Real Name: Joe Barbish
KING
 
Join Date: Feb 2010
Location: Angeles City, Philippines
Posts: 19
Default 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.

Code:
 
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
Code:
 
               /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.
Code:
 
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.

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.
Code:
 
 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
Code:
.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

Code:
 
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.
Code:
.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
Code:
NAME
     ezjail -- description
#Set up the command syntax section
Code:
.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
Code:
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.

Code:
 
.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.
Code:
.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
Code:
 
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.
Code:
.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.
Code:
 
.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@home.com
# or you could just use
Tom Jones  tjones@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
Code:
 
.Sh USAGE EXAMPLES
.Sh HISTORY
.Sh BACKGROUND
Take note; The macro text file should contain no blank lines in it.


Testing method.
I have found it convenient to use 2 sessions for testing.
In the F1 session I cycle through these commands
Code:
 
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
Code:
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.
Code:
 
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.
Reply With Quote
Reply

Thread Tools
Display Modes

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is On
HTML code is Off

Forum Jump

Similar Threads
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


All times are GMT. The time now is 11:44 AM.


Powered by vBulletin® Version 3.8.4
Copyright ©2000 - 2024, Jelsoft Enterprises Ltd.
Content copyright © 2007-2010, the authors
Daemon image copyright ©1988, Marshall Kirk McKusick