Documentation for the org-e-groff and org-e-man exporters.
authorLuis Anaya <papoanaya@hotmail.com>
Sat, 28 Jul 2012 20:36:22 +0000 (16:36 -0400)
committerLuis Anaya <papoanaya@hotmail.com>
Sat, 28 Jul 2012 20:36:22 +0000 (16:36 -0400)
org-tutorials/org-e-groff-documentation.org [new file with mode: 0644]
org-tutorials/org-e-man-documentation.org [new file with mode: 0644]

diff --git a/org-tutorials/org-e-groff-documentation.org b/org-tutorials/org-e-groff-documentation.org
new file mode 100644 (file)
index 0000000..ce72b64
--- /dev/null
@@ -0,0 +1,413 @@
+** Groff and PDF export
+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 LaT_eX
+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 macros calls needed for the 
+Memorandum Type covers. 
+*** To use this feature
+Include =(require 'org-e-groff)= in your =.emacs= file, after the
+invocation of =(org-install)=. This feature only works with the new
+=org-export= facility.
+*** Groff MM macro summary
+For the purpose of context, the following table 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-e-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. The
+        Groff supports the use of the different Memorandum Types as well
+        as Cover Pages (COVER/COVEND pairs).
+
+*** Groff export commands
+  - M-x org-e-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-e-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-e-groff-default-class= or locally by adding an option
+like =#+GROFF_CLASS: myclass= in your file. The class must be listed in
+=org-e-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     |
+| 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-e-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[2]
+   - :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. 
+                   
+
+[2] All memorandum types are defined by default. This command is useful
+for new types of covers or when a custom file is being invoked. 
+
+Example: 
+
+#+begin_src emacs-lisp
+;; org-e-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-e-groff--colored-heading (level numberedp)
+  (concat ".HL " (number-to-string level) " \"%s\"\n%s")
+)
+
+;; adds the class definition. 
+
+(add-to-list 'org-e-groff-classes
+       '("myclass" 
+         ".so myclassfile.groff"
+         (:heading org-e-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-e-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)/
+*** 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. 
+
+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:[1]
+- Encapsulated Postscript (eps)
+- Postscript (ps)
+- Groff Pic (pic)
+
+[1] 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. 
+
+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)/
+*** 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 [[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-e-groff-source-highlight= to
+    *t* in your .emacs file (i. e. =(setq org-e-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-e-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. 
+
+  - Long Tables :: Long tables are supported by =tbl=, but long table
+                   markers (T%{}%T) are not in use. This will result in
+                   a warning and a table running out of space. To solve
+                   this issue, partition the table in Org or fix the groff file
+                   to include them.  A fix is planned for a future release.
+  - 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.
+
+
+
diff --git a/org-tutorials/org-e-man-documentation.org b/org-tutorials/org-e-man-documentation.org
new file mode 100644 (file)
index 0000000..5fb59f8
--- /dev/null
@@ -0,0 +1,119 @@
+** Man Pages and PDF export
+Org mode provides the ability to export files marked with the Groff
+Man Pages (-man) set. With additional processing it can turn
+these files into PDF files that can be used for general
+distribution. 
+
+Groff is used for the generation of =man= pages. But writing those pages 
+may be an intimidating task. With this export mode, Org mode structured 
+editing and facilities are available to facilitate the creation of these
+pages. 
+*** To use this feature
+Include =(require 'org-e-man)= in your =.emacs= file, after the
+invocation for =(org-install)=.  This feature only works with the new
+=org-export= facility. 
+*** Header and sectioning structure
+There is only one type of document available to create man pages,
+therefore there are no classes. However the following customizations are available:
+- The =#+TITLE:= line is used to set the name of the command in the Man page's 
+title line.  
+- The =#+MAN_CLASS_OPTIONS:= line contains one available option:
+   - :section-id :: Defines the section id to be placed in the Man Page. 
+                    Defaults to "1". /(string)/
+*** Man export commands
+  - M-x org-e-man-export-to-man :: Converts buffer to a man page
+       the assumptions that it was Org mode syntax. For an Org file like
+       =myfile.org= the Groff file will be =myfile.man=. The file will
+       be overwritten without warning. 
+  - M-x org-e-man-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. 
+
+*** Tables in Man 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_MAN:= 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. 
+
+The Groff export will honor columns definitions placed on top of a given
+table in Org mode and propagates those definitions as =tbl= commands. 
+
+Man pages do support the use of tables, however the definition in
+/man.conf/ needs to invoke =tbl= when the =man= command is
+executed. This is to ensure that tables are rendered correctly
+*** Source highlight in Man export
+Man export supports source highlight. See /Source highlight in Groff
+export/ for details on how to configure this feature in your
+system.  
+
+One important difference is the name of the variable used to enable
+its use, the name is =org-e-man-source-highlight=. Albeit its name
+is analogous for the one used in the Groff export, the name
+indicates its used to be specific for Man pages.
+*** Embedded Groff commands for Man exports. 
+Groff commands can be exported literally by surrounding the text on a
+pair of =#+BEGIN_MAN/#+END_MAN= lines.  These are a couple of 
+commands that can be useful during export to control the output. 
+
+#+begin_src dummy
+#+BEGIN_MAN
+.bp
+#+END_MAN
+#+end_src
+
+Page break. Skips to a new page. 
+
+#+begin_src dummy
+#+BEGIN_MAN
+.DS C
+.EQ
+
+
+.EN
+.DE
+.EC
+#+END_MAN
+#+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_MAN
+.EX
+
+.EE
+#+END_MAN
+#+end_src
+
+Example start and end. Text must be placed between .EX and
+.EE. Using =#+BEGIN_EXAMPLE/#+END_EXAMPLE= or =#+begin_src dummy/#+end_src= 
+does the same with commands that are compatible on all platforms.
+*** Man export limitations
+The following items are partially or not supported during Man pages
+exports. 
+  - Images :: Images are not supported.
+  - .EX/.EQ :: These are not used on export. They are implemented using
+               .nf/.fi pairs for compatibility with legacy systems. Use
+               embedded Man Pages commands to use these. 
+  - .UR/UE and .MT/ME :: These are not used on export to ensure 
+                         support with legacy systems. Use embedded Man Pages
+                         commands to use these. 
+  - .SY/OP/YS :: These are not used on export. Use embedded Man
+                 pages commands to use these.