home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _1830ec1782e9ee1188869e9ab1ca6052 < prev    next >
Text File  |  2000-03-23  |  12KB  |  241 lines
  1.  
  2. <HTML>
  3. <HEAD>
  4. <TITLE>Pod::Man - Convert POD data to formatted *roff input</TITLE>
  5. <LINK REL="stylesheet" HREF="../../Active.css" TYPE="text/css">
  6. <LINK REV="made" HREF="mailto:">
  7. </HEAD>
  8.  
  9. <BODY>
  10. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  11. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  12. <STRONG><P CLASS=block> Pod::Man - Convert POD data to formatted *roff input</P></STRONG>
  13. </TD></TR>
  14. </TABLE>
  15.  
  16. <A NAME="__index__"></A>
  17. <!-- INDEX BEGIN -->
  18.  
  19. <UL>
  20.  
  21.     <LI><A HREF="#name">NAME</A></LI><LI><A HREF="#supportedplatforms">SUPPORTED PLATFORMS</A></LI>
  22.  
  23.     <LI><A HREF="#synopsis">SYNOPSIS</A></LI>
  24.     <LI><A HREF="#description">DESCRIPTION</A></LI>
  25.     <LI><A HREF="#diagnostics">DIAGNOSTICS</A></LI>
  26.     <LI><A HREF="#bugs">BUGS</A></LI>
  27.     <LI><A HREF="#see also">SEE ALSO</A></LI>
  28.     <LI><A HREF="#author">AUTHOR</A></LI>
  29. </UL>
  30. <!-- INDEX END -->
  31.  
  32. <HR>
  33. <P>
  34. <H1><A NAME="name">NAME</A></H1>
  35. <P>Pod::Man - Convert POD data to formatted *roff input</P>
  36. <P>
  37. <HR>
  38. <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1>
  39. <UL>
  40. <LI>Linux</LI>
  41. <LI>Solaris</LI>
  42. <LI>Windows</LI>
  43. </UL>
  44. <HR>
  45. <H1><A NAME="synopsis">SYNOPSIS</A></H1>
  46. <PRE>
  47.     use Pod::Man;
  48.     my $parser = Pod::Man->new (release => $VERSION, section => 8);</PRE>
  49. <PRE>
  50.     # Read POD from STDIN and write to STDOUT.
  51.     $parser->parse_from_filehandle;</PRE>
  52. <PRE>
  53.     # Read POD from file.pod and write to file.1.
  54.     $parser->parse_from_file ('file.pod', 'file.1');</PRE>
  55. <P>
  56. <HR>
  57. <H1><A NAME="description">DESCRIPTION</A></H1>
  58. <P>Pod::Man is a module to convert documentation in the POD format (the
  59. preferred language for documenting Perl) into *roff input using the man
  60. macro set.  The resulting *roff code is suitable for display on a terminal
  61. using nroff(1), normally via man(1), or printing using troff(1).  It is
  62. conventionally invoked using the driver script <STRONG>pod2man</STRONG>, but it can also
  63. be used directly.</P>
  64. <P>As a derived class from Pod::Parser, Pod::Man supports the same methods and
  65. interfaces.  See <A HREF="../../lib/Pod/Parser.html">the Pod::Parser manpage</A> for all the details; briefly, one creates a
  66. new parser with <CODE>Pod::Man->new()</CODE> and then calls either
  67. <CODE>parse_from_filehandle()</CODE> or parse_from_file().</P>
  68. <P><CODE>new()</CODE> can take options, in the form of key/value pairs that control the
  69. behavior of the parser.  See below for details.</P>
  70. <P>If no options are given, Pod::Man uses the name of the input file with any
  71. trailing <CODE>.pod</CODE>, <CODE>.pm</CODE>, or <CODE>.pl</CODE> stripped as the man page title, to
  72. section 1 unless the file ended in <CODE>.pm</CODE> in which case it defaults to
  73. section 3, to a centered title of ``User Contributed Perl Documentation'', to
  74. a centered footer of the Perl version it is run with, and to a left-hand
  75. footer of the modification date of its input (or the current date if given
  76. STDIN for input).</P>
  77. <P>Pod::Man assumes that your *roff formatters have a fixed-width font named
  78. CW.  If yours is called something else (like CR), use the <A HREF="#item_fixed"><CODE>fixed</CODE></A> option to
  79. specify it.  This generally only matters for troff output for printing.
  80. Similarly, you can set the fonts used for bold, italic, and bold italic
  81. fixed-width output.</P>
  82. <P>Besides the obvious pod conversions, Pod::Man also takes care of formatting
  83. func(), func(n), and simple variable references like $foo or @bar so you
  84. don't have to use code escapes for them; complex expressions like
  85. <CODE>$fred{'stuff'}</CODE> will still need to be escaped, though.  It also translates
  86. dashes that aren't used as hyphens into en dashes, makes long dashes--like
  87. this--into proper em dashes, fixes ``paired quotes,'' makes C++ and PI look
  88. right, puts a little space between double underbars, makes ALLCAPS a teeny
  89. bit smaller in troff(1), and escapes stuff that *roff treats as special so
  90. that you don't have to.</P>
  91. <P>The recognized options to <CODE>new()</CODE> are as follows.  All options take a single
  92. argument.</P>
  93. <DL>
  94. <DT><STRONG><A NAME="item_center">center</A></STRONG><BR>
  95. <DD>
  96. Sets the centered page header to use instead of ``User Contributed Perl
  97. Documentation''.
  98. <P></P>
  99. <DT><STRONG><A NAME="item_date">date</A></STRONG><BR>
  100. <DD>
  101. Sets the left-hand footer.  By default, the modification date of the input
  102. file will be used, or the current date if <A HREF="../../lib/Pod/perlfunc.html#item_stat"><CODE>stat()</CODE></A> can't find that file (the
  103. case if the input is from STDIN), and the date will be formatted as
  104. YYYY-MM-DD.
  105. <P></P>
  106. <DT><STRONG><A NAME="item_fixed">fixed</A></STRONG><BR>
  107. <DD>
  108. The fixed-width font to use for vertabim text and code.  Defaults to CW.
  109. Some systems may want CR instead.  Only matters for <CODE>troff(1)</CODE> output.
  110. <P></P>
  111. <DT><STRONG><A NAME="item_fixedbold">fixedbold</A></STRONG><BR>
  112. <DD>
  113. Bold version of the fixed-width font.  Defaults to CB.  Only matters for
  114. <CODE>troff(1)</CODE> output.
  115. <P></P>
  116. <DT><STRONG><A NAME="item_fixeditalic">fixeditalic</A></STRONG><BR>
  117. <DD>
  118. Italic version of the fixed-width font (actually, something of a misnomer,
  119. since most fixed-width fonts only have an oblique version, not an italic
  120. version).  Defaults to CI.  Only matters for <CODE>troff(1)</CODE> output.
  121. <P></P>
  122. <DT><STRONG><A NAME="item_fixedbolditalic">fixedbolditalic</A></STRONG><BR>
  123. <DD>
  124. Bold italic (probably actually oblique) version of the fixed-width font.
  125. Pod::Man doesn't assume you have this, and defaults to CB.  Some systems
  126. (such as Solaris) have this font available as CX.  Only matters for <CODE>troff(1)</CODE>
  127. output.
  128. <P></P>
  129. <DT><STRONG><A NAME="item_release">release</A></STRONG><BR>
  130. <DD>
  131. Set the centered footer.  By default, this is the version of Perl you run
  132. Pod::Man under.  Note that some system an macro sets assume that the
  133. centered footer will be a modification date and will prepend something like
  134. ``Last modified: ''; if this is the case, you may want to set <A HREF="#item_release"><CODE>release</CODE></A> to
  135. the last modified date and <A HREF="#item_date"><CODE>date</CODE></A> to the version number.
  136. <P></P>
  137. <DT><STRONG><A NAME="item_section">section</A></STRONG><BR>
  138. <DD>
  139. Set the section for the <CODE>.TH</CODE> macro.  The standard section numbering
  140. convention is to use 1 for user commands, 2 for system calls, 3 for
  141. functions, 4 for devices, 5 for file formats, 6 for games, 7 for
  142. miscellaneous information, and 8 for administrator commands.  There is a lot
  143. of variation here, however; some systems (like Solaris) use 4 for file
  144. formats, 5 for miscellaneous information, and 7 for devices.  Still others
  145. use 1m instead of 8, or some mix of both.  About the only section numbers
  146. that are reliably consistent are 1, 2, and 3.
  147. <P>By default, section 1 will be used unless the file ends in .pm in which case
  148. section 3 will be selected.</P>
  149. <P></P></DL>
  150. <P>The standard Pod::Parser method <CODE>parse_from_filehandle()</CODE> takes up to two
  151. arguments, the first being the file handle to read POD from and the second
  152. being the file handle to write the formatted output to.  The first defaults
  153. to STDIN if not given, and the second defaults to STDOUT.  The method
  154. <CODE>parse_from_file()</CODE> is almost identical, except that its two arguments are the
  155. input and output disk files instead.  See <A HREF="../../lib/Pod/Parser.html">the Pod::Parser manpage</A> for the specific
  156. details.</P>
  157. <P>
  158. <HR>
  159. <H1><A NAME="diagnostics">DIAGNOSTICS</A></H1>
  160. <DL>
  161. <DT><STRONG><A NAME="item_roff_font_should_be_1_or_2_chars%2C_not_%60%25s%27">roff font should be 1 or 2 chars, not `%s'</A></STRONG><BR>
  162. <DD>
  163. (F) You specified a *roff font (using <A HREF="#item_fixed"><CODE>fixed</CODE></A>, <A HREF="#item_fixedbold"><CODE>fixedbold</CODE></A>, etc.) that
  164. wasn't either one or two characters.  Pod::Man doesn't support *roff fonts
  165. longer than two characters, although some *roff extensions do (the canonical
  166. versions of <CODE>nroff(1)</CODE> and <CODE>troff(1)</CODE> don't either).
  167. <P></P>
  168. <DT><STRONG><A NAME="item_Invalid_link_%25s">Invalid link %s</A></STRONG><BR>
  169. <DD>
  170. (W) The POD source contained a <CODE>L<></CODE> sequence that Pod::Man was
  171. unable to parse.  You should never see this error message; it probably
  172. indicates a bug in Pod::Man.
  173. <P></P>
  174. <DT><STRONG><A NAME="item_Unknown_escape_E%3C%25s%3E">Unknown escape E<%s></A></STRONG><BR>
  175. <DD>
  176. (W) The POD source contained an <CODE>E<></CODE> escape that Pod::Man didn't
  177. know about.  <CODE>E<%s></CODE> was printed verbatim in the output.
  178. <P></P>
  179. <DT><STRONG><A NAME="item_Unknown_sequence_%25s">Unknown sequence %s</A></STRONG><BR>
  180. <DD>
  181. (W) The POD source contained a non-standard interior sequence (something of
  182. the form <CODE>X<></CODE>) that Pod::Man didn't know about.  It was ignored.
  183. <P></P>
  184. <DT><STRONG><A NAME="item_Unmatched_%3Dback">Unmatched =back</A></STRONG><BR>
  185. <DD>
  186. (W) Pod::Man encountered a <CODE>=back</CODE> command that didn't correspond to an
  187. <CODE>=over</CODE> command.
  188. <P></P></DL>
  189. <P>
  190. <HR>
  191. <H1><A NAME="bugs">BUGS</A></H1>
  192. <P>The lint-like features and strict POD format checking done by <STRONG>pod2man</STRONG> are
  193. not yet implemented and should be, along with the corresponding <CODE>lax</CODE>
  194. option.</P>
  195. <P>The NAME section should be recognized specially and index entries emitted
  196. for everything in that section.  This would have to be deferred until the
  197. next section, since extraneous things in NAME tends to confuse various man
  198. page processors.</P>
  199. <P>The handling of hyphens, en dashes, and em dashes is somewhat fragile, and
  200. one may get the wrong one under some circumstances.  This should only matter
  201. for <CODE>troff(1)</CODE> output.</P>
  202. <P>When and whether to use small caps is somewhat tricky, and Pod::Man doesn't
  203. necessarily get it right.</P>
  204. <P>Pod::Man doesn't handle font names longer than two characters.  Neither do
  205. most <CODE>troff(1)</CODE> implementations, but GNU troff does as an extension.  It would
  206. be nice to support as an option for those who want to use it.</P>
  207. <P>The preamble added to each output file is rather verbose, and most of it is
  208. only necessary in the presence of E<> escapes for non-ASCII
  209. characters.  It would ideally be nice if all of those definitions were only
  210. output if needed, perhaps on the fly as the characters are used.</P>
  211. <P>Some of the automagic applied to file names assumes Unix directory
  212. separators.</P>
  213. <P>Pod::Man is excessively slow.</P>
  214. <P>
  215. <HR>
  216. <H1><A NAME="see also">SEE ALSO</A></H1>
  217. <P><A HREF="../../lib/Pod/Parser.html">Pod::Parser</A>, perlpod(1), pod2man(1), nroff(1), troff(1),
  218. man(1), <CODE>man(7)</CODE></P>
  219. <P>Ossanna, Joseph F., and Brian W. Kernighan.  ``Troff User's Manual,''
  220. Computing Science Technical Report No. 54, AT&T Bell Laboratories.  This is
  221. the best documentation of standard <CODE>nroff(1)</CODE> and troff(1).  At the time of
  222. this writing, it's available at <A HREF="http://www.cs.bell-labs.com/cm/cs/cstr.html.">http://www.cs.bell-labs.com/cm/cs/cstr.html.</A></P>
  223. <P>The man page documenting the man macro set may be <CODE>man(5)</CODE> instead of <CODE>man(7)</CODE>
  224. on your system.  Also, please see <CODE>pod2man(1)</CODE> for extensive documentation on
  225. writing manual pages if you've not done it before and aren't familiar with
  226. the conventions.</P>
  227. <P>
  228. <HR>
  229. <H1><A NAME="author">AUTHOR</A></H1>
  230. <P>Russ Allbery <<A HREF="mailto:rra@stanford.edu">rra@stanford.edu</A>>, based <EM>very</EM> heavily on the
  231. original <STRONG>pod2man</STRONG> by Tom Christiansen <<A HREF="mailto:tchrist@mox.perl.com">tchrist@mox.perl.com</A>>.</P>
  232. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  233. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  234. <STRONG><P CLASS=block> Pod::Man - Convert POD data to formatted *roff input</P></STRONG>
  235. </TD></TR>
  236. </TABLE>
  237.  
  238. </BODY>
  239.  
  240. </HTML>
  241.