I propose that OpenSSL move to DocBook, an XML format, for its
documentation. DocBook (www.docbook.org) is an XML language for
structured/technical documentation. It includes XSLT stylesheets to
convert docbook into many formats, including: roff manpages, HTML pages, a
single HTML document, PDF (via an XSL format known as XSL-FO), etc. Moving
forward, it provides true semantic markup, so that richer documentation
(cross-references, various tables and summaries) are possible.
There are tools to convert from POD to DocBook; Dave Pawson has run them,
and done a bit of cleanup, including making an overall "book" document so
that a single document can be generated.
>From a practical viewpoint, in order to generate documentation from
DocBook files, a user would need the DocBook XSLT files and an XSLT
package, such as Apache Xalan/Xerces, or what's bundled in .NET for
windows, e.g. This is admittedly a bigger requirement than the current
'perl POD package.' There are two ways to address this. First, I think
the distribution could include, e.g., the single HTML documentation
generated from the DocBook files, as well as the DocBook source. Second,
it is possible to also generate POD files from DocBook, and therefore keep
the current distro contents. I think this is not a good idea, however.
If the core team decided to do this, I have some cycles to help.
/r$
--
SOA Appliances
Application Integration Middleware
______________________________________________________________________
OpenSSL Project http://www.openssl.org
Development Mailing List [email protected]
Automated List Manager [EMAIL PROTECTED]
