I filed this RFP to WNPP a couple of days ago (bug #185295), but I think this package is so worthwhile I wanted to also bring it to your attention at debian-devel. * Package name : docbook2x Version : 0.7.0 Upstream Author : Steve Cheng <stevecheng@users.sourceforge.net> * URL : http://sourceforge.net/projects/docbook2x/ * License : GPL Description : converts DocBook documents into man pages and Texinfo docs docbook2X converts DocBook documents into man pages and Texinfo documents. . It aims to support DocBook version 4.1, excepting the features that cannot be supported or are unlikely to be useful for a man-page or Texinfo rendering. ===================================================== Motivation for this package: In Debian we are encouraged to use DocBook to create man pages for our binaries, since this provides the greatest flexibility for converting the documentation to any number of various formats: HTML, info, PDF, TeX, as well as man page format. However, while there are a number of different stylesheets and packages available for converting to most of these formats, there is currently in Debian only one which converts DocBook to a man page, docbook-to-man. (xmltoman has also recently arrived in the archive, but it is based on an unpublished proprietry XML DTD, rather than using DocBook). There are problems with docbook-to-man. It is not maintained upstream (has not been touched since June 14, 1996), and is buggy in a number of ways. Not all DocBook information is adequately converted to the man page, there are errors closing scope of nroff fields in the man page. Conversion is performed using some opaque table system called transpec that seems to make maintenance difficult in principle. Newer versions of DocBook (in particular, the new XML based edition) are not supported. docbook2X seems to deal with all of these inadequacies in docbook-to-man. Although not actively maintained, it is more recent (2001-08-05). It handles both XML and SGML versions of DocBook (the tools assume XML, and provide a command line option to choose SGML). The formatting problem and data loss problems of docbook-to-man are not present. The system is written in perl and therefore accessible to moderately competent programmers. Currently the system requires a minor degree of perl tweaking to fit in with Debian's perl setup. I can provide my own hacks if you require them. docbook2X also has two parts for "historical reasons", one (docbook2manxml) to convert DocBook to an intermediate XML manpage format, and the other (db2x_manxml) to convert from that XML format to the final man page (nroff output). I would recommend providing a glue script to run both these commands transparently to provide one command for users to run. This might also require a small degree of perl hacking to get the two docbook2X commands writing pipewise to stdout by default rather than writing to file by default (I can provide my preliminary changes). Note that the SourceForge project page for docbook2X refers to two projects, docbook2X and docbook2man-sgmlspl. The latter appears to be an experimental attempt to provide another DocBook-to-man convertor, but it seems unfinished and has problems distinguishing XML from SGML. docbook2X is the project we want to use. In fact the docbook2man-sgmlspl docs say "New projects are recommended to use docbook2manxml from docbook2X (a separate package) instead, which is superior to this tool." I don't feel I have enough time right now to finish this package up myself, but I think it would be extremely beneficial to us. Maybe I'll get time for it later if no one steps in before then. I hope others agree this package is worthwhile. Drew Parsons -- PGP public key available at http://people.debian.org/~dparsons/drewskey.txt Fingerprint: A110 EAE1 D7D2 8076 5FE0 EC0A B6CE 7041 6412 4E4A
Attachment:
pgplTJ1k0VzC1.pgp
Description: PGP signature