refentry2man

refentry2man homepage

Table of Contents

  1. Intro
  2. Availability
  3. Features
  4. Docs and samples
  5. Build
  6. Future Development
  7. Feedback
  8. Authors

Chapter 1. Intro

refentry2man is a XML DocBook Refentry to manpage fast converter. It is written in C with support of some preprocessing scripts. XML parsing is performed using Expat.

This program is intended to act as on-the-fly converter, for use in modern Linux systems to serve both traditional manpages and their new, structured, DocBook based replacement with the same man command (of course man needs to be slightly modified).
Chapter 2. Availability

The program is free software (GPL).

It is not yet well tested so consider it “alpha” software.

Homepage

http://refentry2man.pld.org.pl. 

Source tarballs

The current version is http://refentry2man.pld.org.pl/download/refentry2man-0.4.tar.gz. Old versions are available via http in http://refentry2man.pld.org.pl/download/. 

Binary

Linux i586 binary distibution is also available (single executable file linked against libexpat.so.0) http://refentry2man.pld.org.pl/download/refentry2man. 

Anonymous CVS

Getting the module (password: “cvs”):

cvs -d :pserver:cvs@anoncvs.pld.org.pl:/cvsroot login
cvs -d :pserver:cvs@anoncvs.pld.org.pl:/cvsroot co refentry2man


Particular files may be accessed via CVSWeb: http://cvs.pld.org.pl/refentry2man/. 

Chapter 3. Features

Very fast.

Handles external entities (including “nested” ones).

Two modes: simple filter mode for single refentry, and multiple files mode for processing whole references.

Proper (I hope ;) ) handling of whitespaces.

Most commonly used elements implemented. 

Chapter 4. Docs and samples

Generally program is just a filter: reads stdin and writes to stdout. Output to multiple files is also allowed. See manual page, it is in doc directory.

In samples directory there are some simple documents presenting usage of particular DocBook elements. Resulting manpages showing how the elements are formatted are included in the tarball as well. If you can not view them directly (e.g. with mc), run make txt to get the .txt files formatted by nroff.
Chapter 5. Build

READ  solidpop3d

Glibc, expat (either old libxmlparse or new libexpat library) and GNU make is needed in order to build package. Standard ./configure; make procedure should compile program. Then make install may be used to place binary and manpage in proper locations.
Chapter 6. Future Development

Package is still under (not very heavy) development, althrough it is already capable enough to handle most of typical manpages. This is open development software. Contibutors are welcome.

See TODO file.
Chapter 7. Feedback

Any feedback (bug reports, feature request) greatly appreciated. (However, I don’t plan to implement all DocBook elements). My address: klakier@pld.org.pl

“Examples” directory waits for complete refentry documents. If you can contribute some real, well-written refentry, please feel free to send it to me.
Chapter 8. Authors

Code:
Rafał Kleger-Rudomin, klakier@pld.org.pl
Automake support:
Tomek Kłoczko
Artur Frysiak