org-contribute.org: Add Sameer Rahmani to TINYCHANGE contributors

[worg.git] / exporters / ox-groff.org

#+TITLE: Groff and PDF export
#+AUTHOR: Luis Anaya
#+DATE: 2012-08-10
#+OPTIONS: H:2 toc:t num:nil
#+STARTUP: fold
#+CATEGORY: worg

Org mode provides the ability to export files marked with the Groff
Memorandum Macros (-mm) set. With additional processing it can turn
these files into PDF files that can be used for general
distribution. This feature is being provided as an alternative to the LaTeX
export being that not all Unix installations have TeX available while
Groff is commonly installed because it is needed for the generation of
=man= pages.

The Groff export follows the sequence of macro calls needed for the
Memorandum Type covers.

Some example org files and corresponding exported pdf files from the
author of the library can be found on [[https://www.box.com/s/578d9a22c890ddcea8bd][this page]].

* To use this feature
Include =(require 'ox-groff)= in your =.emacs= file. This feature
only works with the new =ox= facility.

* Groff MM macro summary
For the purpose of context, the following list describes some of the
macros used during export. These are built from data stored by your org
document and follows the order needed for the generation of cover
sheets.

In such order:
- AF :: Firm. It is populated with the content of the custom
        variable org-groff-organization. It has a default value of
        "Org User".
- TL :: Title. It uses the content of #+TITLE: during
        export. Subtitles are supported with the use of a custom
        option.
- AU :: Author Macro. It uses the content of #+AUTHOR: during
        export.
- AT :: Author Title. It uses a custom option to populate the title,
        otherwise it is not used.
- ND :: Date. It will use the content of #+DATE: during export. If
        the #+DATE: is not written in your org file, it will default
        to the date at the moment of export.
- MT :: Memorandum Type. It defines the structure of the document.
        Groff supports the use of the different Memorandum Types as well
        as Cover Pages (COVER/COVEND pairs).

* Groff export commands
- M-x org-groff-export-to-groff :: Converts buffer to Groff under
     the assumptions that it was Org mode syntax. For an Org file like
     =myfile.org= the Groff file will be =myfile.groff=. The file will
     be overwritten without warning.
- M-x org-groff-export-to-pdf :: Converts buffer to a PDF file under
     the assumptions that it was Org mode syntax. It uses Groff as its
     typesetter engine.

* Header and sectioning structure
By default, the Groff export uses the =internal= (.MT 0) Memorandum Type
to generate documents.

You can change this globally by setting a different value for
=org-groff-default-class= or locally by adding an option
like =#+GROFF_CLASS: myclass= in your file. The class must be listed in
=org-groff-classes=. This variables defines the attributes for a
class, unlike L_aTex, the structure in Groff is defined in the content
of the document. What this variable defines is the style of the cover
page, the type of headers and if the export will generate a Table of
Content or Letter Signature.

The following classes are defined by default:

| <l10>      | <c15>           | <l40>                                    | <l7>    | <l>     |
| class      | Memorandum Type | Description                              | type    | closing |
|------------+-----------------+------------------------------------------+---------+---------|
| internal   | MT 0            | Creates a document with a cover page having the Subject, Date, Author and Organization. | memo    | toc     |
| file       | MT 1            | Creates a document with a cover page having the Subject, Date, Author, Organization  and  MEMORANDUM FOR FILE header. | memo    | toc     |
| programmer | MT 2            | Creates a document with a cover page having the Subject, Date, Author, Organization  and PROGRAMMER's NOTES header. | memo    | toc     |
| engineer   | MT 3            | Creates a dcoument with a cover page having the Subject, Date, Author, Organization  and ENGINEER's NOTES header | memo    | toc     |
| external   | MT 4            | Creates a document with a cover page having the Subject, Date, Organization. Unlike the previous types, these will centered at the top | memo    | toc     |
| letter     | MT 5            | Creates a document with a cover page having the Subject, Author and Date. It was traditionally used for letters in the original Bell Labs troff macros. However, Groff uses a different mechanism. This is kept for compatibility purposes | memo    | sign    |
| ms         | COVER ms        | Creates a document with a cover page similar to the one used by the ms macros. | cover   | toc     |
| se_ms      | COVER se_ms     | Creates a document with a cover page similar to the one used by the se macros. | cover   | toc     |
| dummy      | ""              | Creates a document without a cover, but defines all the cover attributes. This is used to generate documents with an Abstract section | memo    | toc     |
| block      | "BL"            | Creates a blocked letter using the Groff letter macros | letter  | sign    |
| semiblock  | "SB"            | Creates a semiblocked letter using the Groff letter macros | letter  | sign    |
| fullblock  | "FB"            | Creates a full block letter using the Groff letter macros | letter  | sign    |
| simplified | "SP"            | Creates a simplified letter using the Groff letter macros | letter  | sign    |
| none       | ""              | Creates a document without any header. Used for customized documents or letters using the Groff's macros. | custom  | nothing |

This variable can be used to defined your own document types in which
different type of documents be loaded using the .COVER or .so commands.

To define a new class add a new entry to the =org-groff-class=
list. The element of the list are:

- class name :: Name of the class
- document type invocation :: It defines how the document will be
     invoked. If the document is a memorandum type, the whole .MT
     command written. If the document is a COVER, only the
     cover name is needed. If a custom file is being used, then an Groff
     include statement (.so) with the path of the custom file is used.
- document options :: This is a property list containing the document
     options. These are:
  - :type :: Document type. Defines if the header information is created
            or not. Options are "memo" for full header, "cover" for
            full header plus COVER/COVENT statement, "custom" for no
            header[1]
  - :heading :: Defines the command to invoke each of the section
                heading. Options are 'default for the MM defaults and a
                pointer to a function that will return a format string
                containing the heading command. The format string takes
                the =level= and the result of the =numberp= predicate that
                indicates if the heading is a numbered one or not.
  - :last-section :: Defines what is the last item to print. Options
                     are "toc" for table of content and "sign" for
                     signature.
  - :paragraph :: Defines the command to invoke each of the paragraph
                  commands. Options are 'default or a pointer to a
                  function that will return a format string containing
                  the paragraph formatting commands before writing the
                  paragraph.

Example:

#+begin_src emacs-lisp
;; org-groff--colored-heading is a function that will return
;; the invocation of the .HL macro. The .HL macro is a custom groff
;; macro.

(defun org-groff--colored-heading (level numberedp)
  (concat ".HL " (number-to-string level) " \"%s\"\n%s"))

;; adds the class definition.

(add-to-list 'org-groff-classes
       '("myclass"
         ".so myclassfile.groff"
         (:heading org-groff--colored-heading :type
          "memo" :last-section "toc")))
#+end_src

The =#+GROFF_CLASS_OPTIONS= option is used to add additional information
that changes the document structure or adds additional information that
gets exported.  The following options are supported:

- :firm :: overrides the Organization name stored in the
           =org-groff-organization=. /(string)/
- :author-title :: Adds the title for the author. If not available, the
                   .AT macro will not be used. /(string)/
- :hyphernate :: Enables or disables hyphernation support. /("yes"/"no")/
- :justify-right :: Enables or disables right justification /("yes"/"no")/
- :closing :: Changes the final closing from "Sincerely
              yours,". The string is used as part of a call to .FC.
              /(string)/
- :subtitle1 :: Defines a subtitle that maps to the "Charge Case"
                line. /(string)/
- :subtitle2 :: Defines a subtitle that maps to the "File Case"
                line. These two options might not be relevant for
                many users, but setting values to these variables can be
                helpful when custom covers are used.  These two
                options will be used when the .TL macro is invoked
                during export. /(string)/
- :salutation :: Defines a custom salutation. Defaults to "Tho whom it
                 may concern" /(string)/
- :confidential :: Toggles the confidential batter. /(boolean)/
- :subject :: Adds a subject line /(string)/
- :references :: Addss an "In Reference Line". The value of =#+TITLE= is
                  used to populate the reference. /(boolean)/
- :attention :: Adds an "ATTENTION:" line. /(string)/

[1] All memorandum and letter types are defined by default. This command is useful
for new types of covers or when a custom file is being invoked.

* Special Tags
The Groff exporter now features a set of tags that handles special
contents required for the inclusion of abstracts sections, and parts of
a business letter. The following special tags are in use by the
=ox-groff.el= exporter.
- FROM :: Defines the originator of a letter.
- TO :: Defines the recipient of a letter.
- ABSTRACT :: Defines the abstract part of a memo.
- NS :: Defines a notational sign at the letter. Notational signs items
        like "Copy to" or "Carbon Copy" that are placed at the end of
        the letter to indicate its disposition.
- BODY :: Defines the body part of a letter.

Special tags have several rules to follow. These are:
1. it must be the first tag of a list of tags, or a single tag,
2. it should be placed on first level headlines only,
3. items will be placed in their location and not written as part of
   the document.
Use of tags is described in detail in the following sections.

** Tags used for Letter types
Letter types use the FROM, TO, BODY and NS tags for placing content in
a document class of letter.  Letter types are the ones defined as:
block, semiblock, simplified and fullblock.

Illustrated below is how a typical letter looks like:
#+BEGIN_EXAMPLE
  * FROM :FROM:
  Joe Smith
  00 Street
  City, ST, 00000
  * TO :TO:
  Maria Rivera
  Urbanizacion Palma Lejos
  Calle 22, Bloque A, Numero 10
  Ciudad, ES, 00000
  * BODY :BODY:
  letter content
  * Copy to :NS:
  Jill Brown
#+END_EXAMPLE

- FROM :: A header with a /:FROM:/ tag contains the address of the
          originator. It needs to be
          written in free form but it should follow the
          addressing standards of the originator.
- TO :: A header with a /:TO:/ tag contains the address of the
        recipient. It needs to be written in free form but it should
- BODY :: The /:BODY:/ tag indicates the start of the letter. This is needed to
          start the content of the letter without writing the header on
          output.
- NS :: /:NS: will write the title of the header as the type of
        disposition at the end of the letter, after the signature.
        In the exaple, it will write "Copy to" Jill Brown at
        the end of the letter.

** Tags used for Memorandum Types letters
Letters that are of type "memo" also use the FROM, TO, BODY and NS tags
for placing content in a document class of letter.
Memo letter types are the ones defined as: "letter" or a custom cover.

Illustrated below is how a typical letter looks like:
#+BEGIN_EXAMPLE
  * FROM :FROM:
  initials
  location
  department
  extension
  room
  additional
  * TO :TO:
  Maria Rivera
  Urbanizacion Palma Lejos
  Calle 22, Bloque A, Numero 10
  Ciudad, ES, 00000
  * BODY :BODY:
  letter content
  * Copy to :NS:
  Jill Brown
#+END_EXAMPLE

- FROM :: A header with a /:FROM:/ tag contains the address of the
          originator. It needs to be
          written in the same order as the AU macro call. This order is
          1. Initials: Author initials
          2. Author location: Building Name
          3. Author department code
          4. Author extension
          5. Author room
          6. Additional items, like email or street address.
- TO :: A header with a /:TO:/ tag contains the address of the
        recipient. It needs to be written in free form but it should
- BODY :: The /:BODY:/ tag indicates the start of the letter. This is needed to
          start the content of the letter without writing the header on
          output.
- NS :: The /:NS:/ tag will write the title of the header as the type of
        disposition at the end of the letter, after the signature.
        In the exaple, it will write "Copy to" Jill Brown at
        the end of the letter.

The placement of items depends directly on the way the cover has been
written. Although MT 5 is the "letter" memorandum type, Groff does not
follow the same convention as Bell Labs' troff. Therefore, the use
of these document classes is usable only to custom type covers.

** Tags used for Memorandum Types documents.
Documents that are of type "memo" use the FROM and ABSTRACT
for placing content in a document class of memo
Letter types are the ones defined as: internal, external, file,
engineering, programmer or a custom cover.

Illustrated below is how a typical memo looks like:
#+BEGIN_EXAMPLE
  * FROM :FROM:
  initials
  location
  department
  extension
  room
  additional
 * TO :ABSTRACT:
  Abstract Body
 * First Header
#+END_EXAMPLE

- FROM :: A header with a /:FROM:/ tag contains the address of the
          originator. It needs to be
          written in the same order as the AU macro call. This order is
          1. Author initials
          2. Author location code or Building Name
          3. Author department number
          4. Author extension
          5. Author room
          6. Additional items, like email or street address.
- ABSTRACT :: A header with an /:ABSTRACT:/ tag contains the abstract
              The abstract will be placed in the Abstract Location,
              usually at the cover sheet, before the start of the document.

The placement of items depends directly on the way the cover has been
written and these follows the Bell Labs standards. This may or may not be
applicable for your case. As an alternative you should use the external
or letter class, which does not fully use the author information in the
cover or create your own custom cover.

However, the following alternate ordering used in headers with the FROM tag may
be more suitable to use than the one prescribed in the manual page. This
is because it does not follow the Bell Labs nomenclature.

This alternate ordering is:
1. Initials
2. Building Name or Location
3. Room
4. Extension
5. Main telephone switch number
6. Street
7. City, State, Province, Postal code
8. Email address

This ordering places the author information in the following order:

#+BEGIN_EXAMPLE
Name
BLDG ROOM
Switch Phone Number xExtension
Street
City, State, Province, Postal Code
Email Address
#+END_EXAMPLE.

Out of all these values, the only one required is the initials. The
others do not need to be written and they will not be written in the document.

* Tables in Groff export
Groff uses the =tbl= preprocessor for table exports but the Groff export
process also supports the specification of labels, captions and table
options with the use of the =#+ATTR_GROFF:= line. The following options
are available to modify table behavior.

- :divider :: Places vertical bars between the different
              columns. /(boolean)/
- :placement :: Defines where the table will be placed in the
                line. There are two possible values: center or
                left. /(symbol)/
- :boxtype :: Defines the box type. /(symbol)/ The following values are supported:
   - box :: Creates a border only. Default
   - doublebox :: Creates a border with two lines.
   - allbox :: Creates a table in which all cells are divided.
   - none :: No borders.
- :title-line :: Forces the first row to be centered bold. /(boolean)/
- :diable-caption :: Captions are placed by default. This will disable
     its creation. /(boolean)/
- :expand :: Expands the table across the width of the page.
- :long-cells :: Encloses all cells in T{ }T to allow the use of multi
                 line cells. /(boolean)/
The Groff export will honor columns definitions placed on top of a given
table in Org mode and propagates those definitions as =tbl= commands.

* Images in Groff export
Groff provides very limited support for image export and this limitation
is reflected in the export. The Groff export uses the =pic= preprocessor
and the -Tps device for image support. The only types that are supported
for export  are:[2]
- Encapsulated Postscript (eps)
- Postscript (ps)
- Groff Pic (pic)

Other types need to be converted into either of these for its use in
Groff.

Images that are linked to without description part in the line like
=[[file:img.eps]]= or =[[img.pic]]= will be inserted into the PDF output file
resulting from Groff processing. Org will use a .PSPIC (for eps and ps)
or PS/PE (for pic) macro to insert the image during export. If you have specified a
caption or label, it will be included in the export through a call to
the .FG macro. You can use an =#+ATTR_GROFF:= line to specify other
options, but these only affect postscript types ones (eps and ps). This
is because pic images contain its definition in the in the pic file.
The following options are available:

- :position :: Positions the image in the line. There are three options:
               left, right and center /(symbol)/
- :width :: Defines the width of the image in Groff units. For
            example :width 1.0i or :width 2.0c  /(symbol)/
- :heigth :: Defines the hight of the image in Groff units. For
             example :heigth 1.0i or :height 2.0c.  /(symbol)/

[2] Although the MPIMG macro is available in the -mwww  set, it
conflicts with the definition of list items (LI) in the -mm one. At
the end, these macros convert images to EPS.

* Footnotes and References
The Groff export uses the same footnote mechanism to identify footnotes
and bibliographic references. Adding a =\[1\]= or a =\[fn:123\]= marker with its
appropriate reference will create a footnote at the end of the page.
However adding a reference with a /"rl"/ tag, creates a Reference to the
end of the page.

For example:
#+BEGIN_EXAMPLE
This is a refered text\[fn:rl1\].
\[fn:rl1\] Author, Title (c) 2010.
#+END_EXAMPLE

Will place "Author, Title (c) 2010" in the reference list in the Table
of Contents.

Footnotes markers with the same tag will refer to the same reference in
the list.

* Special Characters
Special character substitution can be enabled if there is a list
specified in the =org-groff-special-char= variable. This variable
consists of a list of cons pairs in which the first value is the item to
substitute and the second value is the value to be substituted with. By
default it will substitute (c) for copyright notice, (tm) for trademark
and (rg) for registered mark.

Character substitution can be disabled by setting this variable to *nil*.

* Source highlight in Groff export
There are no packages or processors for syntax highlight in
Groff. However this feature is available for Groff export with the use
of GNU's source highlight
([[http://www.gnu.org/software/src-highlite/]]). The steps needed to use
this feature are as follows:

1. Install source highlight according to the instruction in the
   distribution. Source highlight requires the Boost [[http://www.boost.org][www.boost.org]]
   libraries installed and available as well. See their respective
   documentation for details.
2. Make sure that the source highlight binary is available in your
   PATH.
3. Download the groff language files from
   [[http://www.github.com/papoanaya/emacs_utils/source-highlight]]. Place
   them in the source-highlight configuration directory, usually under
   =share/source-highlight=. Note that the outlang.map will replace the
   one in the configuration directory. If you have custom outlang.map
   entries, they have to be merged with the ones from the Groff
   language files.
4. Set the custom variable =org-groff-source-highlight= to
   *t* in your .emacs file (i. e. =(setq org-groff-source-highlight t)=)

When the #+begin_src line is used with a supported language, the Groff
export process will submit the block to source-highlight for
processing.

For example:
#+begin_example
   #+begin_src emacs-lisp
     (message "Hello World")
   #+end_src
#+end_example

The resultant text will have Groff formatted text that corresponds to
the highlighted code. This code will be surrounded with a Display Static pair
(DS/DE) and finishes with a call to the EX macro. EX will add an
/Exhibit/ caption at the bottom of the highlighted source.

The following languages are supported by default:
| <l20>                | <l20>                |
| begin_src tag        | source highlight language |
|----------------------+----------------------|
| emacs-lisp           | lisp                 |
| lisp                 | lisp                 |
| clojure              | lisp                 |
| scheme               | scheme               |
| c                    | c                    |
| cc                   | cpp                  |
| csharp               | csharp               |
| d                    | d                    |
| fortran              | fortran              |
| cobol                | cobol                |
| pascal               | pascal               |
| ada                  | ada                  |
| asm                  | asm                  |
| perl                 | perl                 |
| cperl                | perl                 |
| python               | python               |
| ruby                 | ruby                 |
| tcl                  | tcl                  |
| lua                  | lua                  |
| javascript           | javascript           |
| tex                  | latex                |
| shell-script         | sh                   |
| awk                  | awk                  |
| diff                 | diff                 |
| m4                   | m4                   |
| ocaml                | caml                 |
| caml                 | caml                 |
| sql                  | sql                  |
| sqlite               | sql                  |
| html                 | html                 |
| css                  | css                  |
| xml                  | xml                  |
| bat                  | bat                  |
| bison                | bison                |
| opa                  | opa                  |
| php                  | php                  |
| postscript           | postscript           |
| prolog               | prolog               |
| properties           | properties           |
| makefile             | makefile             |
| tml                  | tml                  |
| vala                 | vala                 |
| vbscript             | vbscript             |
| xorg                 | xorg                 |

New languages can be added to source highlight and made available for
export by adding entries to the list stored in the
=org-groff-source-highlight-langs= variable. The format for each entry
consists on a symbol and a string. The symbol corresponds to the
begin_src tag and the string to the corresponding language entry
available in source highlight. An example  of an entry is:
#+begin_src emacs-lisp
   (sqlite "sql")
#+end_src

If a language is not defined, then the Groff export process will default
to write the code in Constant Width font.

* Embedded Groff
Groff commands can be exported literally by surrounding the text on a
pair of #+BEGIN_GROFF/#+END_GROFF lines.  These are a couple of
commands that can be useful during export to control the output.

#+begin_src dummy
#+BEGIN_GROFF
.SK
#+END_GROFF
#+end_src

Page break. Skips to a new page.

#+begin_src dummy
#+BEGIN_GROFF
.DS C
.EQ


.EN
.DE
.EC
#+END_GROFF
#+end_src

EQN escape. This is used to add equations in your exported document. The
Groff export uses the =eqn= processor to add them in your output. EQN
statements must be placed between .EQ and .EN.

#+begin_src dummy
#+BEGIN_GROFF
.AS

.AE
.MT 0
#+END_GROFF
#+end_src

Used with the dummy document class, it can be used to add an abstract block to
any of the memorandum type. The internal type is presented for
reference. Absract text must be placed betwen .AS and .AE.

* Known Limitations
The following limitations are known at the time of release. They will be
looked at and addressed  in subsequent releases if they are technically
solvable.

- Images :: Image support is limited to PIC, PS and EPS.
- Links :: There is no support for document linking or grefer. Most
           links will be just written. The only exception are for
           supported image and files with a .groff extension. The
           former will be embedded in the exported file, the later
           will be included through the use of a .so command.
- Abstracts :: Abstract support is only available through the use of
               embedded Groff.
- Equations :: Equations support is only available through the use of
               embedded Groff.
- Alternate Macro Set :: There are plans to create export for MOM
     macros. No plans for the MS set unless there is enough
     interest. The reason is that MOM seems to be the up and coming
     substitute for MM and its similarities with LaT_eX makes it a
     very attractive alternative to MM. It also allows the use of the
     macros available in the WWW set.
- Gnuplot :: Gnuplot plots can be included if the following conditions
             are met:
    1. Output type  must be set to =gpic= (GnuPIC). Using Lat_eX EPS
       will result in an incomplete graph.
    2. For images generated directly from an Org mode table will have
       to be included afterwards after its generation.  For example:
       #+BEGIN_EXAMPLE
         #+PLOT: title "X" ... set:"term gpic" "set:output 'table.pic'"
         | a | b | c |
         | 1 | 2 | 3 |
         [[file:table.pic]]
       #+END_EXAMPLE
    3. While using Org Babel, gpic output specification needs to be
       stated. Otherwise, the image will not be included on export.
       #+BEGIN_EXAMPLE
         #+begin_src gnuplot :file salida.pic
           set term gpic
           plot sin(x)
         #+end_src
       #+END_EXAMPLE
- PlantUML :: Plantuml is supported but the output type must be
              EPS. This is done by using /.eps/ as the file suffix.
  #+BEGIN_EXAMPLE
     #+begin_src plantuml :file x.eps
        [A] --> [B]
     #+end_src
  #+END_EXAMPLE
- Other Babel Graphics :: Other babel graphics should be supported if
     either PS, EPS or GnuPIC are used as their output format.