ox-groff.org 27 KB

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

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.

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


  * 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
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:


  * 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
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
  • Initials: Author initials
  • Author location: Building Name
  • Author department code
  • Author extension
  • Author room
  • 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:

    
      * FROM :FROM:
      initials
      location
      department
      extension
      room
      additional
     * TO :ABSTRACT:
      Abstract Body
     * First Header
    
    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
  • Author initials
  • Author location code or Building Name
  • Author department number
  • Author extension
  • Author room
  • 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:

    
    Name
    BLDG ROOM
    Switch Phone Number xExtension
    Street
    City, State, Province, Postal Code
    Email Address
    

    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 =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:

    
    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 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
    2. distribution. Source highlight requires the Boost [[www.boost.org]] libraries installed and available as well. See their respective documentation for details.
    3. Make sure that the source highlight binary is available in your
    4. PATH.
    5. Download the groff language files from
    6. [[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.
    7. Set the custom variable org-groff-source-highlight to
    8. *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.

    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

    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.

    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.

    <p>
    .SK
    </p>
    
    

    Page break. Skips to a new page.

    <p>
    .DS C
    </p>
    <p>
    .EQ
    </p>
    
    
    <p>
    .EN
    </p>
    <p>
    .DE
    </p>
    <p>
    .EC
    </p>
    
    

    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.

    <p>
    .AS
    </p>
    
    <p>
    .AE
    </p>
    <p>
    .MT 0
    </p>
    
    

    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:
  • Output type must be set to gpic (GnuPIC). Using Lat_eX EPS
  • will result in an incomplete graph.
  • 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
  • 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.
    he following languages are supported by default
    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