No description, website, or topics provided.
Switch branches/tags
Nothing to show
Clone or download
Latest commit 122eb1e Sep 13, 2017
Permalink
Failed to load latest commit information.
groffonts Revert to CL .eval writing to stdout (in addition to *troff*). Aug 19, 2017
.gitignore pca-t2p-man-lua.tmac no longer needed; contents rolled into troff2pag… Aug 29, 2017
.groffontrc ... May 2, 2015
README.adoc ... Sep 13, 2017
hp1320.tmac ... Apr 8, 2015
otfgroff.adoc ... Sep 13, 2017
pca-also-man.tmac ... Aug 9, 2016
pca-blm.tmac ... Sep 27, 2015
pca-dc.tmac ... Oct 4, 2015
pca-eval-js.tmac ... Feb 13, 2016
pca-eval-lisp.tmac Revert to CL .eval writing to stdout (in addition to *troff*). Aug 19, 2017
pca-eval-lua.tmac Revert to CL .eval writing to stdout (in addition to *troff*). Aug 19, 2017
pca-eval.tmac Added Lua as an .eval language, alongside CL and JS. CL .eval writes to Aug 2, 2017
pca-img.tmac ... Oct 4, 2015
pca-ix.tmac ... Feb 16, 2016
pca-lsm.tmac ... Sep 27, 2015
pca-so.tmac Split pca-t2p-so.tmac off from pca-so.tmac. Aug 25, 2017
pca-t2p-eval-lisp.tmac Revert to CL .eval writing to stdout (in addition to *troff*). Aug 19, 2017
pca-t2p-eval-lua.tmac Revert to CL .eval writing to stdout (in addition to *troff*). Aug 19, 2017
pca-t2p-ix-lisp.tmac Revert to CL .eval writing to stdout (in addition to *troff*). Aug 19, 2017
pca-t2p-ix-lua.tmac Revert to CL .eval writing to stdout (in addition to *troff*). Aug 19, 2017
pca-t2p-ix.tmac Revert to CL .eval writing to stdout (in addition to *troff*). Aug 19, 2017
pca-t2p-man-lisp.tmac Split pca-t2p-man-{lua,lisp}.tmac from pca-t2p-man.tmac. Aug 29, 2017
pca-t2p-man.tmac Split pca-t2p-man-{lua,lisp}.tmac from pca-t2p-man.tmac. Aug 29, 2017
pca-t2p-so.tmac Split pca-t2p-so.tmac off from pca-so.tmac. Aug 25, 2017
pca-t2p-toc-lisp.tmac Revert to CL .eval writing to stdout (in addition to *troff*). Aug 19, 2017
pca-t2p-toc-lua.tmac Revert to CL .eval writing to stdout (in addition to *troff*). Aug 19, 2017
pca-t2p-toc.tmac Revert to CL .eval writing to stdout (in addition to *troff*). Aug 19, 2017
pca-tag.tmac .TAG creates ids with prefix TAG: rather than TAG_. Feb 16, 2016
pca-toc.tmac pca-t2p-man-lua.tmac no longer needed; contents rolled into troff2pag… Aug 29, 2017
pca-verb.tmac ... Sep 27, 2015
pca.tmac ... Aug 26, 2017

README.adoc

mpca

Introduction

The venerable typesetter groff is ubiquitous. It lets you create documents in plain text with your favorite text editor. However, there are other factors that chip away at these core advantages.

To wit: Source documents look very busy, even when one isn’t using any special features, most notably because markup is required for paragraph separation. Basic features like cross references, table of contents and index are not immediately available. Writing even relatively simple macros can be forbidding.

The mpca macro package is an extension of the standard ms package that lets you write clean source documents, and provides workable defaults for basic needs that can be extended or overridden as needed.

mpca is an unobtrusive extension to ms. You only need to use features as you need them.

mpca may stand for “Macros for the Prevention of Cruelty to Authors”.

Installation

Get the mpca package from GitHub:

git clone https://github.com/ds26gte/mpca

The directory mpca contains the macro file pca.tmac and several subfiles pca-*.tmac. Copy all of them to a directory in your GROFF_TMAC_PATH. (If you’re just experimenting, you could just copy them to your home directory.)

troff2page

The macro files with prefix pca-t2p- are automatically loaded when the typesetter is troff2page rather than groff proper. They provide troff2page-specific alterations to the mpca macros that make the translation efficient and/or HTML-relevant. E.g., the ToC, cross-references, and index are converted into hyperlinks.

Tip
If you don’t intend to use troff2page to convert your documents to HTML, you may ignore the pca-t2p-*.tmac macro files. I.e., you don’t need to put them in GROFF_TMAC_PATH.

Invocation

To use mpca, you can simply source pca.tmac in your document:

.mso pca.tmac

Alternatively, you can use the groff command-line option -m, e.g.,

% groff -mpca doc.ms > doc.ps

Other groff options can be added as usual.

Let’s now go into the mpca features that you can use in your document.

Init file

mpca will source a macro file .groffrc if it can find it in your GROFF_TMAC_PATH or home directory.

~/.groffrc is a good place to put minor customizations that are relevant only to your system. (I find I need to slightly tweak the page-offset register (PO) to suit my printer — this tweak needn’t or shouldn’t be enshrined in my document.)

Blank lines

Stop using .PP and .LP (unless you really want to)! Simply separate your paragraphs by a blank line.

mpca takes care to indent paragraphs only when needed. Thus, the first paragraph after a sectioning macro is not indented. Also blank lines within code displays don’t cause indentation.

Verbatim display

Use .EX to start and .EE to end a verbatim display, typically used for program listings. Inside the listing, you can use the backslash (\) without triggering a troff escape. The only restriction is you can’t use a period (.) in the first column of any line in the display. E.g.,

.EX
function fact(n)
  if n == 0 then return 1
  else return n*fact(n - 1)
  end
end
.EE

You can turn the troff escape on and again off within your display with calls to .ec and .eo respectively. The lines containing these calls must of course have . in the first column and will not be displayed.

Image

The .IMG macro can be used to insert image files. The syntax follows that of the .IMG macro in the www.tmac, but (a) isn’t restricted to HTML output. E.g.,

.IMG t2p.png

sources the image t2p.png. You can specify the image alignment with an optional first argument: -L for left, -R for right, -C for centered. If no alignment is specified, -C is assumed.

.IMG relies on the external programs convert (from ImageMagick) and inkscape. (inkscape is needed for SVG images.)

Page cross-references

The .TAG macro manages cross-references. E.g.,

.TAG sec_grofflua

associates the label TAG:sec_grofflua with the number of the current page. The string \*[TAG:sec_grofflua] is defined to typeset as that page number. Thus, in a hand-crafted table of contents, you could use

Extending groff using Lua, \*[TAG:sec_grofflua]

.TAG takes an optional second argument. The label is then associated with the text of the second argument instead of the current page number.

Note
mpca’s .TAG overrides a similarly named macro in the file www.tmac in the groff distribution, which only allows backward references.
Important
.TAG requires two runs of groff. Please see the section on aux files.

Table of contents

The .TOC macro inserts a table of contents (ToC). Add your own header (e.g., “Contents”, or “Table of Contents”).

.TOC does not require you to modify how you use your sectioning macros — it automatically draws its information from the distribution of the .NH and .SH macros within your document. It is thus a solution to the following statement from the groff manual:

Altering the ‘NH’ macro to automatically build the table of contents is perhaps initially more difficult, but would save a great deal of time in the long run if you use ‘ms’ regularly.

ToC entries are generated for the usual ms section headers (.SH, .NH). The depth of the ToC is governed by the number register GROWPS: Only those .SH/.NH headers at a level less than or equal to GROWPS will go into the ToC.

Index

The .IX macro is used to generate index entries:

.IX item to be indexed

marks the text “item to be indexed” as an indexable item. The sorted index made from these entries can be sourced into the input document via

.so \*[AUXF].ind

Adding a section header on top is up to you.

The sorted index is constructed using the external program makeindex. makeindex is included in TeX distributions, but you can also obtain it as a standalone package.

The syntax for .IX calls is essentially the same as for LaTeX, except that in groff we use

