Eases the generation of (proper) man pages
MIT License
Wrapper around standards compliant Manpage tags
This library is a lightweight wrapper around the Manpage file format. It is meant to facilitate the generation of compliant tags, and aims to aid in the replacement of incredibly non-standard Markdown-to-Manpage converters.
var Man = require('man-api');
var fs = require('fs');
var out = fs.createWriteStream('foobar.3');
var man = new Man();
man.on('data', function (str) {
out.write(str);
});
// or
var man = new Man(function (str) {
out.write(str);
});
// all methods are chainable.
man.header('foobar', 3).name('foobar', 'foo into the bar');
// using .header() and .name() now allow your command to appear in the
// `whatis foobar` database.
man.section('Other').write('This is some other text.').bold('This is bold');
Man([fn])
Constructor; creates a new manpage instance. Returns objects are instanceof events.EventEmitter
, and only emit data
events.
fn
: Optional function that receives strings upon calling methods. Can beSee above example.
.write(...)
Writes text to the manpage.
...
: Arguments to be .toString()
coerced and then concatenated with aThis method appends a newline to the end of the string. It does not add any tags nor does it abide by the 6 argument rule.
The method is safe to use within designated paragraph (sub)sections, but does not perform any intelligent argument quoting - only standard textual replacement.
man.write('There are', 3, 'piggies.');
.header([title, [section, [date, [source, [manual]]]]])
Writes the manpage header. This is required for all man-pages and should be the first method called.
title
: the title of your manpage. (default: Untitled)section
: which section your manpagesections
indate
: the date the manpage was created. (default: new Date()
)
Date
object, unix timestamp (Number
), or a string.formatDate()
.source
: the source of the manpage; this has nothing to do with sourcesource
parameter. (default: Linux)manual
: the overarching manual this manpage belongs to. Checkmanual
parameter.This must be the first call in your manpage after any comments.
man.header('fwrite', 3, new Date(), 'Linux', 'Linux Programmer\'s Reference');
/*
.TH FWRITE 3 "August 28, 2015" Linux "Linux Programmer's Reference"
*/
.section(name)
Starts a new section.
name
: the name of the sectionAutomatically coverts name
to upper-case.
Note: You should section names that correspond to the standard list (see Sections within a manual page).
man.section('Synopsis'); //-> .SH SYNOPSIS
.subSection(name)
Starts a new sub-section.
name
: the name of the sub-sectionNote: There are no standard sub-sections; therefore,
name
is not automatically converted to upper-case.
Headings capitalize the first word in heading, but otherwise use lower case, except where English usage (e.g., proper nouns) or programming language requirements (e.g., identifier names) dictate otherwise.
Due to this, we do no formatting here.
man.subSection('Portability'); //-> .SS Portability
.name(name, description)
Starts the NAME section with the name of the function and the whatis
description. This section is required to be standard, and should be
called second, right after .header()
.
name
: the name of the function/command the man page is aboutdescription
: the whatis
description to useKeep descriptions nice and concise, like a GitHub repository description.
man.name('some_function', 'performs some operation');
/*
.SH NAME
some_function \- performs some operation
*/
.paragraph()
Starts a new paragraph.
man.paragraph(); //-> .PP
.bold(str)
.italic(str)
.small(str)
Writes some bold/italic/small text.
.small()
is not very widely supported, and is historically used for acronyms. Keep this in mind before using it.
str
: the string to writeThese are font tags, and to comply with portability standards we break str
up by spaces/new-lines and clump them into 6-word commands as old
implementations only supported that many. Keep this in mind if whitespace is
an issue.
Note that font tags do not cause a line break. Switching from regular ("roman")
font to bold/italic/small does require a new tag but doesn't cause a new line to
form. To do this, you need to use .paragraph()
(.PP
).
man.bold('hello, world!'); //-> .B hello, world!
man.italic('hello, world!'); //-> .I hello, world!
man.small('hello, world!'); //-> .SM hello, world!
.boldItalic(str)
.boldNormal(str)
.italicBold(str)
.italicNormal(str)
.normalBold(str)
.normalItalic(str)
.smallBold(str)
Write alternating font words (see notes below).
str
: the string to writeThese methods do not combine two styles. Instead, they alternate between two styles. The alternation occurs at a space character, and the resulting text does not include a space!
The naming convention used can be read X-to-Y (e.g. bold-to-italic). This
means .boldItalic
will start with bold and alternate to italic, whereas
.italicBold
will start with italics and alternate to bold.
man.boldItalic("hello there chap"); //-> .BI hello there chap
.indentBegin([n])
.indentEnd()
Begins/ends an indentation.
n
: the number of columns to indent. If not supplied, will increase current+11-4
)Indentation amount is relative to current indentation.
Ending an indentation will set indentation level back to previous value.
man.write('What does the program say?');
man.indentBegin(5).bold('Hello, world!').indentEnd();
/*
What does the program say?
.RS 5
.B Hello, world!
.RE
*/
.indent(n, str)
Writes some indented text.
n
: the number of columns to indentstr
: the string to indentThis is a simple wrapper around .indentBegin(n).write(str).indentEnd()
.
man.write('Hello!');
man.indent(5, "This is indented!");
/*
Hello!
.RS 5
This is indented!
.RE
*/
.paragraphHanging(n)
Starts a paragraph with a hanging indent (first line starts at col +0,
subsequent lines start at col +n
).
n
: the number of columns to indent byman.paragraphHanging(5); //-> .HP 5
.paragraphIndented(n, [tag])
Starts a new indented paragraph with an optional starting "tag".
n
: the number of columns to indenttag
: if specified, starts preceeds the paragraph with a tag (or textualman.paragraphIndented(4, '>'); //-> .IP > 4
.writeRaw(...)
This is an internal method and may not pertain to your use-case
Writes some raw text to the output.
...
: the arguments to concatenate using a space, and then writeDoes not perform textual replacements.
man.writeRaw('foo', 1234, true); //-> foo 1234 true
.put(tag, ...)
This is an internal method and may not pertain to your use-case
Writes a tag and some arguments.
tag
: the tag to write (do not prepend .
)...
: arguments to pass to formatArgument()
and then writeRaw()
Formats each argument using .formatArgument()
.
man.put('B', 'foobar', 3, true); //-> .B foobar 3 true
.formatDate([date])
This is an internal method and may not pertain to your use-case
Formats a date to a Month DD, YYYY
format.
date
: A valid date (see notes below). If not passed, new Date()
is passed.Can be passed a string (which is returned verbatim), a number (which is treated
as a Unix timestamp), or a
Date
object.
Uses UTC offsets.
man.formatDate() //-> August 28, 2015
.formatArgument(str)
This is an internal method and may not pertain to your use-case
Formats a string as a single manpage tag argument. If the string has spaces, or
has a .length === 0
, then it wraps it in double-quotes. Also performs various
textual replacements to keep things more standard (i.e. TM symbol
replacement, etc).
man.formatArgument('foo bar.'); //-> "foo bar\."
Licensed under the MIT License. You can find a copy of it in LICENSE.