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

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