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

FreeBSD Manual Pages

  
 
  

home | help
DOCBOOK2MDOC(1)		    General Commands Manual	       DOCBOOK2MDOC(1)

NAME
       docbook2mdoc -- convert DocBook to mdoc

SYNOPSIS
       docbook2mdoc [-W] [-s section] [-T mdoc | tree |	lint] [file]

DESCRIPTION
       The docbook2mdoc	utility	reads DocBook input from a file	and translates
       it to mdoc(7) and eqn(7).  If file is omitted, standard input is	used.

       The options are as follows:

       -s  Specify  the	 manual	page section to	be used	as the second argument
	   of the Dt macro.  Defaults to the content of	the first <manvolnum >
	   element in the first	<refmeta > block, if any, or to	"1" otherwise.

       -T  Select the output mode.  The	following arguments are	supported:

	   mdoc	 Translate the input to	mdoc(7).  This is the default.

	   tree	 Dump a	human-readable representation of the parse tree.  Each
		 output	line shows one tree node.  Child  nodes	 are  indented
		 with respect to their parent node.  The columns are:

		 1.  An	 asterisk if the node starts a new text	line, or a hy-
		     phen if the node follows the previous node	without	inter-
		     vening whitespace.

		 2.  The node type.

		 3.  For text nodes, the text contents.	 For other nodes,  the
		     attributes, if any.

	   lint	 Do  not produce any output, only error	messages.  Can be com-
		 bined with -W.

       -W  Report warnings on standard error output, and if any	 occur,	 raise
	   the "EXIT STATUS" to	at least 2.

       A  subset  of DocBook 5.1 elements are recognized, as well as some ele-
       ments from earlier versions.  The parser	is  optimized  for  robustness
       even  on	 invalid  input, always	producing some output on a best-effort
       basis.  Input is	not required to	be well-formed,	nor to adhere to  Doc-
       Book syntactic or semantic requirements.

       Unknown	elements are ignored in	the sense that they do not affect for-
       matting and only	their content is  rendered.   Unknown  attributes  are
       silently	discarded.

       In addition to DocBook elements,	the following constructs are handled:

       <! DOCTYPE ... [	<!ENTITY name "definition" > ]>
	       Internal	subset declaration to define an	XML entity.

       <! DOCTYPE ... [	<!ENTITY name SYSTEM "file" > ]>
	       Internal	 subset	 declaration  to define	an XML entity using an
	       external	file.

       <! DOCTYPE ... [	<!ENTITY % name	SYSTEM "file" >	%name ]>
	       Internal	subset declaration to include an external file that is
	       supposed	to contain entity declarations.

       < mml:... >
	       Elements	from the MathML	namespace.  These  are	translated  to
	       eqn(7).

       < xi:include ...	href="file">
	       Include an external DocBook file	into the current document.

EXIT STATUS
       The docbook2mdoc	utility	exits with one of the following	values:

       0   No error occurred, and if -W	was specified, no warning occurred ei-
	   ther.

       2   At least one	warning	occurred, but no error,	and -W was specified.

       3   At least one	parsing	error occurred.

       5   Invalid command line	arguments were specified.  No input files have
	   been	read.

       6   Memory was exhausted.  Parsing was aborted immediately.

EXAMPLES
       To pipe a DocBook document foo.xml through mandoc(1) and	a pager:

	     $ docbook2mdoc foo.xml | mandoc -l

DIAGNOSTICS
       Messages	displayed by docbook2mdoc follow this format:

	     docbook2mdoc: file:line:column: level: message

       The  first three	fields identify	the file name, line number, and	column
       number of the input file	where the message was triggered.  The line and
       column numbers start at 1.

       Message levels have the following meanings:

       fatal	An operating system error occurred, typically  memory  exhaus-
		tion, and parsing was aborted immediately.

       error	Indicates  a risk of information loss or severe	misformatting,
		for example caused by  unknown	elements  or  missing  include
		files.

       warning	Indicates  a risk that the information shown or	its formatting
		may mismatch the author's intent in minor ways.	 For  example,
		mismatched or missing end tags are classified as warnings.

SEE ALSO
       mandoc(1), eqn(7), mdoc(7)

AUTHORS
       docbook2mdoc was	written	by Kristaps Dzonsons <kristaps@bsd.lv> and
       Ingo Schwarze <schwarze@openbsd.org>.

FreeBSD	Ports 14.quarterly	  May 2, 2019		       DOCBOOK2MDOC(1)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=docbook2mdoc&sektion=1&manpath=FreeBSD+Ports+14.3.quarterly>

home | help