home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 4 / Apprentice-Release4.iso / Source Code / C / Applications / MacPerl 5.0.3 / MacPerl Source ƒ / MacPerl5 / pod / perlpod.how / perlpod.how.rsrc / STR#_1026.txt < prev    next >
Encoding:
Text File  |  1995-01-16  |  2.7 KB  |  133 lines
  1. 
  2.  
  3. 
  4.  
  5. åDESCRIPTION
  6.  
  7. 
  8.  
  9. 
  10.  
  11. A pod-to-whatever translator reads a pod file paragraph by paragraph,
  12.  
  13. and translates it to the appropriate output format.  There are three kinds
  14.  
  15. of paragraphs:
  16.  
  17. 
  18.  
  19. 
  20.  
  21. 
  22.  
  23. ‚Ä¢ A verbatim paragraph, distinguished by being indented (that is, it starts
  24.  
  25. with space or tab).  It should be reproduced exactly, with tabs assumed to
  26.  
  27. be on 8-column boundaries.  There are no special formatting escapes, so
  28.  
  29. you can't italicize or anything like that.  A \e means \e, and nothing else.
  30.  
  31. 
  32.  
  33. ‚Ä¢ A command.  All command paragraphs start with "=", followed by an
  34.  
  35. identifier, followed by arbitrary text that the command can use however
  36.  
  37. it pleases.  Currently recognized commands are
  38.  
  39. 
  40.  
  41.     =head1 heading
  42.  
  43.     =head2 heading
  44.  
  45.     =item text
  46.  
  47.     =over N
  48.  
  49.     =back
  50.  
  51. 
  52.  
  53. ‚Ä¢ An ordinary block of text.  It will be filled, and maybe even justified.
  54.  
  55. Certain interior sequences are recognized both here and in commands:
  56.  
  57. 
  58.  
  59.     I<text>     italicize text, used for emphasis or variables
  60.  
  61.     B<text>     embolden text, used for switches and programs
  62.  
  63.     S<text>     text contains non-breaking spaces
  64.  
  65.     C<code>     literal code
  66.  
  67.     L<name>     A link (cross reference) to name
  68.  
  69.                     L<name>             manpage
  70.  
  71.                     L<name/ident>       item in manpage
  72.  
  73.                     L<name/"sec">       section in other manpage
  74.  
  75.                     L<"sec">            section in this manpage
  76.  
  77.                                         (the quotes are optional)
  78.  
  79.     F<file>     Used for filenames
  80.  
  81.     Z<>         A zero-width character
  82.  
  83. 
  84.  
  85. That's it.  The intent is simplicity, not power.  I wanted paragraphs to
  86.  
  87. look like paragraphs (block format), so that they stand out visually, and
  88.  
  89. so that I could run them through fmt easily to reformat them (that's F7 in
  90.  
  91. my version of vi).  I wanted the translator (and not me) to worry about
  92.  
  93. whether " or ' is a left quote or a right quote within filled text, and I
  94.  
  95. wanted it to leave the quotes alone dammit in verbatim mode, so I could
  96.  
  97. slurp in a working program, shift it over 4 spaces, and have it print out,
  98.  
  99. er, verbatim.  And presumably in a constant width font.
  100.  
  101. 
  102.  
  103. In particular, you can leave things like this verbatim in your text:
  104.  
  105. 
  106.  
  107.     Perl
  108.  
  109.     FILEHANDLE
  110.  
  111.     $variable
  112.  
  113.     function()
  114.  
  115.     manpage(3r)
  116.  
  117. 
  118.  
  119. Doubtless a few other commands or sequences will need to be added along
  120.  
  121. the way, but I've gotten along surprisingly well with just these.
  122.  
  123. 
  124.  
  125. Note that I'm not at all claiming this to be sufficient for producing a book.
  126.  
  127. I'm just trying to make an idiot-proof common source for nroff, TeX, and
  128.  
  129. other markup languages, as used for online documentation. Both pod2html
  130.  
  131. and pod2man translators exist.
  132.  
  133.