Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
MANLIFTER(1)		      Documentation Tools		  MANLIFTER(1)

NAME
       manlifter - mass-conversion script and test harness for doclifter

SYNOPSIS
       manlifter [-d option] [-e] [-f listfile]	[-h] [-I mandir] [-m] [-M]
		 [-o outdir] [-p patch-directory] [-P] [-q] [-v] [-s section]
		 [-X exclude] name...

       manlifter [-S]

DESCRIPTION
       manlifter is a script that sequences doclifter(1) to convert an entire
       manual-page tree	to XML-Docbook,	optionally also	generating HTML	from
       the XML.	Another	use is as a torture-test tool for doclifter; it	logs
       errors to standard output and collects timings.

       Called without any file arguments, manlifter tries to convert all
       eligible	man pages installed on the system, placing the resulting xml
       files under xmlman in the current directory. Each successfully
       translated page foo.N is	copied to manN/foo.xml beneath the output
       directory, regardless of	what source directory it came from.

       A manual	page is	considered ineligible for batch	conversion if it
       contains	text indicating	it has been generated from DocBook masters of
       from Doxygen.

       For each	source file examined, if the destination file exists and is
       newer than the source, the conversion is	skipped; thus, incremental
       runs of manlifter do the	least work needed to keep the target XML tree
       up to date. Likewise, in	-h mode	derived	HTML files are only made when
       necessary.

       Stub pages that are just	.so redirections are translated	to
       corresponding symlinks of XML files (and, with -h, HTML files).

       manlifter may also be called with a single file argument, which is
       interpreted as the stem name of a potential manual page.	 manlifter
       then 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 beheath the output directory,
       with the	names foobar.man and foobar.man.xml, respectively. This	mode
       is normally only	of interest only to doclifter developers for debugging
       that program.

       In either of the	above cases, manlifter will uncompress the file	if it
       has a .gz, .bz2 or .Z suffix on the name.

       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.

       -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 a way dependent on	the -f and -q options.
	   If neither of these is given, messages from successful runs are
	   stripped out	and only errors	passed through to standard output.

       -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.

       -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.

       -I
	   Specify the root of the manual-page tree. By	default	this is
	   /usr/share/man.

       -m
	   Make	a patch	to correct the last page fetched. It is	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. Fails with an error if such a patch is already
	   present.

       -M
	   Lift	the specified files, then do the equivalent of the -m option.

       -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.

       -P
	   Enable profiling using the Python hotshot module; this is only
	   useful for tuning doclifter so it runs faster. Raw data is written
	   to manlifter.prof, and a digested report is appended	to the log on
	   standard output. Warning: the raw data files	can become huge, and
	   the postprocessing for report generation can	take as	long as	the
	   actual processing (or longer!).

       -q
	   Normally, pass the -q (quiet) option	to each	doclifter call.	In
	   error-filter	mode, return a list of files on	which translation
	   failed.

       -v
	   Pass	the -v (verbose) option	to each	doclifter call.	This option
	   can be repeated to increase the verbosity level.

       -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.

       -X
	   In batch mode exclude pages listed in the argument file. 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.)

       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 these are stanzas,
       separated by blank lines, one for each file on which doclifter was run.

       The first line of each stanza beguns with "! ", followed	by the
       pathname	of the source manual pager, followed by	"=" and	the return
       status of 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.

       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.

BUGS
       HTML generation is painfully slow. Unfortunately, there is little we
       can do to remedy	this, because XSLT engines are painfully slow.

SEE ALSO
       doclifter(1), xmlto(1)

AUTHOR
       Eric S. Raymond <esr@thyrsus.com>

       There is	a project web page at http://www.catb.org/~esr/doclifter/.

manlifter			  06/03/2014			  MANLIFTER(1)

NAME | SYNOPSIS | DESCRIPTION | BUGS | SEE ALSO | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=manlifter&sektion=1&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help