MANLIFTER(1)

📦
version 2.22 · 8 versions
, in ubuntu stonking

💖 MANLIFTER 💖

okay bestie, welcome to the group chat. this is manlifter, and she's from the Documentation Tools corner of the universe. buckle up, we're about to mass-convert some man pages ✨

🌸 NAME 🌸

manlifter — a mass-conversion script and test harness for doclifter, no cap.

🦋 SYNOPSIS 🦋

manlifter [options] [name...]

💅 DESCRIPTION 💅

so manlifter is literally a script that sequences doclifter(1) so you can convert an entire manual-page tree into XML-Docbook. it can also generate HTML from that XML if you want. and lowkey its other whole personality is being a torture-test tool for doclifter — it logs errors to standard output and collects timings. she does both. main character energy fr.

when you call her with no file arguments at all, manlifter tries to convert all eligible man pages installed on the system, dropping the resulting xml files under xmlman in the current directory. every successfully translated page foo.N gets copied to manN/foo.xml beneath the output directory — and it does that regardless of what source directory it came from. we don't care where you're from, only where you're going 💖

a manual page is considered ineligible for batch conversion if it contains text indicating it has been generated from DocBook masters or from Doxygen. (not invited to the party, sorry bestie 🙈)

for each source file she examines, if the destination file already exists and is newer than the source, the conversion is simply skipped. the way that means incremental runs of manlifter do the least work needed to keep the target XML tree up to date. iconic. and likewise, in -h mode, derived HTML files are only made when necessary. she's not doing unpaid overtime 💅

Stub pages that are just .so redirections get translated into corresponding symlinks of XML files — and, with -h, HTML files too. slay.

you can also call manlifter with a single file argument, which gets interpreted as the stem name of a potential manual page. then she searches all selected manual sections for a matching page and attempts to convert it. in this case, a copy of the man page and the converted version are dropped immediately beneath the output directory, named foobar.man and foobar.man.xml respectively. ngl this mode is normally only of interest to doclifter developers for debugging that program. that's their business, not ours 🫶

in either of the above cases, manlifter will uncompress the file if it has a .gz, .bz2 or .Z suffix on the name. zip zap, done ✨

🎀 Options are as follows: 🎀

  • -d — pass the string argument to each doclifter call as options. each space-separated token in the string becomes a separate argument in the call. tokenizer moment.
  • -e — run in log-filter mode (mainly of interest to doclifter developers). in this mode, manlifter reads a test log from standard input and filters it in a way dependent on the -f and -q options. if neither of those is given, messages from successful runs are stripped out and only errors are passed through to standard output. bye bye success stories 💀
  • -f — normally, run doclifter on the files named by each line in the argument file. in error-filter mode the argument is instead interpreted as a filtering regular expression. two moods, one flag.
  • -h — also generate HTML translations into the output directory. DocBook citerefentry markup is transformed to hyperlinks in the directory, and a contents listing is generated to index.html. cute AND organized 🎀
  • -I — specify the root of the manual-page tree. by default this is /usr/share/man. home base fr.
  • -m — make a patch to correct the last page fetched. it's copied, an editor is called on the copy (using the environment variable $EDITOR), and then diff(1) is called to drop the patch in the prepatch directory. it fails with an error if such a patch is already present. so don't double-dip bestie 😭
  • -M — lift the specified files, then do the equivalent of the -m option. combo move.
  • -o — set the output directory into which XML-DocBook translations will be dropped. by default this is xmlman under the current directory in batch mode, or the current directory otherwise.
  • -p — interpret the argument as the name of a patch directory (the default name is prepatch under the current directory). each file named foo.N.patch is interpreted as a patch to be applied to the manual page foo(N) before doclifter translates it. glow-up before the photoshoot ✨
  • -q — normally, pass the -q (quiet) option to each doclifter call. in error-filter mode, return a list of files on which translation failed. receipts only.
  • -v — pass the -v (verbose) option to each doclifter call. this option can be repeated to increase the verbosity level. she will NOT stop talking and we love that for her 💅
  • -s — specify a section to scan. use this with an argument; it should not be necessary when doing a conversion of the entire tree.
  • -S — compile error statistics from a manlifter logfile presented on standard input. this option will be of interest mainly to doclifter developers. number crunching era 📊
  • -X — in batch mode, exclude pages listed in the argument file. this is meant to be used for pages that are known good and take an extremely long time to lift, in order to cut down the time for a test run. (most pages lift in less than a half second, but a few can take 15 minutes or longer. 15 MINUTES. bestie. 😭)

🌈 the logfile 🌈

manlifter emits a logfile to standard output. the file begins with a timestamp line and a blank line, and ends with a line giving run time and various interesting statistics. between those are stanzas, separated by blank lines — one for each file on which doclifter was run.

the first line of each stanza begins with "! ", followed by the pathname of the source manual pager, followed by "=" and the return status of the doclifter run on that file. following that is a space and doclifter's runtime in seconds. ⏱️

this initial line may be followed by information messages and the error output of the doclifter run.

💜 heads up: manlifter must find a copy of doclifter in either the current directory or one of the command directories in your PATH in order to run. no doclifter, no party.

💀 BUGS 💀

HTML generation is painfully slow. unfortunately, there is little we can do to remedy this, because XSLT engines are painfully slow. it's not her fault, it's the engine's fault, and we're all just living in it 😭

👑 SEE ALSO 👑

🦋 AUTHOR 🦋

Eric S. Raymond <esr@thyrsus.com>

there is a project web page at http://www.catb.org/~esr/doclifter/. go visit, she's an icon 🫶

and that's the whole page, bestie! this was manlifter from the Documentation Tools collection, version manlifter, dated 2026-03-22. periodt ✨💖🎀

📦 where this page comes from