Groff and PDF export

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

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).

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.

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:

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:

;; 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")))

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.

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.

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.

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.

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:

This is a refered text\[fn:rl1\].
\[fn:rl1\] Author, Title (c) 2010.

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 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.

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 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_src emacs-lisp
  (message "Hello World")
#+end_src

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:

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:

(sqlite "sql")

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

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_GROFF
.SK
#+END_GROFF

Page break. Skips to a new page.

#+BEGIN_GROFF
.DS C
.EQ


.EN
.DE
.EC
#+END_GROFF

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_GROFF
.AS

.AE
.MT 0
#+END_GROFF

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.

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:

   #+PLOT: title "X" ... set:"term gpic" "set:output 'table.pic'"
   | a | b | c |
   | 1 | 2 | 3 |
   [[file:table.pic]]
   

3. While using Org Babel, gpic output specification needs to be stated. Otherwise, the image will not be included on export.

   #+begin_src gnuplot :file salida.pic
     set term gpic
     plot sin(x)
   #+end_src
   

PlantUML

Plantuml is supported but the output type must be EPS. This is done by using .eps as the file suffix.

#+begin_src plantuml :file x.eps
   [A] --> [B]
#+end_src

Other Babel Graphics

Other babel graphics should be supported if either PS, EPS or GnuPIC are used as their output format.