Here - The Linux Documentation Project
Contents
1. AUTHOR Jens Schweikhardt lt howto at schweikhardt dot net gt SEE ALSO par 1L 5 deexe 99 p sewer 1 Linux Last change MARCH 1995 2 Here s the explanation as I promised The NAME section is the only required section Man pages without a name section are as useful as refrigerators at the north pole This section also has a standardized format consisting of a comma separated list of program or function names followed by a dash followed by a short usually one line description of the functionality the program or function or file is supposed to provide By means of makewhatis 8 the name sections make it into the whatis database files Makewhat is is the reason the name section must exist and why it must adhere to the format I described In the groff source it must look like SH NAME foo frobnicate the bar library The V is of importance here The backslash is needed to make the dash distinct from a hyphenation dash that may appear in either the command name or the one line description The SYNOPSIS section is intended to give a short overview on available program options For functions this sections lists corresponding include files and the prototype so the programmer knows the type and number of arguments as well as the return type The DESCRIPTION section eloquently explains why your sequence of Os and 1s is worth anything at all Here s where you write down all your knowledge This is the Hall2. certainly a bad idea to write yet another editor and call it ed sed for smart ed or red for Rocky s ed By making sure your program s name is unique you avoid having someone execute your program but read someone else s man page or vice versa Now we know the name to give our file The next decision is the directory in which it will finally be installed say when the user runs make install for your package On Linux all man pages are below directories listed in the environment variable MANPATH The doc related tools use MANPATH in the same way the shell uses PATH to locate executables In fact MANPATH has the same format as PATH Each contains a colon separated list of directories with the exception that MANPATH does not allow empty fields and relative pathnames it uses absolute names only If MANPATH is not set or not exported a default will be used that contains at least the usr man directory To speed up the search and to keep directories small the directories specified by MANPATH the so called base directories contain a bunch of subdirectories named man s where s stands for the one character section designator introduced in the table above Not all of the sections may be represented by a subdirectory because there simply is no reason to keep an empty mano subdirectory However there may be directories named cat lt s gt dvi lt s gt and ps lt s gt which hold documentation that is ready to display or prin
3. For example XAllocColor 3x uses a few formulas with exponentiation Due to the nature of typewriter like devices the exponent will be on the same line as the base N to the power of two appears as N2 Tb1 should be avoided because all xman programs I have seen fail on them Xman 3 1 6 uses the following command to format man pages e g signal 7 gtbl usr man man7 signal 7 geqn gtbl groff Tascii man tmp xmana01760 2 dev null which screws up for sources using gtb1 because gtb1 output is fed again into gtb1 The effect is a man page without your table I don t know if it s a bug or a feature that gtb1 chokes on its own output or if xman could be a little smarter and not use gt b1 twice Furthermore some systems use grog to determine what options to pass to groff Unfortunately grog sometimes guesses wrong and recommends groff t whenin fact tb1 must not be used We are basically left with two workarounds for tables 1 Format the table yourself manually and put it between nf and fi lines so that it will be left unformatted You won t have bold and italics this way but this beats having your table swallowed any day 2 Use any tb1 macros you like but distribute the t 51 output instead of the input There is however this quirk with grog who thinks that any file containing a line starting with TS requires tbl Tb1 output for some reason unbeknownst to me still contains TS and TE It seems you can simply remove them and have
4. Of Fame Win other programmers and users admiration by making this section the source of reliable and detailed information Explain what the arguments are for the file format what algorithms do the dirty jobs The OPTIONS section gives a description of how each option affects program behaviour You knew that didn t you The FILES section lists files the program or function uses For example it lists configuration files startup files and files the program directly operates on It is a good idea to give the full pathname of these files and to make the install process modify the directory part to match user preferences the grof f manuals have a default prefix of usr local so they reference usr local lib groff by default However if you install using make prefix opt gnu the references in the man page change to opt gnu lib groff 3 How should a formatted man page look 5 Linux Man Page Howto The ENVIRONMENT section lists all environment variables that affect your program or function and tells how of course Most commonly the variables will hold pathnames filenames or default options The DIAGNOSTICS section should give an overview of the most common error messages from your program and how to cope with them There s no need to explain system error error messages from perror 3 or fatal signals from psignal 3 as they can appear during execution of any program The BUGS section should ideally be no
5. of your documentation e Test examples to make sure they work use cut and paste to give your shell the exact wording from the man page Copy the output of your command into your man page don t just type what you think your program will print Proof read ispell and have someone else read it especially if you are not a native English speaker The HOWTO you are reading has passed the latter test special thanks to Michael Miller for a particular heroic contribution All the remaining rough edges are entirely my fault Additional volunteers are always welcome Test your man page Does groff complain when you format your man page It s nice to have the groff command line in a comment Does the man 1 command complain when you call man yourprog Does it produce the expected result Will xman 1x and t kman 1tk cope with your manual XFree86 3 1 has xman 3 1 6 X11R6 it will try to uncompress usinggzip c d s gt 6S zcat lt s gt S e Will makewhatis 8 be able to extract the one line description from the NAME section e Translate your man page to HTML format using rman from http polyglotman sourceforge net and view the result with a a set of web browsers netscape mozilla opera lynx Check that the cross references among your man pages work as hyperlinks in the generated HTML If your software package has a web site post its man pages there and keep them up to date The rman utility can also translate man pages i
6. rarely seen software distributed with formatted man pages If any sysadmin is really concerned about having man pages accessible then he also has groff installed 7 Should distribute source and or already formatted documentation 11 8 What are the font conventions First of all don t use direct font operators like fB V P etc Use macros which take arguments This way you avoid a common glitch forgetting the font change at the end of the word and having the bold or italic extend up to the next font change Believe me it happens more often than you think The tmac an macros provide the following type faces B Bold BI Bold alternating with italics BR Bold alternating with Roman I Italics IB Italics alternating with bold IR Italics alternating with Roman RB Roman alternating with bold RI Roman alternating with italics SM Small scaled 9 10 of the regular size SB Small bold not small alternating with bold X alternating with Y means that the odd arguments are typeset in X while the even arguments are typeset in Y For example BI Arg 1 is Bold Arg 2 is Italics and Bold and Italics The double quotes are needed to include white space into an argument without them no white space appears between the alternating typefaces In fact you ll only need the macros for alternating typefaces in cases where you want to avoid white space between typeface changes So much for what s available Here s how yo
7. the cwd 4 How do document several programs functions in a single man page 8 5 Which macro package should I use There are a number of macro packages especially designed for use in writing man pages Usually they are in the groff macro directory usr lib groff tmac The file names are tmac something where something is the argument to groff s m option Groff will use tmac something when it is given the m something option Often the blank between m and something is omitted so we may say gro f man when we are formatting man pages using the tmac an macro package That s the reason for the strange name tmac an Besides tmac an there is another popular macro package tmac doc which originated at the University of California at Berkeley Many BSD man pages use it and it seems that UCB has made it its standard for documentation The tmac doc macros are much more flexible but alas there are manual browsers that will not use them but always call gro f man For example all xman programs I have seen will screw up on man pages requiring tmac doc So do yourself a favor use tmac an use of any other macro package is considered harmful tmac andoc is a pseudo macro package that takes a look at the source and then loads either tmac an or tmac doc Actually any man page browser should use it but to this point not all of them do so it is best we cling to ye olde tmac an Anything I tell you from no
8. Linux Man Page Howto Jens Schweikhardt lt howto schweikhardt net gt Pradeep Padala Conversion from HTML to DocBook v4 1 v0 1 2002 09 07 Revision History Revision 0 1 2002 09 07 Revised by ppadala Conversion from HTML to Docbook v4 1 Id Man Page sgml v 1 2 2002 12 15 17 51 43 schweikh Exp schweikh This HOWTO explains what you should bear in mind when you are going to write on line documentation a so called man page that you want to make accessible via the man 1 command Throughout this HOWTO a manual entry is simply referred to as a man page regardless of actual length and without sexist intention Linux Man Page Howto Table of Contents 1 A few thoughts on GOCumMen ALON scssisssscsssscssccsessssesrseecssssessacstsessasssaacaeasionssovsadsacvssacsvossaeaestseedspsiactaeiveciaeens 1 2 HOW are man pages accessed uenis RE ESEER HERRERA PIA FRE MISERE INNER MF UYRE E Pr AER ET NNUS ERA NER eee 2 3 How should a formatted man page look sesoosooeoosoosessoesosssssossossossosseseossossossossossossoesessossosssesossesssssosseses 4 4 How do I document several programs functions in a single man page eere scene eee etnne 8 5 Which macro package should IL use iiuerseeceeis ree pheo ta tp etra n erba kae br PE ka o P1RE ER EF PEE e EYE E REPE E FENEM MEER A ePi V EA ap EEE 9 6 What preprocessors may DLUse7 uso neas ee REESE kiso NAR EPOR KENN EAS RSEN ESAE RU Hee 10 7
9. PSIS e00 ese l e eemig i ie tule DESCRIPTION foo frobnicates the bar library by tweaking internal symbol tables By default it parses all baz segments and rearranges them in reverse order by time for the xyzzy 1 linker to find them The symdef entry is then compressed using the WBG Whiz Bang Gizmo algorithm All files are processed in the order specified OPTIONS T6 Do not write busy to stdout while processing c config file Use the alternate system wid config file instead of etc foo conf This overrides any FOOCONF environment variable a In addition to the baz segments also parse the blurfl headers Ha Recursiv mode Operates as fast as lightning at the expense of a megabyte of virtual memory FILES etc foo conf The system wide configuration file See foo 5 for fur ther details foorc Per user configuration file See foo 5 for further details ENVIRONMENT FOOCONF If non null the full pathname for an alternate system wide foo conf Overridden by the c option DIAGNOSTICS The following diagnostics may be issued on stderr Bad magic number The input file does not look like an archive file Old style baz segments foo can only handle new style baz segments COBOL object libraries are not supported in this version 3 How should a formatted man page look 4 Linux Man Page Howto BUGS The command name should have been chosen mor carefully to reflect its purpose
10. Should I distribute source and or already formatted documentation eres 11 5 What are tbe font conventio 7 desee HS RpRRIEREEDREEEERHAT HEN REEAREERNNNER REEH RARE AS EEUNR EAE EREDeUE E pNA X ERES EM EPIO MER 12 D Po lishing your man LIE m 14 10 How do I get a plain text man page without all that H stuff ooososoosossoesoosssssssosssesoososssssossoseo 15 11 How do I get a high quality PostScript man page eese cesse esee eese esee eee eene tees te sete sten etna etna s taa 16 12 How do I get apropos and whatis to work eee eee eee esee seres esee setae teneas teens ta stas ts ense tnea 17 13 Copying COMOROS RC ednassiasqeaissaraiernideasvssiantersisceunsaaseesiaaenannaannte 18 14 Acknovledgenaepts cuces bed EIER RERER PII ERE EERREI OA r RM RENE ERE UR EIER rA ERS E PARE RM NE ESS 19 1 A few thoughts on documentation Why do we write documentation Silly question Because we want others to be able to use our program library function or whatever we have written and made available But writing documentation is not all there is to it Documentation must be accessible If it s hidden in some non standard place where the documentation related tools won t find it how can it serve its purpose Documentation must be reliable and accurate There s nothing more annoying than having program behaviour and documentation disagree Users will c
11. ce and binary forms with or without modification are permitted provided that the following conditions cus ieu 1 Redistributions of source code must retain the above copyright notice this list of conditions and the following disclaimer 2 Redistributions in binary form must reproduce the above copyright notice this list of conditions and the following disclaimer in the documentation and or other materials provided with the distribution THIS SOFTWARE IS PROVIDED BY THE AUTHOR AS IS AND ANY EXPRESS OR IMPLIED WARRANTIES INCLUDING BUT NOT LIMITED TO HE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT INDIRECT INCIDENTAL SPECIAL EXEMPLARY OR CONSEQUENTIAL DAMAGES S H S I INCLUDING BUT NOT LIMITED TO PROCUREMENT OF SUBSTITUTE GOODS OR BITSVAT BIS MEI OS sm OFM USE an AWEAy aOR 2 OFS MORBUS NERS S OSTEN ETEET LESE TITO IND OWEVER CAUSED AND ON ANY THEORY OF LIABILITY WHETHER IN CONTRACT TRICT LIABILITY OR TORT INCLUDING NEGLIGENCE OR OTHERWISE ARISING N ANY WAY OUT OF THE USE OF THIS SOFTWARE EVEN IF ADVISED OF THE POS SS psy TORT SUC HEP AMAGBE I 13 Copy
12. e only accessible under one name We cannot expect a user to remember that the egrep man page is actually the grep man page It is therefore necessary to have the man page available under different names You have several possibilities to achieve this 1 have identical copies for each name 2 connect all man pages using hard links 3 symbolic links pointing to the actual man page 4 use groff s source mechanism provided by the so macro The first way is obviously a waste of disk space The second is not recommended because intelligent versions of the catman program can save a lot of work by looking at the the file type or contents Hard links will prevent catman from being clever Note that catman s purpose is to format all man pages so they can be displayed quickly The third alternative has a slight drawback if flexibility is a concern you have to be aware that there are file systems that do not support symbolic links The upshot of this is that the Best Thing TM is using groff s source mechanism Here s how to do it If you want to have your man page available under the names foo and bar in section 1 then put the man page in foo 1 and have bar 1 look like this So manl foo 1 It is important to specify the man1 directory part as well as the file name foo 1 because when grof f is run by the browser it will have the manual base directory as its current working directory cwd and groff interprets so arguments relative to
13. ing conditions 18 14 Acknowledgements Michael Miller for proofreading the whole HOWTO in February 2001 Gordon Torrie for many helpful grammar remarks in August 2001 Any remaining grammar or style bogons are entirely my fault e S u S E de or com who are the only distributor to keep sending me a free copy of their latest product acknowledging my work as a howto author George B Moody for additional suggestions on how to polish a man page If your name is missing here drop me a note 14 Acknowledgements 19 15 Changelog e March 6 2001 HTML source now passes weblint pedant ic Paragraph 6 Added workarounds for t b1 screw ups Added Acknowledgements and Changelog Added RCS Id August 9 2001 Howto put under a two clause BSD license August 20 2001 Improved grammar Use a numbered list for the TOC e October 28 2001 Added refs to mdoc 7 mdoc samples 7 and groff_man 7 April 28 2002 Fix a grammar bogon by s particular particularly April 30 2002 Update the link to the groff mdoc BSD tutorial November 29 2002 More suggestions for polishing your man page December 15 2002 Publish SGML derived HTML Removed dead link to LSM 15 Changelog 20
14. matted man page look 6 Linux Man Page Howto This overrides any B FOOCONF environment variable 5 12 In addition to the baz segments also parse the blurfl headers Pel UR s Recursive mode Operates as fast as lightning at the expense of a megabyte of virtual memory eon 2 LES I etc foo conf IRS The system wide configuration file See SIR LOG 5 for further details RE ol af sc OOS SES Per user configuration file See SENE ONIS for further details SH ENVIRONMENT P FOOCONF If non null the full pathname for an alternate system wid I oR OG COME Overridden by the EN option SH DIAGNOSTICS The following diagnostics may be issued on stderr Bad magic number The input file does not look like an archive file Old style baz segments RS 513 FOO can only handle new style baz segments COBOL object libraries are not supported in this version SH BUGS The command name should have been chosen more carefully to reflect its purpose SH AUTHOR Jens Schweikhardt lt howto at schweikhardt dot net gt seus Uam ziUISXO U TERTE TERE IO 09 5 ZBERE VAZN 3 How should a formatted man page look 4 How do document several programs functions in a single man page Many programs grep egrep and functions printf fprintf are documented in a single man page However these man pages would be quite useless if they wer
15. n existent If you re brave you can describe here the limitations known inconveniences and features that others may regard as misfeatures If you re not so brave rename it the TO DO section The AUTHOR section is nice to have in case there are gross errors in the documentation or program behaviour Bzzt and you want to mail a bug report The SEE ALSO section is a list of related man pages in alphabetical order Conventionally it is the last section You are free to invent other sections if they really don t fit in one of those described so far So how exactly did you generate that man page I expected that question here s the source Luke Process this file with aN V gror mem Tagel soo ENN TH FOO 1 MARCH 1995 Linux User Manuals SH NAME foo N frobnicate the bar library wot STNOESTS 5 o0 l bar e i conmisdcoedidslte alg T B maie SH DESCRIPTION B foo frobnicates the bar library by tweaking internal symbol tables By default it parses all baz segments and rearranges them in reverse order by time for the BRESAN CL linker to find them The symdef entry is then compressed using the WBG Whiz Bang Gizmo algorithm All files are processed in the order specified POOLE EXON gt 2 H Do not write busy to stdout while processing J 9 UG xoiuE ale ist ike Use the alternate system wid sdb COE ie 2 ILS instead of IR etc foo conf 3 How should a for
16. nto LaTeX RTF SGML and other formats check these out if you want to incorporate your man pages in a book or other larger document e Try translating your man page to HTML using man2htm1 which has been part of the Linux man package since man 1 4 The man2htm1 utility is a less ambitious translator than rman but almost every Linux user has it already so it is worth making sure that man2htm1 does not choke on your man page 9 Polishing your man page 14 10 How do I get a plain text man page without all that H stuff Have a look at co1 1 because col can filter out backspace sequences Just in case you can t wait that long funnypromp manpage txi groff t e mandoc Tascii manpage 1 col bx Gh ct The t and e switches tell groff to preprocess using tb1 and eqn This is overkill for man pages that don t require preprocessing but it does no harm apart from a few CPU cycles wasted On the other hand not using t when it is actually required does harm the table is terribly formatted You can even find out well guess is a better word what command is needed to format a certain grof f document not just man pages by issuing funnyprompt grog usr man man7 signal 7 groff t man usr man man7 signal 7 Grog stands for GROff Guess and it does what it says guess If it were perfect we wouldn t need options any more I ve seen it guess incorrectly on macro packages and on preprocessors Here is a little perl sc
17. r set version See the FS Stnd for a few common locale strings According to these guidelines we have our man pages in usr man locale man 1 91no The formatted versions should then be in usr man lt locale gt cat 1 9Ino of course otherwise we could only provide them for a single locale HOWEVER I can not recommend switching to that structure at this time The FS Stnd 1 2 also allows that Systems which use a unique language and code set for all manual pages may omit the locale substring and store all manual pages in lt mandir gt For example systems which only have English manual pages coded with ASCII may store manual pages the man 1 9 directories directly in usr man That is the traditional circumstance and arrangement in fact I would not switch until all tools like xman tkman info and many others that read man pages can cope with the new structure 2 How are man pages accessed 3 3 How should a formatted man page look Let me present you an example Below I will explain it in detail If you read this as plain text it won t show the different typefaces bold and italics TODO the bold and italics has disappeared with the conversion to SGML HTML Bring it back Please refer to the paragraph What are the font conventions for further explanations Here comes the man page for the hypothetical foo program FOO 1 User Manuals FOO 1 NAME foo frobnicate the bar library SYNO
18. ript I wrote that can delete the page headers and footers thereby saving you a few pages and mother nature a tree when printing long and elaborate man pages Save it in a file named strip headers amp chmod 755 usr bin perl wn make it slurp the whole file at once undef delete first header 6i Ni s Na f B delete last footer SPAN a 5 Wa ia GTP delete page breaks S Ne are Wied s Wwe sir NSHP o TE Nr ae Niu ASE collapse two or more blank lines into a single one s n 3 n n g see what s left piae You have to use it as the first filter after the man command as it relies on the number of newlines being output by grof f For example funnyprompt man bash strip headers col bx gt bash txt 10 How do get a plain text man page without all that H stuff 15 11 How do get a high quality PostScript man page funnyprompt groff t e mandoc Tps manpage 1 gt manpage ps Print or view that using your favorite PostScript printer viewer See question 10 for an explanation of the options 11 How do get a high quality PostScript man page 16 12 How dol get apropos and whatis to work Suppose you wonder what compilers are installed on your system and how these can be invoked To answer this frequently asked question you say funnyprompt apropos compiler fy Cl Torca 77 Coronet gee NL CU C ancl eal oT STIR pe 1 Pascal compiler Apropos and whatis are used to quickl
19. rnel routine documentation Deprecated New documentation that may be moved to a more appropriate section Deprecated Old documentation that may be kept for a grace period Deprecated Local documentation referring to this particular system FOS oo 1oy Ou WD The name of the man page s source file the input to the formatting system is the name of the command function or file name followed by a dot followed by the section character If you write the documentation on the format of the passwd file you have to name the source file passwd 5 Here we also have an example of a file name that is the same as a command name There might be even a library subroutine named passwd Sectioning is the usual way to resolve these ambiguities The command description is found in the file passwd 1 and the hypothetical library subroutine in passwd 3 Sometimes additional characters are appended and the file name looks for example like xterm 1x or wish 1tk The intent is to indicate that this is documentation for an X Window program or a Tk application respectively Some manual browsers can make use of this additional information For example xman will use xterm x and wish tk in the list of available documentation Please don t use the n o and 1 sections according to the File System Standard these sections are deprecated Stick to the numeric sections Beware of name clashes with existing programs functions or file names It is
20. t More on this later The only other file in any base directory should be a file named whatis The purpose and creation of this file will also be described under paragraph 12 The safest way to have a man page for section s installed in the right place is to put it in the directory 2 How are man pages accessed 2 Linux Man Page Howto usr man man lt s gt A good Makefile however will allow the user to chose a base directory by means of a make variable MANDIR say Most of the GNU packages can be configured with the prefix what ever option The manuals will then be installed under the base directory what ever man I suggest you also provide a way to do something similar With the advent of the Linux File System Standard FS Stnd things became more complicated Note the FS Stnd appears to be replaced by the Filesystem Hierarchy Standard FHS The FS Stnd 1 2 states that Provisions must be made in the structure of usr man to support manual pages which are written in different or multiple languages This is achieved by introducing another directory level that distinguishes between different languages Quoting again from FS Stnd 1 2 This naming of language subdirectories of usr man is based on Appendix E of the POSIX 1003 1 standard which describes the locale identification string the most well accepted method to describe a cultural environment The locale string is language territory characte
21. the result still look okay YMMV so please test this with your particular man page I have yet to see a man page requiring pic preprocessing But I would not like it As you can see above xman will not use it and groff will certainly do the funky wadakiki on the input 6 What preprocessors may use 10 7 Should I distribute source and or already formatted documentation Let me give the pros and cons of a few selected possibilities Source only smaller distribution package inaccessible on systems without groff Uncompressed formatted only accessible even on systems without groff the user can t generate a dvi or postscript file waste of disk space on systems that also handle compressed pages 3 Compressed formatted only accessible even on systems without groff the user can t generate a dvi or postscript file which compression format would you use Z z gz All of them 4 Source and uncompressed formatted accessible even on systems without groff larger distribution package some systems may expect compressed formatted man pages redundant information on systems equipped with grof f Ne IMHO it is best to distribute source only The argument that it s inaccessible on systems without groff does not matter The 500 man pages of the Linux Documentation Project are source only The man pages of XFree86 are source only The man pages from the FSF are source only In fact I have
22. u should make use of the different typefaces portions shamelessly stolen from man 7 Although there are many arbitrary conventions for man pages in the UNIX world the existence of several hundred Linux specific man pages defines our standards For functions the arguments are always specified using italics even in the SYNOPSIS section where the rest of the function is specified in bold BI myfunction int argc char argv Filenames are always in italics except in the SYNOPSIS section where included files are in bold So you should use I usr include stdio h and 8 What are the font conventions 12 Linux Man Page Howto B include lt stdio h gt Special macros which are usually in upper case are in bold B MAXINT When enumerating a list of error codes the codes are in bold This list usually uses the TP paragraph with hanging tag macro as follows TP B EBADF I fd is not a valid file descriptor TP B EINV AL I fd is unsuitable for reading Any reference to another man page or to the subject of the current man page is in bold If the manual section number is given it is given in roman without any spaces BR man 7 Acronyms look best when typeset in small type face So I recommend SM UNIX SM ASCII SM TAB SM NFS SM LALR 1 8 What are the font conventions 13 9 Polishing your man page Following are some guidelines that increase reliability readability and formatability
23. urse you send you hate mail and throw your work into the bit bucket with the firm intent to never install anything written by that jerk again The historical and well known way documentation is accessed on UNIX is via the man 1 command This HOWTO describes what you have to do to write a man page that will be correctly processed by the documentation related tools The most important of these tools are man 1 xman 1x apropos 1 makewhatis 8 and catman 8 Reliability and accuracy of the information are of course up to you But even in this respect you will find some ideas below that help you avoid some common glitches 1 A few thoughts on documentation 1 2 How are man pages accessed You need to know the precise mechanism for acccessing man pages in order to give your man page the right name and install it in the right place Each man page should be categorized in a specific section denoted by a single character The most common sections under Linux and their human readable names are Section The human readable name il User commands that may be started by everyon System calls that is functions provided by the kernel Sulswoucimes timate as llilowainy iumeiLoms o Devices that is special files in the dev directory File format descriptions e g etc passwd Games self explanatory Miscellaneous e g macro packages conventions System administration tools that only root can execute Another Linux specific place for ke
24. w on and concerning macros only holds true for tmac an If you want to use the tmac doc macros anyway have a look at the tutorial sampler ndoc samples Some distros I m told also come with mdoc 7 mdoc samples 7 and groff man 7 The definitive dope for t rof f with all macros explained is the Troff User s Manual available as html PostScript ps 760K or Portable Document Format pdf 240K by Jospeh F Ossanna and Brian W Kernighan revised November 1992 AT amp T Bell Labs have made it publicly available Don t forget to check out the late great W Richard Steven s homepage famous for Unix Network Programming as well as the TCP IP Illustrated trilogy who also has a list of Troff Resources including tbl eqn pic and other filters 5 Which macro package should use 9 6 What preprocessors may I use Groff comes with at least three preprocessors tbl eqn and pic on some systems they are named gtbl geqn and gpic Their purpose is to translate preprocessor macros and their data to regular troff input Tb1 is a table preprocessor eqn is an equations maths preprocessor and pic is a picture preprocessor Please refer to the man pages for more information on what functionality they provide To put it in a nutshell don t write man pages requiring any preprocessor Eqn will generally produce terrible output for typewriter like devices unfortunately the type of device 99 of all man pages are viewed on well at least I do
25. y report which man page has information on a certain topic Both programs search a number of files named whatis that may be found in each of the manual base directories As previously stated the whatis data base files contain a one line entry for any man page in the respective directory tree In fact that line is exactly the NAME section to be precise joined on one line and with hyphenation removed note that the section is mentioned within parentheses The whatis database files are created with the makewhatis 8 program There are several versions around so please refer to the man page to determine what options are available In order for makewhat is to be able to extract the NAME sections correctly it is important that you the manual writer adhere to the NAME section format described under question 3 The differences between apropos and whatis are simply where in the line they look and what they are looking for Apropos which is equivalent to man k searches the argument string anywhere on the line whereas whatis equivalent to man tries to match a complete command name only on the part before the dash Consequently whatis cc willreport if there is a cc manual and remain quiet for gcc Corrections and suggestions welcome 12 How do get apropos and whatis to work 17 13 Copying conditions Copyright 1995 2001 by Jens Schweikhardt All rights reserved Two clause BSD License Redistribution and use in sour
Download Pdf Manuals
Related Search