README.xml

<?xml version="1.0" encoding="UTF-8"?>
<article version="5.0" xmlns="http://docbook.org/ns/docbook"><info><title>Docbook::Convert README</title><author><personname><firstname>Andrew</firstname><surname>Speer</surname></personname></author><pubdate>2025-08-30</pubdate></info><section><title>Docbook::Convert - migrate Docbook files to Markdown or POD</title><para>This Perl module arose from the mixed results I had in migrating
    Docbook material to Markdown - and from there to POD - using pandoc, rman
    and other existing tools. None of the toolchains produced the output I was
    after.</para></section><section><title>Why use XML for documentation ?</title><para>I prefer to write documentation for man pages in Docbook using the
    XMLMind XXE editor. It has Docbook templates and formatting features that
    allow for quick and easy creation of man pages, articles etc. Additionally
    the XXE editor shows formatting in realtime allowing for a more complete
    sense of what the document will look like when finished.</para><para>However I could not find toolsets which gave satisfactory results
    when converting Docbook to Markdown or POD. This module provides a
    facility to perform those conversions.</para></section><section><title>Why not write an XSL stylesheet and use XSLT ?</title><para>After trying to get my head around the syntax of XSL stylesheets -
    and failing miserably to produce any decent output using them - I resorted
    to the "if all you have is a hammer everything looks like a nail" approach
    and do it with a Perl module - which suited my competencies far better
    than XSL.</para></section><section><title>Installation</title><para>Docbook-Convert is available on CPAN, and the latest code will
    always be on GitHub. Install via the following commands:</para><screen>#  Clone repo
#
git clone https://github.com/aspeer/pm-Docbook-Convert.git
cd pm-Docbook-Convert

# Make sure the expat-devel code in installed
#
dnf install expat-devel  # Fedora
apt-get install libexpat1-dev # Debian

# If on a modern system
cpan .

# Or with cpanminus (better)
cpanm .

# Failing that
perl Makefile.PL
make
make test
make install</screen></section><section><title>Usage</title><para>For full usage instructions see the man page. A quick
    example:</para><screen>#  Convert to markdown
#
docbook2md manpage.xml > manpage.md

#  Convert to POD
#
docbook2pod manpage.xml > manpage.pod

#  More options using the docbook-convert, e.g convert docbook 
#  to pod and install into myfile.pl
#
docbook-convert --pod --merge myfile.pl.xml</screen></section><section><title>Dependencies</title><para>Docbook::Convert depends heavily on XML::Twig and some other Perl
    modules. All dependencies are listed in the Makefile.PL and will be
    installed automatically assuming Internet connectivity.</para><para>XML::Twig makes use of XML::Parser which needs the <link xlink:href="https://libexpat.github.io" xmlns:xlink="http://www.w3.org/1999/xlink">Expat XML Parser library</link>
    installed. Use of system libraries via DNF on Fedora/Redhat or apt-get in
    Debian will satisfy the dependency.</para></section><section><title>LICENSE and COPYRIGHT</title><para>This file is part of Docbook::Convert.</para><para>This software is copyright (c) 2025 by Andrew Speer &lt;andrew.speer@isolutions.com.au>.</para><para>This is free software; you can redistribute it and/or modify it underthe same terms as the Perl 5 programming language system itself.</para><para>Full license text is available at:</para><para>&lt;http://dev.perl.org/licenses/></para></section></article>