Attachment 105233 Details for Bug 145644 – file.txt

file.txt

file.txt (text/plain), 9.14 KB, created by Joe on 2010-04-12 10:40:01 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Joe

Created: 2010-04-12 10:40:01 UTC

Size: 9.14 KB

patch

obsolete

>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 its 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 whats 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@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
>
>.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 its 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 its 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

Actions: View

Attachments on bug 145644: 105233