📄 ch50_10.htm
字号:
<HTML><!--Distributed by F --><HEAD><TITLE>[Chapter 50] 50.10 Make Your Own Man Pages Without Learning troff</TITLE><METANAME="DC.title"CONTENT="UNIX Power Tools"><METANAME="DC.creator"CONTENT="Jerry Peek, Tim O'Reilly & Mike Loukides"><METANAME="DC.publisher"CONTENT="O'Reilly & Associates, Inc."><METANAME="DC.date"CONTENT="1998-08-04T21:57:00Z"><METANAME="DC.type"CONTENT="Text.Monograph"><METANAME="DC.format"CONTENT="text/html"SCHEME="MIME"><METANAME="DC.source"CONTENT="1-56592-260-3"SCHEME="ISBN"><METANAME="DC.language"CONTENT="en-US"><METANAME="generator"CONTENT="Jade 1.1/O'Reilly DocBook 3.0 to HTML 4.0"><LINKREV="made"HREF="mailto:online-books@oreilly.com"TITLE="Online Books Comments"><LINKREL="up"HREF="ch50_01.htm"TITLE="50. Help--Online Documentation, etc."><LINKREL="prev"HREF="ch50_09.htm"TITLE="50.9 Reading a Permuted Index "><LINKREL="next"HREF="ch50_11.htm"TITLE="50.11 Writing a Simple Man Page with the -man Macros "></HEAD><BODYBGCOLOR="#FFFFFF"TEXT="#000000"><DIVCLASS="htmlnav"><H1><IMGSRC="gifs/smbanner.gif"ALT="UNIX Power Tools"USEMAP="#srchmap"BORDER="0"></H1><MAPNAME="srchmap"><AREASHAPE="RECT"COORDS="0,0,466,58"HREF="index.htm"ALT="UNIX Power Tools"><AREASHAPE="RECT"COORDS="467,0,514,18"HREF="jobjects/fsearch.htm"ALT="Search this book"></MAP><TABLEWIDTH="515"BORDER="0"CELLSPACING="0"CELLPADDING="0"><TR><TDALIGN="LEFT"VALIGN="TOP"WIDTH="172"><ACLASS="SECT1"HREF="ch50_09.htm"TITLE="50.9 Reading a Permuted Index "><IMGSRC="gifs/txtpreva.gif"SRC="gifs/txtpreva.gif"ALT="Previous: 50.9 Reading a Permuted Index "BORDER="0"></A></TD><TDALIGN="CENTER"VALIGN="TOP"WIDTH="171"><B><FONTFACE="ARIEL,HELVETICA,HELV,SANSERIF"SIZE="-1">Chapter 50<BR>Help--Online Documentation, etc.</FONT></B></TD><TDALIGN="RIGHT"VALIGN="TOP"WIDTH="172"><ACLASS="SECT1"HREF="ch50_11.htm"TITLE="50.11 Writing a Simple Man Page with the -man Macros "><IMGSRC="gifs/txtnexta.gif"SRC="gifs/txtnexta.gif"ALT="Next: 50.11 Writing a Simple Man Page with the -man Macros "BORDER="0"></A></TD></TR></TABLE> <HRALIGN="LEFT"WIDTH="515"TITLE="footer"></DIV><DIVCLASS="SECT1"><H2CLASS="sect1"><ACLASS="title"NAME="UPT-ART-1030">50.10 Make Your Own Man Pages Without Learning troff</A></H2><PCLASS="para"><ACLASS="indexterm"NAME="UPT-ART-1030-IX-COMMANDS-WRITING-MANUAL-PAGES-FOR"></A><ACLASS="indexterm"NAME="UPT-ART-1030-IX-MANUAL-PAGES-WRITING"></A><ACLASS="indexterm"NAME="UPT-ART-1030-IX-MANUAL-PAGES-FORMATTING"></A>We strongly suggest that you write a manual page for each command thatyou place in your <EMCLASS="emphasis">bin</EM> directory. UNIX manual pages typicallyhave the following format, which we suggest you follow:</P><PCLASS="para"><BLOCKQUOTECLASS="screen"><PRECLASS="screen">NAME the program's name - one line summary of what it doesSYNOPSIS how to invoke the program, including all arguments and command-line options. (Optional arguments are placed in square brackets)DESCRIPTION a description of what the program does-as long as is necessaryOPTIONS an explanation of each optionEXAMPLES One or more examples of how to use the programENVIRONMENT Any environment variables that control the program's behaviorFILES Files the program internals will read or write. May include temporary files. Doesn't include files on the command line.BUGS Any known bugs. The standard manual pages don't take bug-recording seriously, but this can be very helpful.AUTHOR Who wrote the program</PRE></BLOCKQUOTE></P><PCLASS="para">To see how a "real" manual page looks, type <CODECLASS="literal">man ls</CODE>.</P><PCLASS="para"><ACLASS="indexterm"NAME="AUTOID-59538"></A><ACLASS="indexterm"NAME="AUTOID-59540"></A>Feel free to add any other sections that you think are necessary.You can use the<SPANCLASS="link"><EMCLASS="emphasis">nroff</EM> (<ACLASS="linkend"HREF="ch43_13.htm"TITLE="The Text Formatters nroff, troff, ditroff, ... ">43.13</A>)</SPAN><SPANCLASS="link"><EMCLASS="emphasis">-man</EM> macros (<ACLASS="linkend"HREF="ch50_11.htm"TITLE="Writing a Simple Man Page with the -man Macros ">50.11</A>)</SPAN>if you want a nicely formattedmanual page. However, <EMCLASS="emphasis">nroff</EM> is fairly complicated and, for this purpose,not really necessary. Just create a text file that looks like the onewe showed above. If you are using a BSD system and want your manualpages formatted with <EMCLASS="emphasis">nroff</EM>, look at any of thefiles in <EMCLASS="emphasis">/usr/man/man1</EM> and copy it.</P><PCLASS="para">Hint: If you insist on formatting your manual page properly, using the<EMCLASS="emphasis">troff</EM> or <EMCLASS="emphasis">groff</EM>"man" macros, you can use <EMCLASS="emphasis">nroff</EM> to preview the file.The<SPANCLASS="link"><EMCLASS="emphasis">man</EM> (<ACLASS="linkend"HREF="ch50_01.htm#UPT-ART-4910"TITLE="UNIX Online Documentation ">50.1</A>)</SPAN>command is essentially the same as:</P><PCLASS="para"><TABLECLASS="screen.co"BORDER="1"><TR><THVALIGN="TOP"><PRECLASS="calloutlist"><ACLASS="co"HREF="ch25_03.htm"TITLE="25.3 Using more to Page Through Files ">more</A> <ACLASS="co"HREF="ch25_10.htm"TITLE="25.10 Squash Extra Blank Lines ">-s</A> </PRE></TH><TDVALIGN="TOP"><PRECLASS="screen">% <CODECLASS="userinput"><B>nroff -e -man </B></CODE><CODECLASS="replaceable"><I>filename</I></CODE><CODECLASS="userinput"><B> | more -s</B></CODE></PRE></TD></TR></TABLE></P><PCLASS="para">You can safely omit the <EMCLASS="emphasis">-e</EM> option to <EMCLASS="emphasis">nroff</EM> and the <EMCLASS="emphasis">-s</EM>option to <EMCLASS="emphasis">more</EM>. And remember that <EMCLASS="emphasis">nroff</EM> may not beavailable on many versions of System V UNIX, but the Power Toolsdisc has<SPANCLASS="link"><EMCLASS="emphasis">gnroff</EM> and <EMCLASS="emphasis">awf</EM> (<ACLASS="linkend"HREF="ch43_17.htm"TITLE="Don't Have nroff? Try gnroff or awf ">43.17</A>)</SPAN>.</P><PCLASS="para">Now, you want to make this manual page "readable" by the standard<EMCLASS="emphasis">man</EM>command.For BSD systems, there are a few ways to do this. Create the directory <EMCLASS="emphasis">man</EM> in your home directory; create the directory<EMCLASS="emphasis">cat1</EM> as a subdirectory of <EMCLASS="emphasis">man</EM>; then copy your manualentry into <EMCLASS="emphasis">cat1</EM>, with the name <EMCLASS="emphasis">program.1</EM> (where<EMCLASS="emphasis">program</EM> is the name of your special command). When you want toread the manual page, give the command:</P><PCLASS="para"><TABLECLASS="screen.co"BORDER="1"><TR><THVALIGN="TOP"><PRECLASS="calloutlist"><ACLASS="co"HREF="ch14_11.htm"TITLE="14.11 Finding (Anyone's) Home Directory, Quickly ">~</A> </PRE></TH><TDVALIGN="TOP"><PRECLASS="screen">% <CODECLASS="userinput"><B>man -M ~/man </B></CODE><CODECLASS="replaceable"><I>program</I></CODE></PRE></TD></TR></TABLE></P><PCLASS="para">Shortcut: We like to be more strict about naming things properly,but you can omit the <EMCLASS="emphasis">man</EM> directory, and just put the <EMCLASS="emphasis">cat1</EM>directory into your home directory. In this case, the command wouldbe:</P><PCLASS="para"><BLOCKQUOTECLASS="screen"><PRECLASS="screen">% <CODECLASS="userinput"><B>man -M ~ </B></CODE><CODECLASS="replaceable"><I>program</I></CODE></PRE></BLOCKQUOTE></P><PCLASS="para"><ACLASS="indexterm"NAME="AUTOID-59593"></A>Some systems have a<EMCLASS="emphasis">MANPATH</EM><SPANCLASS="link">environment variable (<ACLASS="linkend"HREF="ch06_01.htm#UPT-ART-1170"TITLE="What Environment Variables Are Good For ">6.1</A>)</SPAN>,a colon-separated list of directories where the <EMCLASS="emphasis">man</EM> command should look.For example, my <EMCLASS="emphasis">MANPATH</EM> contains:</P><PCLASS="para"><BLOCKQUOTECLASS="screen"><PRECLASS="screen">/home/mike/man:/usr/local/man:/usr/man</PRE></BLOCKQUOTE></P><PCLASS="para"><EMCLASS="emphasis">MANPATH</EM> can be more convenient than the <EMCLASS="emphasis">-M</EM> option.</P><PCLASS="para">HINT: We are telling you to put the manual page into the <EMCLASS="emphasis">cat1</EM>directory rather than the <EMCLASS="emphasis">man1</EM> directorybecause the <EMCLASS="emphasis">man</EM> program assumes that files in <EMCLASS="emphasis">cat1</EM> arealready formatted.</P><PCLASS="para">If you are sharing your program with other people on the system, youshould put your manual entry in a public place. Become superuser andcopy your documentation into<EMCLASS="emphasis">/usr/local/man/catl</EM>, giving it the name <EMCLASS="emphasis">program.l</EM>(the "l" stands for "local"). If you can't become superuser, get thesystem administrator to do it for you. Make sure that everyone canread the manual page; the permissions should be something like this:</P><PCLASS="para"><BLOCKQUOTECLASS="screen"><PRECLASS="screen">% <CODECLASS="userinput"><B>ls -l /usr/local/man/catl</B></CODE>-r--r--r-- 1 root 468 Aug 5 09:21 program.l</PRE></BLOCKQUOTE></P><PCLASS="para">Then give the command <CODECLASS="literal">man</CODE> <CODECLASS="replaceable"><I>program</I></CODE> to read your documentation.</P><PCLASS="para">If you are working on some System V variants, therules are a little different.The organization of the manual pages andthe <EMCLASS="emphasis">man</EM> command itself are slightly different - and really, notas good. Write your manual entry and place it in your <EMCLASS="emphasis">doc</EM>directory. Then create the following<SPANCLASS="link">C shell alias (<ACLASS="linkend"HREF="ch10_03.htm"TITLE="C Shell Aliases with Command-Line Arguments ">10.3</A>)</SPAN>:</P><PCLASS="para"><BLOCKQUOTECLASS="screen"><PRECLASS="screen">alias myman "(cd ~/doc; man -d \!$ | pg)"</PRE></BLOCKQUOTE></P><PCLASS="para">or<SPANCLASS="link">shell function (<ACLASS="linkend"HREF="ch10_09.htm"TITLE="Shell Functions ">10.9</A>)</SPAN>:</P><PCLASS="para"><BLOCKQUOTECLASS="screen"><PRECLASS="screen">myman() { (cd $HOME/doc; man -d "$1" | pg); }</PRE></BLOCKQUOTE></P><PCLASS="para">Now the command <EMCLASS="emphasis">myman docfilename</EM> will retrieve your manual page.Note that if you use a section-number extension like <CODECLASS="literal">.1</CODE>,you have to give the entire filename (e.g., <EMCLASS="emphasis">program.1</EM>),not just the program's name.</P><PCLASS="para">If you want to makeyour manual page publicly available, copy the file into the directory<EMCLASS="emphasis">/usr/man/u_man/man1</EM>; you may have to become superuser to do so.Make sure that anyone on the system can read your file.If the entryis extremely long and you want to save space in your filesystem, youcan use the <EMCLASS="emphasis">pack</EM> utilityon your documentation file.The resulting filewill have the name <EMCLASS="emphasis">program.1.z</EM>; the <EMCLASS="emphasis">man</EM> command willautomatically unpack the file whenever anyone reads it.<ACLASS="indexterm"NAME="AUTOID-59638"></A><ACLASS="indexterm"NAME="AUTOID-59639"></A><ACLASS="indexterm"NAME="AUTOID-59640"></A></P><DIVCLASS="sect1info"><PCLASS="SECT1INFO">- <SPANCLASS="authorinitials">ML</SPAN></P></DIV></DIV><DIVCLASS="htmlnav"><P></P><HRALIGN="LEFT"WIDTH="515"TITLE="footer"><TABLEWIDTH="515"BORDER="0"CELLSPACING="0"CELLPADDING="0"><TR><TDALIGN="LEFT"VALIGN="TOP"WIDTH="172"><ACLASS="SECT1"HREF="ch50_09.htm"TITLE="50.9 Reading a Permuted Index "><IMGSRC="gifs/txtpreva.gif"SRC="gifs/txtpreva.gif"ALT="Previous: 50.9 Reading a Permuted Index "BORDER="0"></A></TD><TDALIGN="CENTER"VALIGN="TOP"WIDTH="171"><ACLASS="book"HREF="index.htm"TITLE="UNIX Power Tools"><IMGSRC="gifs/txthome.gif"SRC="gifs/txthome.gif"ALT="UNIX Power Tools"BORDER="0"></A></TD><TDALIGN="RIGHT"VALIGN="TOP"WIDTH="172"><ACLASS="SECT1"HREF="ch50_11.htm"TITLE="50.11 Writing a Simple Man Page with the -man Macros "><IMGSRC="gifs/txtnexta.gif"SRC="gifs/txtnexta.gif"ALT="Next: 50.11 Writing a Simple Man Page with the -man Macros "BORDER="0"></A></TD></TR><TR><TDALIGN="LEFT"VALIGN="TOP"WIDTH="172">50.9 Reading a Permuted Index </TD><TDALIGN="CENTER"VALIGN="TOP"WIDTH="171"><ACLASS="index"HREF="index/idx_0.htm"TITLE="Book Index"><IMGSRC="gifs/index.gif"SRC="gifs/index.gif"ALT="Book Index"BORDER="0"></A></TD><TDALIGN="RIGHT"VALIGN="TOP"WIDTH="172">50.11 Writing a Simple Man Page with the -man Macros </TD></TR></TABLE><HRALIGN="LEFT"WIDTH="515"TITLE="footer"><IMGSRC="gifs/smnavbar.gif"SRC="gifs/smnavbar.gif"USEMAP="#map"BORDER="0"ALT="The UNIX CD Bookshelf Navigation"><MAPNAME="map"><AREASHAPE="RECT"COORDS="0,0,73,21"HREF="../index.htm"ALT="The UNIX CD Bookshelf"><AREASHAPE="RECT"COORDS="74,0,163,21"HREF="index.htm"ALT="UNIX Power Tools"><AREASHAPE="RECT"COORDS="164,0,257,21"HREF="../unixnut/index.htm"ALT="UNIX in a Nutshell"><AREASHAPE="RECT"COORDS="258,0,321,21"HREF="../vi/index.htm"ALT="Learning the vi Editor"><AREASHAPE="RECT"COORDS="322,0,378,21"HREF="../sedawk/index.htm"ALT="sed & awk"><AREASHAPE="RECT"COORDS="379,0,438,21"HREF="../ksh/index.htm"ALT="Learning the Korn Shell"><AREASHAPE="RECT"COORDS="439,0,514,21"HREF="../lrnunix/index.htm"ALT="Learning the UNIX Operating System"></MAP></DIV></BODY></HTML>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -