metalsmith-groff

This plugin for Metalsmith is aimed at generating documents written for groff. It has very few Javascript dependencies, but expects groff to be correctly installed on the system.

Usage

If using the CLI for Metalsmith, metalsmith-groff can be used like any other plugin by including it in metalsmith.json.

{
  "plugins": {
    "metalsmith-groff": {}
  }
}

In Metalscript's JavaScript API, metalsmith-groff can be used like any other plugin by attaching it to the function invocation chain on the Metalscript object.

const groff = require('metalsmith-groff')

require('metalsmith')(__dirname)
  .use(groff())
  .build()

If metalsmith-groff is used as above without any argument, it will handle any file ending with .ms, .me, .mm or .mom and call groff with the eponymous macro to build a PDF document. The original file is dropped and replaced by the produced PDF one. To extend this default behaviour, it is possible to provide options as a simple objet.

Options

Here are the options handled by the plugin. A good share of them is used to configure the call to groff, so reading groff manual will provide additional and useful information.

• device is the groff output device to be used. Default is pdf, and other common devices provided with groff are html or ps.

• encoding sets the input encoding. It is the -K option of groff and defaults to utf8.

• macroPackages is an array of macros to use. By default, the plugin tries to choose a classical macro package using the file extension.

• macroPaths is an array of additional paths to search for macros. The default value is empty, see man groff_tmac for further explanation about the search sequence.

• preprocessors is an array of preprocessors to be used by groff. Common preprocessors are tbl, pic or soelim. It is empty by default.

• pattern is the matcher used to determine the files to be transformed. It is used with minimatch. The default value (**/*.@(me|mm|ms|mom)) matches all files ending with .ms, .me, .mm or .mom at any depth.

• The source file is dropped if source is false (the default behaviour), but remains in the tree along the translated document if true.