.IX item

where in LaTeX one would use

\index{item}

The metacharacters @, !, ", and | can be used to respectively specify

  1. alternate alphabetization,

  2. subitems,

  3. literal metacharacters, and

  4. encapsulation of the page number.

E.g.,

.IX m@-m, groff option

identifies an index entry for “-m, groff option” but alphabetizes it as though it were “m” rather than something that starts with a hyphen.

For full details on the other metacharacters, consult the makeindex documentation.

Eval

The macro .eval allows you to insert Common Lisp, JavaScript, or Lua code in your document to guide its transformation via groff. In other words, it lets you you use Lua, CL, or JS to extend groff instead of relying purely on groff macros. We will first describe the Lua version of .eval.

Lua

.eval does only one thing: It allows you to place arbitrary Lisp code until the following .endeval, and the text written to standard output by this Lua code is substituted for the .eval …​ .endeval. The usefulness of this tactic will be apparent from an example. Consider the following document, tau.ms:

The ratio of the circumference of a circle to
its radius is \(*t \(~=
.eval
-- following prints tau, because cos(tau/2) = -1
io.write(2*math.acos(-1), '.\n')
.endeval

Run it through mpca:

groff -z -U -mpca tau.ms

The -z avoids generating ouput, because we’re not ready for it yet. The -U runs groff in “unsafe” mode, i.e., it allows the writing of aux files.

You will find that the groff call produces the following message:

Rerun groff with -U

Call groff again as folows:

groff -U -mpca tau.ms > tau.ps

tau.ps will now look like:

The ratio of the circumference of a circle to its radius is τ ≈ 6.2831855.

Here’s how it works. The first groff call produces a Lua file \*[AUXF].lua that collects all the .eval code in the document. The second groff call invokes Lua to create an aux file for each .eval and sources it back into the document.

It should be clear that Lua code via .eval can serve as a very powerful second extension language for groff. For a more substantial example of .eval’s use see the troff2page manual.

Common Lisp

To use Common Lisp inside .eval, set

.ds pca-eval-lang lisp

in your document before the first use of .eval. Thus, the tau.ms file, translated to Common Lisp, will now read:

.ds pca-eval-lang lisp
The ratio of the circumference of a circle to
its radius is \(*t \(~=
.eval
;following prints tau, because cos(tau/2) = -1
(princ (* 2 (acos -1)))
(princ ".")
(terpri)
.endeval

JavaScript

To use JavaScript inside .eval, set

.ds pca-eval-lang js

in your document before the first use of .eval. Thus, the tau.ms file, translated to JavaScript, will now read:

.ds pca-eval-lang js
The ratio of the circumference of a circle to
its radius is \(*t \(~=
.eval
// following prints tau, because cos(tau/2) = -1
troff.write('' + 2*Math.acos(-1));
troff.write('.\n');
.endeval
Note
For the JavaScript .eval, we write to the stream troff rather than to standard output.

Aux files

mpca uses auxiliary (aux) files to implement its cross-referencing, ToC, indexing, and eval features.

The troff string \*[AUXF] is used to construct the names of these auxiliary files. By default this is quietly set to .trofftemp. You can change it to something else (provided it satisfies file-naming conventions) in your document before the first use of any macros that use or write aux files.

Aux files are created in one run of groff and slurped back in during a second run. Thus groff needs to be run twice for the defined feature to take effect. Furthermore, the first run of groff must be run in “unsafe” mode (groff option -U) as groff won’t create external files in “safe” mode.

Using only some of mpca’s features

Tip
You may ignore this section if you don’t mind loading all of the mpca features.

You may pick and choose individual features of mpca without committing to the rest of it. To do this source one or more of the following macro files: pca-img.tmac (for images), pca-tag.tmac (cross-references), pca-toc.tmac (ToC), pca-ix.tmac (index), and pca-eval.tmac (eval). E.g.,

.mso pca-eval.tmac

If the feature uses aux files, you will need to run groff twice, once in unsafe mode, as described in the section on aux files.

Adding OpenType Fonts to groff

For tips on this, see otfgroff.adoc.