pm-Docbook-Convert/README at main · aspeer/pm-Docbook-Convert · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
Docbook::Convert - migrate Docbook files to Markdown or POD
===========================================================

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.

Why use XML for documentation ?
===============================

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.

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.

Why not write an XSL stylesheet and use XSLT ?
==============================================

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.

Installation
============

Docbook-Convert is available on CPAN, and the latest code will always be on GitHub. Install via
the following commands:

    #  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

Usage
=====

For full usage instructions see the man page. A quick example:

    #  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

Dependencies
============

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.

XML::Twig makes use of XML::Parser which needs the Expat XML Parser library installed. Use of
system libraries via DNF on Fedora/Redhat or apt-get in Debian will satisfy the dependency.

LICENSE and COPYRIGHT
=====================

This file is part of Docbook::Convert.

This software is copyright (c) 2025 by Andrew Speer <andrew.speer@isolutions.com.au>.

This is free software; you can redistribute it and/or modify it underthe same terms as the Perl
5 programming language system itself.

Full license text is available at:

<http://dev.perl.org/licenses/>