|
Packit |
e4b6da |
.\" -*- coding: us-ascii -*-
|
|
Packit |
e4b6da |
.if \n(.g .ds T< \\FC
|
|
Packit |
e4b6da |
.if \n(.g .ds T> \\F[\n[.fam]]
|
|
Packit |
e4b6da |
.de URL
|
|
Packit |
e4b6da |
\\$2 \(la\\$1\(ra\\$3
|
|
Packit |
e4b6da |
..
|
|
Packit |
e4b6da |
.if \n(.g .mso www.tmac
|
|
Packit |
e4b6da |
.TH db2x_manxml 1 "3 March 2007" "docbook2X 0.8.8" docbook2X
|
|
Packit |
e4b6da |
.SH NAME
|
|
Packit |
e4b6da |
db2x_manxml \- Make man pages from Man-XML
|
|
Packit |
e4b6da |
.SH SYNOPSIS
|
|
Packit |
e4b6da |
'nh
|
|
Packit |
e4b6da |
.fi
|
|
Packit |
e4b6da |
.ad l
|
|
Packit |
e4b6da |
\fBdb2x_manxml\fR \kx
|
|
Packit |
e4b6da |
.if (\nx>(\n(.l/2)) .nr x (\n(.l/5)
|
|
Packit |
e4b6da |
'in \n(.iu+\nxu
|
|
Packit |
e4b6da |
[\fIoptions\fR] [\fIxml-document\fR]
|
|
Packit |
e4b6da |
'in \n(.iu-\nxu
|
|
Packit |
e4b6da |
.ad b
|
|
Packit |
e4b6da |
'hy
|
|
Packit |
e4b6da |
.SH DESCRIPTION
|
|
Packit |
e4b6da |
\fBdb2x_manxml\fR converts a Man-XML document into one or
|
|
Packit |
e4b6da |
more man pages. They are written in the current directory.
|
|
Packit |
e4b6da |
.PP
|
|
Packit |
e4b6da |
If \fIxml-document\fR is not given, then the document
|
|
Packit |
e4b6da |
to convert is read from standard input.
|
|
Packit |
e4b6da |
.SH OPTIONS
|
|
Packit |
e4b6da |
.TP
|
|
Packit |
e4b6da |
\*(T<\fB\-\-encoding=\fR\*(T>\fIencoding\fR
|
|
Packit |
e4b6da |
Select the character encoding used for the output files.
|
|
Packit |
e4b6da |
The available encodings are those of
|
|
Packit |
e4b6da |
\fBiconv\fR(1).
|
|
Packit |
e4b6da |
The default encoding is \*(T<us\-ascii\*(T>.
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
The XML source may contain characters that are not representable in the encoding that
|
|
Packit |
e4b6da |
you select; in this case the program will bomb out during processing, and you should
|
|
Packit |
e4b6da |
choose another encoding.
|
|
Packit |
e4b6da |
(This is guaranteed not to happen with any Unicode encoding such as
|
|
Packit |
e4b6da |
UTF-8, but unfortunately not everyone is able to
|
|
Packit |
e4b6da |
process Unicode texts.)
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
If you are using GNU\(cqs version of
|
|
Packit |
e4b6da |
\fBiconv\fR(1), you can affix
|
|
Packit |
e4b6da |
\*(T<//TRANSLIT\*(T> to the end of the encoding name
|
|
Packit |
e4b6da |
to attempt transliterations of any unconvertible characters in the output.
|
|
Packit |
e4b6da |
Beware, however, that the really inconvertible characters will be turned
|
|
Packit |
e4b6da |
into another of those damned question marks. (Aren\(cqt you sick of this?)
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
The suffix \*(T<//TRANSLIT\*(T> applied
|
|
Packit |
e4b6da |
to a Unicode encoding \(em in particular, \*(T<utf\-8//TRANSLIT\*(T> \(em
|
|
Packit |
e4b6da |
means that the output files are to remain in Unicode,
|
|
Packit |
e4b6da |
but markup-level character translations using \fButf8trans\fR
|
|
Packit |
e4b6da |
are still to be done. So in most cases, an English-language
|
|
Packit |
e4b6da |
document, converted using
|
|
Packit |
e4b6da |
\*(T<\fB\-\-encoding=\fR\*(T>\*(T<\fButf\-8//TRANSLIT\fR\*(T>
|
|
Packit |
e4b6da |
will actually end up as a US-ASCII document,
|
|
Packit |
e4b6da |
but any untranslatable characters
|
|
Packit |
e4b6da |
will remain as UTF-8 without any warning whatsoever.
|
|
Packit |
e4b6da |
(Note: strictly speaking this is not \(lqtransliteration\(rq.)
|
|
Packit |
e4b6da |
This method of conversion is a compromise over strict
|
|
Packit |
e4b6da |
\*(T<\fB\-\-encoding=\fR\*(T>\*(T<\fBus\-ascii\fR\*(T>
|
|
Packit |
e4b6da |
processing, which aborts if any untranslatable characters are
|
|
Packit |
e4b6da |
encountered.
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
Note that man pages and Texinfo documents
|
|
Packit |
e4b6da |
in non-ASCII encodings (including UTF-8)
|
|
Packit |
e4b6da |
may not be portable to older (non-internationalized) systems,
|
|
Packit |
e4b6da |
which is why the default value for this option is
|
|
Packit |
e4b6da |
\*(T<us\-ascii\*(T>.
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
To suppress any automatic character mapping or encoding conversion
|
|
Packit |
e4b6da |
whatsoever, pass the option
|
|
Packit |
e4b6da |
\*(T<\fB\-\-encoding=\fR\*(T>\*(T<\fButf\-8\fR\*(T>.
|
|
Packit |
e4b6da |
.TP
|
|
Packit |
e4b6da |
\*(T<\fB\-\-list\-files\fR\*(T>
|
|
Packit |
e4b6da |
Write a list of all the output files to standard output,
|
|
Packit |
e4b6da |
in addition to normal processing.
|
|
Packit |
e4b6da |
.TP
|
|
Packit |
e4b6da |
\*(T<\fB\-\-output\-dir=\fR\*(T>\fIdir\fR
|
|
Packit |
e4b6da |
Specify the directory where the output files are placed.
|
|
Packit |
e4b6da |
The default is the current working directory.
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
This option is ignored if the output is to be written
|
|
Packit |
e4b6da |
to standard output (triggered by the
|
|
Packit |
e4b6da |
option \*(T<\fB\-\-to\-stdout\fR\*(T>).
|
|
Packit |
e4b6da |
.TP
|
|
Packit |
e4b6da |
\*(T<\fB\-\-to\-stdout\fR\*(T>
|
|
Packit |
e4b6da |
Write the output to standard output instead of to individual files.
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
If this option is used even when there are supposed to be multiple
|
|
Packit |
e4b6da |
output documents, then everything is concatenated to standard output.
|
|
Packit |
e4b6da |
But beware that most other programs will not accept this concatenated
|
|
Packit |
e4b6da |
output.
|
|
Packit |
e4b6da |
|
|
Packit |
e4b6da |
This option is incompatible with \*(T<\fB\-\-list\-files\fR\*(T>,
|
|
Packit |
e4b6da |
obviously.
|
|
Packit |
e4b6da |
.TP
|
|
Packit |
e4b6da |
\*(T<\fB\-\-help\fR\*(T>
|
|
Packit |
e4b6da |
Show brief usage information and exit.
|
|
Packit |
e4b6da |
.TP
|
|
Packit |
e4b6da |
\*(T<\fB\-\-version\fR\*(T>
|
|
Packit |
e4b6da |
Show version and exit.
|
|
Packit |
e4b6da |
.PP
|
|
Packit |
e4b6da |
Some man pages may be referenced under two or more
|
|
Packit |
e4b6da |
names, instead of just one. For example,
|
|
Packit |
e4b6da |
\fBstrcpy\fR(3)
|
|
Packit |
e4b6da |
and
|
|
Packit |
e4b6da |
\fBstrncpy\fR(3)
|
|
Packit |
e4b6da |
often point to the same man page which describes the two functions together.
|
|
Packit |
e4b6da |
Choose one of the following options to select
|
|
Packit |
e4b6da |
how such man pages are to be generated:
|
|
Packit |
e4b6da |
.TP
|
|
Packit |
e4b6da |
\*(T<\fB\-\-symlinks\fR\*(T>
|
|
Packit |
e4b6da |
For each of all the alternate names for a man page,
|
|
Packit |
e4b6da |
erect symbolic links to the file that contains the real man page content.
|
|
Packit |
e4b6da |
.TP
|
|
Packit |
e4b6da |
\*(T<\fB\-\-solinks\fR\*(T>
|
|
Packit |
e4b6da |
Generate stub pages (using \*(T<.so\*(T> roff requests)
|
|
Packit |
e4b6da |
for the alternate names, pointing them to the real man page content.
|
|
Packit |
e4b6da |
.TP
|
|
Packit |
e4b6da |
\*(T<\fB\-\-no\-links\fR\*(T>
|
|
Packit |
e4b6da |
Do not make any alternative names available.
|
|
Packit |
e4b6da |
The man page can only be referenced under its principal name.
|
|
Packit |
e4b6da |
.PP
|
|
Packit |
e4b6da |
This program uses certain other programs for its operation.
|
|
Packit |
e4b6da |
If they are not in their default installed locations, then use
|
|
Packit |
e4b6da |
the following options to set their location:
|
|
Packit |
e4b6da |
.TP
|
|
Packit |
e4b6da |
\*(T<\fB\-\-utf8trans\-program=\fR\*(T>\fIpath\fR, \*(T<\fB\-\-utf8trans\-map=\fR\*(T>\fIcharmap\fR
|
|
Packit |
e4b6da |
Use the character map \fIcharmap\fR
|
|
Packit |
e4b6da |
with the \fButf8trans\fR(1) program, included with docbook2X, found
|
|
Packit |
e4b6da |
under \fIpath\fR.
|
|
Packit |
e4b6da |
.TP
|
|
Packit |
e4b6da |
\*(T<\fB\-\-iconv\-program=\fR\*(T>\fIpath\fR
|
|
Packit |
e4b6da |
The location of the
|
|
Packit |
e4b6da |
\fBiconv\fR(1) program, used for encoding
|
|
Packit |
e4b6da |
conversions.
|
|
Packit |
e4b6da |
.SH NOTES
|
|
Packit |
e4b6da |
The man pages produced should be compatible
|
|
Packit |
e4b6da |
with most troff implementations and other tools
|
|
Packit |
e4b6da |
that process man pages.
|
|
Packit |
e4b6da |
Some backwards-compatible
|
|
Packit |
e4b6da |
\fBgroff\fR(1) extensions
|
|
Packit |
e4b6da |
are used to make the output look nicer.
|
|
Packit |
e4b6da |
.SH AUTHOR
|
|
Packit |
e4b6da |
Steve Cheng <\*(T<stevecheng@users.sourceforge.net\*(T>>.
|
|
Packit |
e4b6da |
.SH "SEE ALSO"
|
|
Packit |
e4b6da |
The docbook2X manual (in Texinfo or HTML format) fully describes
|
|
Packit |
e4b6da |
how to convert DocBook to man pages and Texinfo.
|
|
Packit |
e4b6da |
.PP
|
|
Packit |
e4b6da |
Up-to-date information about this program
|
|
Packit |
e4b6da |
can be found
|
|
Packit |
e4b6da |
at the
|
|
Packit |
e4b6da |
.URL http://docbook2x.sourceforge.net/ "docbook2X Web site"
|
|
Packit |
e4b6da |
\&.
|
|
Packit |
e4b6da |
.PP
|
|
Packit |
e4b6da |
The input to \fBdb2x_manxml\fR is defined by the XML DTD
|
|
Packit |
e4b6da |
present at \*(T<\fIdtd/Man\-XML\fR\*(T> in the docbook2X
|
|
Packit |
e4b6da |
distribution.
|