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

FreeBSD Manual Pages

  
 
  

home | help
docbook2texi(1)			   docbook2X		       docbook2texi(1)

NAME
       docbook2texi - Convert DocBook to Texinfo

SYNOPSIS
       docbook2texi [options] xml-document

DESCRIPTION
       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  docbook2texi command is a wrapper script for a two-step conversion
       process.	 See the section "CONVERSION PROCESS" below for	details.

OPTIONS
       The available options are essentially the  union	 of  the  options  for
       db2x_xsltproc(1)	and db2x_texixml(1).

       Some commonly-used options are listed below:

       --encoding=encoding
	      Sets the character encoding of the output.

       --string-param parameter=value
	      Sets  a stylesheet parameter (options that affect	how the	output
	      looks).  See "Stylesheet parameters" below  for  the  parameters
	      that can be set.

       --sgml Accept an	SGML source document as	input instead of XML.

   STYLESHEET PARAMETERS
       captions-display-as-headings
	      Brief. Use heading markup	for minor captions?

	      Default setting. 0 (boolean false)

	      If  true,	 title	content	 in some (formal) objects are rendered
	      with the Texinfo @heading	commands.

	      If false,	captions are rendered as an emphasized paragraph.

       links-use-pxref
	      Brief. Translate link using @pxref

	      Default setting. 1 (boolean true)

	      If true, 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 @ref. Typically info	displays this contruct
	      badly.

       explicit-node-names
	      Brief. Insist on manually	constructed Texinfo node names

	      Default setting. 0 (boolean false)

	      Elements	in  the	source document	can influence the Texinfo node
	      name generation specifying either	a xreflabel, or	for  the  sec-
	      tioning  elements, a title with role='texinfo-node' in the *info
	      container.

	      However, for the majority	of source documents, explicit  Texinfo
	      node names are not available, and	the stylesheet tries to	gener-
	      ate 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 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.
	      Note

	      The  absolute  fallback  for  generating node names is using the
	      XSLT function generate-id, and the  stylesheet  always  emits  a
	      warning  in  this	 case  regardless  of  the  setting of explic-
	      it-node-names.

       show-comments
	      Brief. Display comment elements?

	      Default setting. 1 (boolean true)

	      If true, comments	will be	displayed,  otherwise  they  are  sup-
	      pressed.	 Comments  here	 refers	 to the	comment	element, which
	      will be renamed remark in	DocBook	V4.0, not  XML	comments  (<--
	      like this	-->) which are unavailable.

       funcsynopsis-decoration
	      Brief. Decorate elements of a FuncSynopsis?

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

       function-parens
	      Brief. Generate parentheses after	a function?

	      Default setting. 0 (boolean false)

	      If  true,	 the  formatting  of a <function> element will include
	      generated	parenthesis.

       refentry-display-name
	      Brief. Output NAME header	before 'RefName'(s)?

	      Default setting. 1 (boolean true)

	      If true, a "NAME"	section	title is output	 before	 the  list  of
	      'RefName's.

       manvolnum-in-xref
	      Brief. Output manvolnum as part of refentry cross-reference?

	      Default setting. 1 (boolean true)

	      if true, the manvolnum is	used when cross-referencing refentrys,
	      either with xref or citerefentry.

       prefer-textobjects
	      Brief. Prefer textobject over imageobject?

	      Default setting. 1 (boolean true)

	      If true, the textobject in a mediaobject is preferred  over  any
	      imageobject.

	      (Of  course,  for	output formats other than Texinfo, you usually
	      want to prefer the imageobject, but Info is a text-only format.)

	      In addition to the values	true and false,	this parameter may  be
	      set to 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	@image command has its
	      own mechanism for	switching between text and image output	-- but
	      we do not	use this here.

	      The default is true.

       semantic-decorations
	      Brief. Use Texinfo semantic inline markup?

	      Default setting. 1 (boolean true)

	      If true, the semantic inline markup of DocBook is	translated in-
	      to (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.)

       custom-localization-file
	      Brief. URI of XML	document containing custom localization	data

	      Default setting. (blank)

	      This parameter specifies the URI of  a  XML  document  that  de-
	      scribes  text  translations  (and	other locale-specific informa-
	      tion) that is needed by the stylesheet to	 process  the  DocBook
	      document.

	      The  text	translations pointed to	by this	parameter always over-
	      ride the default text translations (from the internal  parameter
	      localization-file).   If a particular translation	is not present
	      here, the	corresponding default translation is used as  a	 fall-
	      back.

	      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 doc-
	      ument, but can also be dependent on the locale.

	      To not use custom	text translations, leave this parameter	as the
	      empty string.

       custom-l10n-data
	      Brief. XML document containing custom localization data

	      Default setting. 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 custom-localization-file parameter instead.

	      However,	inside	a  custom stylesheet (not on the command-line)
	      this paramter can	be set to the XPath  expression	 document(''),
	      which  will  cause the custom translations directly embedded in-
	      side the custom stylesheet to be read.

       author-othername-in-middle
	      Brief. Is	othername in author a middle name?

	      Default setting. 1

	      If true, the othername of	an author appears between  the	first-
	      name and surname.	Otherwise, othername is	suppressed.

       output-file
	      Brief. Name of the Info file

	      Default setting. (blank)

	      This  parameter specifies	the name of the	final Info file, over-
	      riding the setting in the	document itself	and the	automatic  se-
	      lection in the stylesheet. If the	document is a set, this	param-
	      eter has no effect.
	      Important

	      Do not include the .info extension in the	name.

       (Note that this parameter has nothing to	do with	the name of the	 Texi-
       XML output by the XSLT processor	you are	running	this stylesheet	from.)

       directory-category
	      Brief. The categorization	of the document	in the Info directory

	      Default setting. (blank)

	      This is set to the category that the document should go under in
	      the Info directory of installed Info files.  For example,	Gener-
	      al Commands.
	      Note

	      Categories may also be set directly in the source	document.  But
	      if this parameter	is not empty, then  it	always	overrides  the
	      setting in the source document.

       directory-description
	      Brief. The description of	the document in	the Info directory

	      Default setting. (blank)

	      This  is a short description of the document that	appears	in the
	      Info directory of	installed Info files.  For example, An	Inter-
	      active Plotting Program.
	      Note

	      Menu  descriptions  may also be set directly in the source docu-
	      ment.  But if this parameter is not empty, then it always	 over-
	      rides the	setting	in the source document.

       index-category
	      Brief. The Texinfo index to use

	      Default setting. cp

	      The Texinfo index	for indexterm and index	is specified using the
	      role attribute. If the above elements do not have	a  role,  then
	      the default specified by this parameter is used.

	      The predefined indices are:

	      c, cp  Concept index

	      f, fn  Function index

	      v, vr  Variable index

	      k, ky  Keystroke index

	      p, pg  Program index

	      d, tp  Data type index

       User-defined indices are	not yet	supported.

       qanda-defaultlabel
	      Brief. Sets the default for defaultlabel on QandASet.

	      Default setting.

	      If  no  defaultlabel  attribute is specified on a	QandASet, this
	      value is used. It	must be	one of the legal values	 for  the  de-
	      faultlabel attribute.

       qandaset-generate-toc
	      Brief. Is	a Table	of Contents created for	QandASets?

	      Default setting.

	      If true, a ToC is	constructed for	QandASets.

