\input texinfo

@setfilename docbook2X.info

@documentencoding us-ascii

@settitle docbook2X

@dircategory Document Preparation

@direntry

* docbook2X: (docbook2X).       Convert DocBook into man pages and Texinfo

@end direntry

@node Top, Quick start, , (dir)

@documentlanguage en

@top docbook2X

@cindex DocBook

@i{docbook2X} converts 

DocBook

documents into man pages and 

Texinfo documents.

It aims to support DocBook version 4.2, excepting the features

that cannot be supported or are not useful in a man page or 

Texinfo document.

@cindex web site

@cindex download

For information on the latest releases of docbook2X, and downloads,

please visit the @uref{http://docbook2x.sourceforge.net/,docbook2X home page}.

@menu

* Quick start::                 Examples to get you started

* Converting to man pages::     Details on man-page conversion

* Converting to Texinfo::       Details on Texinfo conversion

* The XSLT stylesheets::        How to run the docbook2X XSLT stylesheets

* Character set conversion::    Discussion on reproducing non-ASCII

                                  characters in the converted output

* FAQ::                         Answers and tips for common problems

* Performance analysis::        Discussion on conversion speed

* How docbook2X is tested::     Discussion of correctness-testing

* To-do list::                  Ideas for future improvements

* Release history::             Changes to the package between releases

* Design notes::                Author's notes on the grand scheme of

                                  docbook2X

* Package installation::        Where to get docbook2X, and details on how

                                  to install it

* Index: Concept index.

@detailmenu

--- The Detailed Node Listing ---

Converting to man pages

* docbook2man: docbook2man wrapper script.   Convert DocBook to man pages

* db2x_manxml::                 Make man pages from Man-XML

Converting to Texinfo

* docbook2texi: docbook2texi wrapper script.   Convert DocBook to Texinfo

* db2x_texixml::                Make Texinfo files from Texi-XML

The XSLT stylesheets

* db2x_xsltproc::               XSLT processor invocation wrapper

* sgml2xml-isoent::             Convert SGML to XML with support for ISO

                                  entities

Character set conversion

* utf8trans::                   Transliterate UTF-8 characters according to

                                  a table

Package installation

* Installation::                Package install procedure

* Dependencies on other software::   Other software packages that docbook2X

                                       needs

@end detailmenu

@end menu

@node Quick start, Converting to man pages, Top, Top

@chapter Quick start

@cindex example usage

@cindex converting to man pages

@cindex converting to Texinfo

To convert to man pages, you run the command @code{docbook2man} (@pxref{docbook2man wrapper script}).  For example,

@example

$ docbook2man --solinks manpages.xml

@end example

The man pages will be output to your current directory.

The @code{--solinks} options tells @code{docbook2man} to create man page

links.  You may want to omit this option when developing documentation

so that your working directory does not explode with many stub man pages.

(If you don't know what this means, you can read about it in detail in @code{db2x_manxml},

or just ignore the previous two sentences and always specify this option.)

To convert to Texinfo, you run the command @code{docbook2texi} (@pxref{docbook2texi wrapper script}).  For example,

@example

$ docbook2texi tdg.xml

@end example

One (or more) Texinfo files will be output to your current directory.

The rest of this manual describes in detail all the other options

and how to customize docbook2X's output.

@node Converting to man pages, Converting to Texinfo, Quick start, Top

@chapter Converting to man pages

@cindex man pages

@cindex converting to man pages

@cindex XSLT stylesheets

@cindex Man-XML

DocBook documents are converted to man pages in two steps:

@enumerate 

@item

The DocBook source is converted by a XSLT stylesheet into an 

intermediate XML format, Man-XML.

Man-XML is simpler than DocBook and closer to the man page format;

it is intended to make the stylesheets' job easier.

The stylesheet for this purpose is in

@file{xslt/man/docbook.xsl}.

For portability, it should always be referred to

by the following URI:

@example

http://docbook2x.sourceforge.net/latest/xslt/man/docbook.xsl

@end example

Run this stylesheet with @ref{db2x_xsltproc,,@code{db2x_xsltproc}}.

@cindex customizing

@strong{Customizing. } 

You can also customize the output by

creating your own XSLT stylesheet ---

changing parameters or adding new templates ---

and importing @file{xslt/man/docbook.xsl}.

@item

Man-XML is converted to the actual man pages by @ref{db2x_manxml,,@code{db2x_manxml}}.

@end enumerate

The @code{docbook2man} (@pxref{docbook2man wrapper script}) command does both steps automatically,

but if any problems occur, you can see the errors more clearly

if you do each step separately:

@example

$ db2x_xsltproc -s man mydoc.xml -o mydoc.mxml

$ db2x_manxml mydoc.mxml

@end example

Options to the conversion stylesheet are described in

@ref{Top,,the man-pages stylesheets reference,docbook2man-xslt,docbook2X Man-pages Stylesheets Reference}.

@cindex pure XSLT

@strong{Pure XSLT conversion. } 

An alternative to the @code{db2x_manxml} Perl script is the XSLT

stylesheet in 

@file{xslt/backend/db2x_manxml.xsl}.

This stylesheet performs a similar function

of converting Man-XML to actual man pages.

It is useful if you desire a pure XSLT

solution to man-page conversion.

Of course, the quality of the conversion using this stylesheet

will never be as good as the Perl @code{db2x_manxml},

and it runs slower.  

In particular, the pure XSLT version

currently does not support tables in man pages,

but its Perl counterpart does.

@menu

* docbook2man: docbook2man wrapper script.   Convert DocBook to man pages

* db2x_manxml::                 Make man pages from Man-XML

@end menu

@node docbook2man wrapper script, db2x_manxml, , Converting to man pages

@section docbook2man

@cindex man pages

@cindex converting to man pages

@cindex wrapper script

@cindex @code{docbook2man}

@subheading Name

@code{docbook2man} --- Convert DocBook to man pages

@subheading Synopsis

@quotation

@t{docbook2man [options]  xml-document }

@end quotation

@subheading Description

@code{docbook2man} converts the given DocBook XML document into man pages.

By default, the man pages will be output to the current directory.

@cindex @code{refentry}

Only the @code{refentry} content

in the DocBook document is converted.

(To convert content outside of a @code{refentry},

stylesheet customization is required.  See the docbook2X

package for details.)

The @code{docbook2man} command is a wrapper script

for a two-step conversion process.

@subheading Options

The available options are essentially the union of the options

from @ref{db2x_xsltproc,,@code{db2x_xsltproc}} and @ref{db2x_manxml,,@code{db2x_manxml}}.

Some commonly-used options are listed below:

@table @asis

@item @code{--encoding=@var{encoding}}

Sets the character encoding of the output.

@item @code{--string-param @var{parameter}=@var{value}}

Sets a stylesheet parameter (options that affect how the output looks).

See ``Stylesheet parameters'' below for the parameters that

can be set.

@item @code{--sgml}

Accept an SGML source document as input instead of XML.

@item @code{--solinks}

Make stub pages for alternate names for an output man page.

@end table

@subsubheading Stylesheet parameters

@cindex stylesheet parameters

@table @asis

@item @code{uppercase-headings}

@strong{Brief. } Make headings uppercase?

@strong{Default setting. } @samp{1} (boolean true)

Headings in man page content should be or should not be uppercased.

@item @code{manvolnum-cite-numeral-only}

@strong{Brief. } Man page section citation should use only the number

@strong{Default setting. } @samp{1} (boolean true)

When citing other man pages, the man-page section is either given as is,

or has the letters stripped from it, citing only the number of the

section (e.g. section @samp{3x} becomes

@samp{3}).  This option specifies which style. 

@item @code{quotes-on-literals}

@strong{Brief. } Display quotes on @code{literal}

elements?

@strong{Default setting. } @samp{0} (boolean false)

If true, render @code{literal} elements

with quotes around them.

@item @code{show-comments}

@strong{Brief. } Display @code{comment} elements?

@strong{Default setting. } @samp{1} (boolean true)

If true, comments will be displayed, otherwise they are suppressed.

Comments here refers to the @code{comment} element,

which will be renamed @code{remark} in DocBook V4.0,

not XML comments (<-- like this -->) which are unavailable.

@item @code{function-parens}

@strong{Brief. } Generate parentheses after a function?

@strong{Default setting. } @samp{0} (boolean false)

If true, the formatting of

a @code{<function>} element will include

generated parenthesis.

@item @code{xref-on-link}

@strong{Brief. } Should @code{link} generate a

cross-reference?

@strong{Default setting. } @samp{1} (boolean true)

Man pages cannot render the hypertext links created by @code{link}.  If this option is set, then the

stylesheet renders a cross reference to the target of the link.

(This may reduce clutter).  Otherwise, only the content of the @code{link} is rendered and the actual link itself is

ignored.

@item @code{header-3}

@strong{Brief. } Third header text

@strong{Default setting. } (blank)

Specifies the text of the third header of a man page,

typically the date for the man page.  If empty, the @code{date} content for the @code{refentry} is used.

@item @code{header-4}

@strong{Brief. } Fourth header text

@strong{Default setting. } (blank)

Specifies the text of the fourth header of a man page.

If empty, the @code{refmiscinfo} content for

the @code{refentry} is used.

@item @code{header-5}

@strong{Brief. } Fifth header text

@strong{Default setting. } (blank)

Specifies the text of the fifth header of a man page.

If empty, the `manual name', that is, the title of the

@code{book} or @code{reference} container is used.

@item @code{default-manpage-section}

@strong{Brief. } Default man page section

@strong{Default setting. } @samp{1}

The source document usually indicates the sections that each man page

should belong to (with @code{manvolnum} in

@code{refmeta}).  In case the source

document does not indicate man-page sections, this option specifies the

default.

@item @code{custom-localization-file}

@strong{Brief. } URI of XML document containing custom localization data

@strong{Default setting. } (blank)

This parameter specifies the URI of a XML document

that describes text translations (and other locale-specific information)

that is needed by the stylesheet to process the DocBook document.

The text translations pointed to by this parameter always

override the default text translations 

(from the internal parameter @code{localization-file}).

If a particular translation is not present here,

the corresponding default translation 

is used as a fallback.

This parameter is primarily for changing certain

punctuation characters used in formatting the source document.

The settings for punctuation characters are often specific

to the source document, but can also be dependent on the locale.

To not use custom text translations, leave this parameter 

as the empty string.

@item @code{custom-l10n-data}

@strong{Brief. } XML document containing custom localization data

@strong{Default setting. } @samp{document($custom-localization-file)}

This parameter specifies the XML document

that describes text translations (and other locale-specific information)

that is needed by the stylesheet to process the DocBook document.

This parameter is internal to the stylesheet.

To point to an external XML document with a URI or a file name, 

you should use the @code{custom-localization-file}

parameter instead.

However, inside a custom stylesheet 

(@emph{not on the command-line})

this paramter can be set to the XPath expression

@samp{document('')},

which will cause the custom translations 

directly embedded inside the custom stylesheet to be read.

@item @code{author-othername-in-middle}

@strong{Brief. } Is @code{othername} in @code{author} a

middle name?

@strong{Default setting. } @samp{1}

If true, the @code{othername} of an @code{author}

appears between the @code{firstname} and

@code{surname}.  Otherwise, @code{othername}

is suppressed.

@end table

@subheading Examples

@cindex example usage

@example

$ docbook2man --solinks manpages.xml

$ docbook2man --solinks --encoding=utf-8//TRANSLIT manpages.xml

$ docbook2man --string-param header-4="Free Recode 3.6" document.xml

@end example

@subheading Limitations

@itemize 

@item

Internally there is one long pipeline of programs which your 

document goes through.  If any segment of the pipeline fails

(even trivially, like from mistyped program options), 

the resulting errors can be difficult to decipher ---

in this case, try running the components of docbook2X

separately.

@end itemize

@node db2x_manxml, , docbook2man wrapper script, Converting to man pages

@section @code{db2x_manxml}

@cindex man pages

@cindex converting to man pages

@cindex Man-XML

@cindex stub pages

@cindex symbolic links

@cindex encoding

@cindex output directory

@cindex @code{db2x_manxml}

@subheading Name

@code{db2x_manxml} --- Make man pages from Man-XML

@subheading Synopsis

@quotation

@t{db2x_manxml [options] [xml-document]}

@end quotation

@subheading Description

@code{db2x_manxml} converts a Man-XML document into one or 

more man pages.  They are written in the current directory.

If @var{xml-document} is not given, then the document

to convert is read from standard input.  

@subheading Options

@table @asis

@item @code{--encoding=@var{encoding}}

Select the character encoding used for the output files.

The available encodings are those of 

iconv(1). 

The default encoding is @samp{us-ascii}.  

The XML source may contain characters that are not representable in the encoding that

you select;  in this case the program will bomb out during processing, and you should 

choose another encoding.

(This is guaranteed not to happen with any Unicode encoding such as 

UTF-8, but unfortunately not everyone is able to 

process Unicode texts.)

If you are using GNU's version of 

iconv(1), you can affix 

@samp{//TRANSLIT} to the end of the encoding name

to attempt transliterations of any unconvertible characters in the output.

Beware, however, that the really inconvertible characters will be turned

into another of those damned question marks.  (Aren't you sick of this?)

The suffix @samp{//TRANSLIT} applied

to a Unicode encoding --- in particular, @samp{utf-8//TRANSLIT} ---

means that the output files are to remain in Unicode,

but markup-level character translations using @code{utf8trans} 

are still to be done.  So in most cases, an English-language

document, converted using 

@code{--encoding=@samp{utf-8//TRANSLIT}}

will actually end up as a US-ASCII document,

but any untranslatable characters 

will remain as UTF-8 without any warning whatsoever.

(Note: strictly speaking this is not ``transliteration''.)

This method of conversion is a compromise over strict

@code{--encoding=@samp{us-ascii}}

processing, which aborts if any untranslatable characters are 

encountered.

Note that man pages and Texinfo documents 

in non-ASCII encodings (including UTF-8)

may not be portable to older (non-internationalized) systems,

which is why the default value for this option is 

@samp{us-ascii}.

To suppress any automatic character mapping or encoding conversion

whatsoever, pass the option 

@code{--encoding=@samp{utf-8}}.

@item @code{--list-files}

Write a list of all the output files to standard output,

in addition to normal processing.

@item @code{--output-dir=@var{dir}}

Specify the directory where the output files are placed.

The default is the current working directory.

This option is ignored if the output is to be written

to standard output (triggered by the 

option @code{--to-stdout}).

@item @code{--to-stdout}

Write the output to standard output instead of to individual files.

If this option is used even when there are supposed to be multiple

output documents, then everything is concatenated to standard output.

But beware that most other programs will not accept this concatenated

output.

This option is incompatible with @code{--list-files},

obviously.

@item @code{--help}

Show brief usage information and exit.

@item @code{--version}

Show version and exit.

@end table

Some man pages may be referenced under two or more

names, instead of just one.  For example, 

strcpy(3)

and

strncpy(3)

often point to the same man page which describes the two functions together.

Choose one of the following options to select

how such man pages are to be generated:

@table @asis

@item @code{--symlinks}

For each of all the alternate names for a man page,

erect symbolic links to the file that contains the real man page content.

@item @code{--solinks}

Generate stub pages (using @samp{.so} roff requests)

for the alternate names, pointing them to the real man page content.

@item @code{--no-links}

Do not make any alternative names available.

The man page can only be referenced under its principal name.

@end table

This program uses certain other programs for its operation.

If they are not in their default installed locations, then use

the following options to set their location:

@table @asis

@item @code{--utf8trans-program=@var{path}}

@itemx @code{--utf8trans-map=@var{charmap}}

Use the character map @var{charmap}

with the @ref{utf8trans,,@code{utf8trans}} program, included with docbook2X, found

under @var{path}.

@item @code{--iconv-program=@var{path}}

The location of the 

iconv(1) program, used for encoding

conversions.

@end table

@subheading Notes

@cindex @code{groff}

@cindex compatibility

The man pages produced should be compatible

with most troff implementations and other tools

that process man pages.

Some backwards-compatible 

groff(1) extensions

are used to make the output look nicer.

@subheading See Also

The input to @code{db2x_manxml} is defined by the XML DTD

present at @file{dtd/Man-XML} in the docbook2X

distribution.

@node Converting to Texinfo, The XSLT stylesheets, Converting to man pages, Top

@chapter Converting to Texinfo

@cindex Texinfo

@cindex converting to Texinfo

@cindex XSLT stylesheets

@cindex Texi-XML

DocBook documents are converted to Texinfo in two steps:

@enumerate 

@item

The DocBook source is converted by a XSLT stylesheet into an intermediate

XML format, Texi-XML.

Texi-XML is simpler than DocBook and closer to the Texinfo format;

it is intended to make the stylesheets' job easier.

The stylesheet for this purpose is in

@file{xslt/texi/docbook.xsl}.

For portability, it should always be referred to

by the following URI:

@example

http://docbook2x.sourceforge.net/latest/xslt/texi/docbook.xsl

@end example

Run this stylesheet with @ref{db2x_xsltproc,,@code{db2x_xsltproc}}.

@cindex customizing

@strong{Customizing. } 

You can also customize the output by

creating your own XSLT stylesheet ---

changing parameters or adding new templates ---

and importing @file{xslt/texi/docbook.xsl}.

@item

Texi-XML is converted to the actual Texinfo files by @ref{db2x_texixml,,@code{db2x_texixml}}.

@end enumerate

The @code{docbook2texi} (@pxref{docbook2texi wrapper script}) command does both steps automatically,

but if any problems occur, you can see the errors more clearly

if you do each step separately:

@example

$ db2x_xsltproc -s texi mydoc.xml -o mydoc.txml

$ db2x_texixml mydoc.txml

@end example

Options to the conversion stylesheet are described

in @ref{Top,,the Texinfo stylesheets reference,docbook2texi-xslt,docbook2X Texinfo Stylesheets Reference}.

@menu

* docbook2texi: docbook2texi wrapper script.   Convert DocBook to Texinfo

* db2x_texixml::                Make Texinfo files from Texi-XML

@end menu

@node docbook2texi wrapper script, db2x_texixml, , Converting to Texinfo

@section docbook2texi

@cindex Texinfo

@cindex converting to Texinfo

@cindex wrapper script

@cindex @code{docbook2texi}

@subheading Name

@code{docbook2texi} --- Convert DocBook to Texinfo

@subheading Synopsis

@quotation

@t{docbook2texi [options]  xml-document }

@end quotation

@subheading Description

@code{docbook2texi} converts the given 

DocBook XML document into one or more Texinfo documents.

By default, these Texinfo documents will be output to the current

directory.

The @code{docbook2texi} command is a wrapper script

for a two-step conversion process.

@subheading Options

The available options are essentially the union of the options

for @ref{db2x_xsltproc,,@code{db2x_xsltproc}} and @ref{db2x_texixml,,@code{db2x_texixml}}.

Some commonly-used options are listed below:

@table @asis

@item @code{--encoding=@var{encoding}}

Sets the character encoding of the output.

@item @code{--string-param @var{parameter}=@var{value}}

Sets a stylesheet parameter (options that affect how the output looks).

See ``Stylesheet parameters'' below for the parameters that

can be set.

@item @code{--sgml}

Accept an SGML source document as input instead of XML.

@end table

@subsubheading Stylesheet parameters

@cindex stylesheet parameters

@table @asis

@item @code{captions-display-as-headings}

@strong{Brief. } Use heading markup for minor captions?

@strong{Default setting. } @samp{0} (boolean false)

If true, @code{title}

content in some (formal) objects are rendered with the Texinfo

@code{@@@var{heading}} commands.

If false, captions are rendered as an emphasized paragraph.

@item @code{links-use-pxref}

@strong{Brief. } Translate @code{link} using

@code{@@pxref}

@strong{Default setting. } @samp{1} (boolean true)

If true, @code{link} is translated

with the hypertext followed by the cross reference in parentheses.

Otherwise, the hypertext content serves as the cross-reference name

marked up using @code{@@ref}.  Typically info displays this

contruct badly.

@item @code{explicit-node-names}

@strong{Brief. } Insist on manually constructed Texinfo node

names

@strong{Default setting. } @samp{0} (boolean false)

Elements in the source document can influence the Texinfo node name

generation specifying either a @code{xreflabel}, or for the sectioning elements,

a @code{title} with @code{role='texinfo-node'} in the 

@code{@var{*}info} container.

However, for the majority of source documents, explicit Texinfo node

names are not available, and the stylesheet tries to generate a

reasonable one instead, e.g. from the normal title of an element.  

The generated name may not be optimal.  If this option is set and the

stylesheet needs to generate a name, a warning is emitted and 

@code{generate-id} is always used for the name.

When the hashtable extension is not available, the stylesheet cannot

check for node name collisions, and in this case, setting this option

and using explicit node names are recommended.  

This option is not set (i.e. false) by default.

@quotation

@strong{Note}

The absolute fallback for generating node names is using the XSLT

function @code{generate-id}, and the stylesheet always

emits a warning in this case regardless of the setting of

@code{explicit-node-names}.

@end quotation

@item @code{show-comments}

@strong{Brief. } Display @code{comment} elements?

@strong{Default setting. } @samp{1} (boolean true)

If true, comments will be displayed, otherwise they are suppressed.

Comments here refers to the @code{comment} element,

which will be renamed @code{remark} in DocBook V4.0,

not XML comments (<-- like this -->) which are unavailable.

@item @code{funcsynopsis-decoration}

@strong{Brief. } Decorate elements of a FuncSynopsis?

@strong{Default setting. } @samp{1} (boolean true)

If true, elements of the FuncSynopsis will be decorated (e.g. bold or

italic).  The decoration is controlled by functions that can be redefined

in a customization layer.

@item @code{function-parens}

@strong{Brief. } Generate parentheses after a function?

@strong{Default setting. } @samp{0} (boolean false)

If true, the formatting of

a @code{<function>} element will include

generated parenthesis.

@item @code{refentry-display-name}

@strong{Brief. } Output NAME header before 'RefName'(s)?

@strong{Default setting. } @samp{1} (boolean true)

If true, a "NAME" section title is output before the list

of 'RefName's.

@item @code{manvolnum-in-xref}

@strong{Brief. } Output @code{manvolnum} as part of

@code{refentry} cross-reference?

@strong{Default setting. } @samp{1} (boolean true)

if true, the @code{manvolnum} is used when cross-referencing

@code{refentry}s, either with @code{xref}

or @code{citerefentry}.

@item @code{prefer-textobjects}

@strong{Brief. } Prefer @code{textobject}

over @code{imageobject}?

@strong{Default setting. } @samp{1} (boolean true)

If true, the 

@code{textobject}

in a @code{mediaobject}

is preferred over any

@code{imageobject}.

(Of course, for output formats other than Texinfo, you usually

want to prefer the @code{imageobject},

but Info is a text-only format.)

In addition to the values true and false, this parameter

may be set to @samp{2} to indicate that

both the text and the images should be output.

You may want to do this because some Texinfo viewers

can read images.  Note that the Texinfo @code{@@image}

command has its own mechanism for switching between text

and image output --- but we do not use this here.

The default is true.

@item @code{semantic-decorations}

@strong{Brief. } Use Texinfo semantic inline markup?

@strong{Default setting. } @samp{1} (boolean true)

If true, the semantic inline markup of DocBook is translated into

(the closest) Texinfo equivalent.  This is the default.

However, because the Info format is limited to plain text,

the semantic inline markup is often distinguished by using 

explicit quotes, which may not look good.  

You can set this option to false to suppress these.

(For finer control over the inline formatting, you can

use your own stylesheet.)

@item @code{custom-localization-file}

@strong{Brief. } URI of XML document containing custom localization data

@strong{Default setting. } (blank)

This parameter specifies the URI of a XML document

that describes text translations (and other locale-specific information)

that is needed by the stylesheet to process the DocBook document.

The text translations pointed to by this parameter always

override the default text translations 

(from the internal parameter @code{localization-file}).

If a particular translation is not present here,

the corresponding default translation 

is used as a fallback.

This parameter is primarily for changing certain

punctuation characters used in formatting the source document.

The settings for punctuation characters are often specific

to the source document, but can also be dependent on the locale.

To not use custom text translations, leave this parameter 

as the empty string.

@item @code{custom-l10n-data}

@strong{Brief. } XML document containing custom localization data

@strong{Default setting. } @samp{document($custom-localization-file)}

This parameter specifies the XML document

that describes text translations (and other locale-specific information)

that is needed by the stylesheet to process the DocBook document.

This parameter is internal to the stylesheet.

To point to an external XML document with a URI or a file name, 

you should use the @code{custom-localization-file}

parameter instead.

However, inside a custom stylesheet 

(@emph{not on the command-line})

this paramter can be set to the XPath expression

@samp{document('')},

which will cause the custom translations 

directly embedded inside the custom stylesheet to be read.

@item @code{author-othername-in-middle}

@strong{Brief. } Is @code{othername} in @code{author} a

middle name?

@strong{Default setting. } @samp{1}

If true, the @code{othername} of an @code{author}

appears between the @code{firstname} and

@code{surname}.  Otherwise, @code{othername}

is suppressed.