org-tutorials/org-e-man-documentation.org

   1 ** Man Pages and PDF export
   2 Org mode provides the ability to export files marked with the Groff
   3 Man Pages (-man) set. With additional processing it can turn
   4 these files into PDF files that can be used for general
   5 distribution.
   6
   7 Groff is used for the generation of =man= pages. But writing those pages
   8 may be an intimidating task. With this export mode, Org mode structured
   9 editing and facilities are available to facilitate the creation of these
  10 pages.
  11 *** To use this feature
  12 Include =(require 'org-e-man)= in your =.emacs= file, after the
  13 invocation for =(org-install)=.  This feature only works with the new
  14 =org-export= facility.
  15 *** Header and sectioning structure
  16 There is only one type of document available to create man pages,
  17 therefore there are no classes. However the following customizations are available:
  18 - The =#+TITLE:= line is used to set the name of the command in the Man page's
  19 title line.
  20 - The =#+MAN_CLASS_OPTIONS:= line contains one available option:
  21    - :section-id :: Defines the section id to be placed in the Man Page.
  22                     Defaults to "1". /(string)/
  23 *** Man export commands
  24   - M-x org-e-man-export-to-man :: Converts buffer to a man page
  25        the assumptions that it was Org mode syntax. For an Org file like
  26        =myfile.org= the Groff file will be =myfile.man=. The file will
  27        be overwritten without warning.
  28   - M-x org-e-man-export-to-pdf :: Converts buffer to a PDF file under
  29        the assumptions that it was Org mode syntax. It uses Groff as its
  30        typesetter engine.
  31
  32 *** Tables in Man export
  33 Groff uses the =tbl= preprocessor for table exports but the Groff export
  34 process also supports the specification of labels, captions and table
  35 options with the use of the =#+ATTR_MAN:= line. The following options
  36 are available to modify table behavior.
  37
  38 - :divider :: Places vertical bars between the different
  39               columns. /(boolean)/
  40 - :placement :: Defines where the table will be placed in the
  41                 line. There are two possible values: center or
  42                 left. /(symbol)/
  43 - :boxtype :: Defines the box type. /(symbol)/ The following values are supported:
  44    - box :: Creates a border only. Default
  45    - doublebox :: Creates a border with two lines.
  46    - allbox :: Creates a table in which all cells are divided.
  47    - none :: No borders.
  48 - :title-line :: Forces the first row to be centered bold. /(boolean)/
  49 - :diable-caption :: Captions are placed by default. This will disable
  50      its creation. /(boolean)/
  51 - :expand :: Expands the table across the width of the page.
  52
  53 The Groff export will honor columns definitions placed on top of a given
  54 table in Org mode and propagates those definitions as =tbl= commands.
  55
  56 Man pages do support the use of tables, however the definition in
  57 /man.conf/ needs to invoke =tbl= when the =man= command is
  58 executed. This is to ensure that tables are rendered correctly
  59 *** Source highlight in Man export
  60 Man export supports source highlight. See /Source highlight in Groff
  61 export/ for details on how to configure this feature in your
  62 system.
  63
  64 One important difference is the name of the variable used to enable
  65 its use, the name is =org-e-man-source-highlight=. Albeit its name
  66 is analogous for the one used in the Groff export, the name
  67 indicates its used to be specific for Man pages.
  68 *** Embedded Groff commands for Man exports.
  69 Groff commands can be exported literally by surrounding the text on a
  70 pair of =#+BEGIN_MAN/#+END_MAN= lines.  These are a couple of
  71 commands that can be useful during export to control the output.
  72
  73 #+begin_src dummy
  74 #+BEGIN_MAN
  75 .bp
  76 #+END_MAN
  77 #+end_src
  78
  79 Page break. Skips to a new page.
  80
  81 #+begin_src dummy
  82 #+BEGIN_MAN
  83 .DS C
  84 .EQ
  85
  86
  87 .EN
  88 .DE
  89 .EC
  90 #+END_MAN
  91 #+end_src
  92
  93 EQN escape. This is used to add equations in your exported document. The
  94 Groff export uses the =eqn= processor to add them in your output. EQN
  95 statements must be placed between .EQ and .EN.
  96
  97 #+begin_src dummy
  98 #+BEGIN_MAN
  99 .EX
 100
 101 .EE
 102 #+END_MAN
 103 #+end_src
 104
 105 Example start and end. Text must be placed between .EX and
 106 .EE. Using =#+BEGIN_EXAMPLE/#+END_EXAMPLE= or =#+begin_src dummy/#+end_src=
 107 does the same with commands that are compatible on all platforms.
 108 *** Man export limitations
 109 The following items are partially or not supported during Man pages
 110 exports.
 111   - Images :: Images are not supported.
 112   - .EX/.EQ :: These are not used on export. They are implemented using
 113                .nf/.fi pairs for compatibility with legacy systems. Use
 114                embedded Man Pages commands to use these.
 115   - .UR/UE and .MT/ME :: These are not used on export to ensure
 116                          support with legacy systems. Use embedded Man Pages
 117                          commands to use these.
 118   - .SY/OP/YS :: These are not used on export. Use embedded Man
 119                  pages commands to use these.