Date: Mon, 12 Apr 2010 09:30:18 GMT From: Joe Barbish <fbsd1@a1poweruser.com> To: freebsd-gnats-submit@FreeBSD.org Subject: docs/145644: Add artical about creating manpage from scratch Message-ID: <201004120930.o3C9UIPC009467@www.freebsd.org> Resent-Message-ID: <201004120940.o3C9e1tK064599@freefall.freebsd.org>
next in thread | raw e-mail | index | archive | help
>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@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 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:
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201004120930.o3C9UIPC009467>