EXAMPLES
       $ docbook2texi tdg.xml
       $ docbook2texi --encoding=utf-8//TRANSLIT tdg.xml
       $ docbook2texi --string-param semantic-decorations=0 tdg.xml
       .fi

CONVERSION PROCESS
   Converting to Texinfo
       DocBook documents are converted to Texinfo in two steps:

       1.  The DocBook source is converted by a	XSLT stylesheet	into an	inter-
	   mediate 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 xslt/texi/docbook.xsl.  For
	   portability,	it should always be referred to	by the following URI:

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

	   Run this stylesheet with db2x_xsltproc(1).

	   Customizing.	 You can also customize	the output  by	creating  your
	   own	XSLT stylesheet	-- changing parameters or adding new templates
	   -- and importing xslt/texi/docbook.xsl.

       2.  Texi-XML is converted to the	 actual	 Texinfo  files	 by  db2x_tex-
	   ixml(1).

       The  docbook2texi  command  does	 both  steps automatically, but	if any
       problems	occur, you can see the errors more clearly if you do each step
       separately:

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

       Options to the conversion stylesheet are	described
       in the Texinfo stylesheets
       reference.

   Character set conversion
       When  translating  XML  to legacy ASCII-based formats with poor support
       for Unicode, such as man	pages and Texinfo, there is always the problem
       that  Unicode  characters in the	source document	also have to be	trans-
       lated somehow.

       A straightforward character set conversion from Unicode does  not  suf-
       fice,  because  the  target  character  set,  usually  US-ASCII	or ISO
       Latin-1,	do not contain common characters such as dashes	and direction-
       al  quotation marks that	are widely used	in XML documents. But document
       formatters (man and Texinfo) allow such characters to be	entered	 by  a
       markup escape: for example, \(lq	for the	left directional quote ".  And
       if a markup-level escape	is not	available,  an	ASCII  transliteration
       might  be  used:	 for example, using the	ASCII less-than	sign < for the
       angle quotation mark <.

       So the Unicode character	problem	can be solved in two steps:

       1.  utf8trans(1), a program included in docbook2X, maps Unicode charac-
	   ters	to markup-level	escapes	or transliterations.

	   Since there is not necessarily a fixed, official mapping of Unicode
	   characters, utf8trans can read in  user-modifiable  character  map-
	   pings  expressed in text files and apply them. (Unlike most charac-
	   ter set converters.)

	   In  charmaps/man/roff.charmap  and  charmaps/man/texi.charmap   are
	   character  maps  that  may be used for man-page and Texinfo conver-
	   sion.  The programs db2x_manxml(1) and db2x_texixml(1)  will	 apply
	   these character maps, or another character map specified by the us-
	   er, automatically.

       2.  The rest of the Unicode text	is converted to	some  other  character
	   set (encoding).  For	example, a French document with	accented char-
	   acters (such	as e) might be converted to ISO	Latin 1.

	   This	step is	applied	after utf8trans	character mapping,  using  the
	   iconv(1)   encoding	 conversion  tool.   Both  db2x_manxml(1)  and
	   db2x_texixml(1) can	call  iconv(1)	automatically  when  producing
	   their output.

FILES
       /usr/local/share/docbook2X/xslt/texi/docbook.xsl
       /usr/local/share/docbook2X/xslt/backend/db2x_texixml.xsl
       /usr/local/share/docbook2X/xslt/catalog.xml
       /usr/local/share/docbook2X/charmaps/texi.charmap.xml
       /usr/local/share/docbook2X/charmaps/texi.charmap.xml

       The above files are distributed and installed by	the docbook2X package.

NOTES
       The  docbook2man	 or  the docbook2texi command described	in this	manual
       page come from the docbook2X package.  It should	not be	confused  with
       the command of the same name from the obsoleted docbook-utils package.

LIMITATIONS
       o 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 dif-
	 ficult	to decipher -- in this case, try  running  the	components  of
	 docbook2X separately.

AUTHOR
       Steve Cheng <stevecheng@users.sourceforge.net>.

SEE ALSO
       db2x_xsltproc(1), db2x_texixml(1), utf8trans(1)

       The docbook2X manual (in	Texinfo	or HTML	format)	fully describes	how to
       convert DocBook to man pages and	Texinfo.

       Up-to-date information about this program can be	found at the docbook2X
       Web site	<http://docbook2x.sourceforge.net/> .

docbook2X 0.8.8			 3 March 2007		       docbook2texi(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | EXAMPLES | CONVERSION PROCESS | FILES | NOTES | LIMITATIONS | AUTHOR | SEE ALSO

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

home | help