Propose replacing POD with DocBook

classic Classic list List threaded Threaded
18 messages Options
Reply | Threaded
Open this post in threaded view
|

Propose replacing POD with DocBook

Richard Salz
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                       [hidden email]
Automated List Manager                           [hidden email]
Reply | Threaded
Open this post in threaded view
|

Re: Propose replacing POD with DocBook

Bear Giles
> 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.

You can also include unformatted external documents, e.g. configuration
files and source code.  I've used that on a few projects -- it makes it
trivial to update examples without needing to edit the docbook source
itself.

(In fact, iirc some of it was internal documentation for openssl!  It was
stuff like demonstrating the contents of an X509 certificate or a config
file suitable for autopopulating a server certificate via xxx_value=
fields.)

Bear

______________________________________________________________________
OpenSSL Project                                 http://www.openssl.org
Development Mailing List                       [hidden email]
Automated List Manager                           [hidden email]
Reply | Threaded
Open this post in threaded view
|

Re: Propose replacing POD with DocBook

Michael Sierchio
In reply to this post by Richard Salz
Richard Salz wrote:
> I propose that OpenSSL move to DocBook

FWIW, I emphatically support this proposal.

______________________________________________________________________
OpenSSL Project                                 http://www.openssl.org
Development Mailing List                       [hidden email]
Automated List Manager                           [hidden email]
Reply | Threaded
Open this post in threaded view
|

Re: Propose replacing POD with DocBook

Richard Salz
> FWIW, I emphatically support this proposal.

Thanks!

Hope you're doing well.

        /r$

--
SOA Appliances
Application Integration Middleware

______________________________________________________________________
OpenSSL Project                                 http://www.openssl.org
Development Mailing List                       [hidden email]
Automated List Manager                           [hidden email]
Reply | Threaded
Open this post in threaded view
|

Re: Propose replacing POD with DocBook

Michael Sierchio
Richard Salz wrote:
>> FWIW, I emphatically support this proposal.
>
> Thanks!
>
> Hope you're doing well.

I am, thanks.  How are you?  You sorta dropped low on the
radar for a while.

I used to joke: "XML: the new ASN1!"  But I'm happy to be
wrong about that.  Anything -- and I include a clay tablet
and cuneiform implement -- is better than gnuinfo and POD.

I'm trying to do security and privacy consulting, and find
it's really a form of business process reengineering.
Computers and networks are easy,  data classification, policy,
work methods are hard.

Cheers,

Michael
______________________________________________________________________
OpenSSL Project                                 http://www.openssl.org
Development Mailing List                       [hidden email]
Automated List Manager                           [hidden email]
Reply | Threaded
Open this post in threaded view
|

Re: Propose replacing POD with DocBook

Michael Sierchio

Sorry folks, my MUA caused that to go to the list instead of
just Rich.

Cheers,

Michael


______________________________________________________________________
OpenSSL Project                                 http://www.openssl.org
Development Mailing List                       [hidden email]
Automated List Manager                           [hidden email]
Reply | Threaded
Open this post in threaded view
|

Re: Propose replacing POD with DocBook

Richard Levitte - VMS Whacker
In reply to this post by Richard Salz
In message <[hidden email]> on Mon, 17 Jul 2006 11:40:01 -0400, Richard Salz <[hidden email]> said:

rsalz> I propose that OpenSSL move to DocBook, an XML format, for its
rsalz> documentation.

I agree completely.  This was actually brought up a while ago by
someone else (was that Dave Pawson, the one you're mentioning below?),
and should probably have been discussed already then.

rsalz> DocBook (www.docbook.org) is an XML language for structured/-
rsalz> technical documentation.  It includes XSLT stylesheets to
rsalz> convert docbook into many formats, including: roff manpages,
rsalz> HTML pages, a single HTML document, PDF (via an XSL format
rsalz> known as XSL-FO), etc. Moving forward, it provides true
rsalz> semantic markup, so that richer documentation
rsalz> (cross-references, various tables and summaries) are possible.

It's actually pretty great, I've dabbed with it before, for a
different project.  I think the only thing that's an obstacle
for me is that the synopsis for C function declarations get quite
complicated at times, and I've found no way to properly markup a
function pointer parameter declaration in such way that it looks
acceptable in the nroff output.  If you have an example or two, I'd
love to see them.

rsalz> There are tools to convert from POD to DocBook; Dave Pawson has
rsalz> run them, and done a bit of cleanup, including making an
rsalz> overall "book" document so that a single document can be
rsalz> generated.

And this is where I'd simply like to say "patches welcome!", but let's
hear a little from the rest of the team first.

Cheers,
Richard

-----
Please consider sponsoring my work on free software.
See http://www.free.lp.se/sponsoring.html for details.

--
Richard Levitte                         [hidden email]
                                        http://richard.levitte.org/

"When I became a man I put away childish things, including
 the fear of childishness and the desire to be very grown up."
                                                -- C.S. Lewis
______________________________________________________________________
OpenSSL Project                                 http://www.openssl.org
Development Mailing List                       [hidden email]
Automated List Manager                           [hidden email]
Reply | Threaded
Open this post in threaded view
|

Re: Propose replacing POD with DocBook

Richard Salz
> I agree completely.  This was actually brought up a while ago by
> someone else (was that Dave Pawson, the one you're mentioning below?),
> and should probably have been discussed already then.

Yes, same guy. :)

> I think the only thing that's an obstacle
> for me is that the synopsis for C function declarations get quite
> complicated at times, and I've found no way to properly markup a
> function pointer parameter declaration in such way that it looks
> acceptable in the nroff output.

If you mail me some examples of what you have now, I'll pass it around and
see if any suggestions for improvement come back.

        /r$

--
SOA Appliances
Application Integration Middleware



______________________________________________________________________
OpenSSL Project                                 http://www.openssl.org
Development Mailing List                       [hidden email]
Automated List Manager                           [hidden email]
Reply | Threaded
Open this post in threaded view
|

Re: Propose replacing POD with DocBook

Dave Pawson-2
In reply to this post by Richard Levitte - VMS Whacker
On 17/07/06, Richard Levitte - VMS Whacker <[hidden email]> wrote:


> It's actually pretty great, I've dabbed with it before, for a
> different project.  I think the only thing that's an obstacle
> for me is that the synopsis for C function declarations get quite
> complicated at times, and I've found no way to properly markup a
> function pointer parameter declaration in such way that it looks
> acceptable in the nroff output.  If you have an example or two, I'd
> love to see them.

Not pretending that I fully understand, but
a pointer to a functions parameter?

**param, that sort of thing?

http://www.docbook.org/tdg/en/html/funcparams.html

Is that any help?

regards

--
Dave Pawson
XSLT XSL-FO FAQ.
http://www.dpawson.co.uk
______________________________________________________________________
OpenSSL Project                                 http://www.openssl.org
Development Mailing List                       [hidden email]
Automated List Manager                           [hidden email]
Reply | Threaded
Open this post in threaded view
|

Re: Propose replacing POD with DocBook

Richard Levitte - VMS Whacker
In message <[hidden email]> on Mon, 17 Jul 2006 19:51:53 +0100, "Dave Pawson" <[hidden email]> said:

dave.pawson> http://www.docbook.org/tdg/en/html/funcparams.html
dave.pawson>
dave.pawson> Is that any help?

That's what I've tried, and it seems like it doesn't add the
parenthesis it should.  I just experimented with the attached foo.xml,
and did the following command do convert:

: ; db2x_xsltproc -s man foo.xml | db2x_manxml

The result is attached as foo.3.  Note that the parameters to the
function pointer don't have parenthesis around them.  And also, the
indentation of the include line is buuuuut-ugly, not quite what I
expected.  Spaces are a little to well obeyed, me thinks...

BTW, I do this on a freshly updated Debian unstable.

Cheers,
Richard

-----
Please consider sponsoring my work on free software.
See http://www.free.lp.se/sponsoring.html for details.

--
Richard Levitte                         [hidden email]
                                        http://richard.levitte.org/

"When I became a man I put away childish things, including
 the fear of childishness and the desire to be very grown up."
                                                -- C.S. Lewis

<?xml version='1.0'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBk XML V4.2//EN"
               "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<refentry>
  <refentryinfo>
    <author>
      <firstname>Richard</firstname>
      <surname>Levitte</surname>
      <contrib>Original author</contrib>
      <email>[hidden email]</email>
    </author>
  </refentryinfo>

  <refmeta>
    <refentrytitle>foo</refentrytitle>
    <manvolnum>3</manvolnum>
  </refmeta>

  <refsynopsisdiv>
    <funcsynopsis>
      <funcsynopsisinfo>
        #include &lt;foo.h&gt;
      </funcsynopsisinfo>
      <funcprototype>
        <funcdef>void <function>sort</function></funcdef>
        <paramdef>int *<parameter>arr</parameter>[]</paramdef>
        <paramdef>int <parameter>(* comp)</parameter>
        <funcparams>int *, int *</funcparams></paramdef>
      </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>
</refentry>

.TH foo 3  
.SH SYNOPSIS
.nf
#include <foo.h>
.fi
.sp 1
.PP
void \fIsort\fR(int *\fIarr\fR[], int \fI(* comp)\fR
int *, int *);
Reply | Threaded
Open this post in threaded view
|

Re: Propose replacing POD with DocBook

Kyle Hamilton
In reply to this post by Dave Pawson-2
On 7/17/06, Dave Pawson <[hidden email]> wrote:

> On 17/07/06, Richard Levitte - VMS Whacker <[hidden email]> wrote:
>
>
> > It's actually pretty great, I've dabbed with it before, for a
> > different project.  I think the only thing that's an obstacle
> > for me is that the synopsis for C function declarations get quite
> > complicated at times, and I've found no way to properly markup a
> > function pointer parameter declaration in such way that it looks
> > acceptable in the nroff output.  If you have an example or two, I'd
> > love to see them.
>
> Not pretending that I fully understand, but
> a pointer to a functions parameter?
>
> **param, that sort of thing?

I think he's referring to something like:

void SSL_CTX_set_client_cert_cb(SSL_CTX *ctx, int
(*client_cert_cb)(SSL *ssl, X509 **x509, EVP_PKEY **pkey));
 int (*SSL_CTX_get_client_cert_cb(SSL_CTX *ctx))(SSL *ssl, X509
**x509, EVP_PKEY **pkey);
 int (*client_cert_cb)(SSL *ssl, X509 **x509, EVP_PKEY **pkey);

Basically, when you're passing a pointer to a function as a parameter
to another function for callbacks and such.

> http://www.docbook.org/tdg/en/html/funcparams.html

There's an example for qsort in there, but there's a problem: it loses
information between the XML and the output.  Specifically, what's
printed is:

void qsort( dataptr,
  dataptr,
  left,
  right,
  (* comp));
  dataptr;
  left;
  right;
int (* comp) (void *, void *);

i.e., it loses type information for dataptr, left, and right.

> Is that any help?

It's a great help for exposition of what the problem is! :)

-Kyle H
______________________________________________________________________
OpenSSL Project                                 http://www.openssl.org
Development Mailing List                       [hidden email]
Automated List Manager                           [hidden email]
Reply | Threaded
Open this post in threaded view
|

Re: Propose replacing POD with DocBook

Dave Pawson-2
On 17/07/06, Kyle Hamilton <[hidden email]> wrote:

> Basically, when you're passing a pointer to a function as a parameter
> to another function for callbacks and such.
>
> > http://www.docbook.org/tdg/en/html/funcparams.html
>
> There's an example for qsort in there, but there's a problem: it loses
> information between the XML and the output.  Specifically, what's
> printed is:
>
> void qsort(     dataptr,
>         dataptr,
>         left,
>         right,
>         (* comp));
>         dataptr;
>         left;
>         right;
> int (* comp) (void *, void *);
>
> i.e., it loses type information for dataptr, left, and right.
>
> > Is that any help?
>
> It's a great help for exposition of what the problem is! :)

Yes, very clear. I've asked the guru's.
Only parameterization is to use K&R or ANSI format (do you understand
the difference?)

WhenI find out how to get them back I'll let you know.
It may be deliberate, but I can't see why.


regards


--
Dave Pawson
XSLT XSL-FO FAQ.
http://www.dpawson.co.uk
______________________________________________________________________
OpenSSL Project                                 http://www.openssl.org
Development Mailing List                       [hidden email]
Automated List Manager                           [hidden email]
Reply | Threaded
Open this post in threaded view
|

Re: Propose replacing POD with DocBook

Dave Pawson-2
In reply to this post by Kyle Hamilton
On 17/07/06, Kyle Hamilton <[hidden email]> wrote:



> > http://www.docbook.org/tdg/en/html/funcparams.html
>
> There's an example for qsort in there, but there's a problem: it loses
> information between the XML and the output.  Specifically, what's
> printed is:
>
> void qsort(     dataptr,
>         dataptr,
>         left,
>         right,
>         (* comp));
>         dataptr;
>         left;
>         right;
> int (* comp) (void *, void *);
>
> i.e., it loses type information for dataptr, left, and right.
>
> > Is that any help?


I just ran that through my rev of the stylesheets and produced


void qsort( dataptr,
  left,
  right,
  comp);
void * dataptr[];
int   left;
int   right;
int (*comp) (void *, void *);



1. I think your version of docbook may be out of date.
2. The example in 'the definitive guide' seems wrong.
3. You get what you want (from what I see? Is that right)

HTH

--
Dave Pawson
XSLT XSL-FO FAQ.
http://www.dpawson.co.uk
______________________________________________________________________
OpenSSL Project                                 http://www.openssl.org
Development Mailing List                       [hidden email]
Automated List Manager                           [hidden email]
Reply | Threaded
Open this post in threaded view
|

Re: Propose replacing POD with DocBook

Kyle Hamilton
In reply to this post by Dave Pawson-2
On 7/17/06, Dave Pawson <[hidden email]> wrote:

> On 17/07/06, Kyle Hamilton <[hidden email]> wrote:
>
> > Basically, when you're passing a pointer to a function as a parameter
> > to another function for callbacks and such.
> >
> > > http://www.docbook.org/tdg/en/html/funcparams.html
> >
> > There's an example for qsort in there, but there's a problem: it loses
> > information between the XML and the output.  Specifically, what's
> > printed is:
> >
> > void qsort(     dataptr,
> >         dataptr,
> >         left,
> >         right,
> >         (* comp));
> >         dataptr;
> >         left;
> >         right;
> > int (* comp) (void *, void *);
> >
> > i.e., it loses type information for dataptr, left, and right.
> >
> > > Is that any help?
> >
> > It's a great help for exposition of what the problem is! :)
>
> Yes, very clear. I've asked the guru's.
> Only parameterization is to use K&R or ANSI format (do you understand
> the difference?)

/* K&R */
int somefunc(x, y)
    char *x, int *y
{ ... return 1; }

/* ANSI */
int somefunc(char *x, int *y)
{ ... return 1; }

Either way, the results of the DocBook conversion lose the type
information for the parameters, so it's not K&R format either.  Since
OpenSSL makes fairly extensive use of callbacks, the need for the
functions that get and set them to be well-documented is extremely
important.

> WhenI find out how to get them back I'll let you know.
> It may be deliberate, but I can't see why.

Neither can I.  The official docs really can't be put into DocBook
until this oversight is corrected -- but there's no reason why initial
work can't be done pending the bugfix.

-Kyle H
______________________________________________________________________
OpenSSL Project                                 http://www.openssl.org
Development Mailing List                       [hidden email]
Automated List Manager                           [hidden email]
Reply | Threaded
Open this post in threaded view
|

Re: Propose replacing POD with DocBook

Kyle Hamilton
In reply to this post by Dave Pawson-2
I would much prefer ANSI notation than K&R notation -- among other
things, all the other manpages use it, and K&R was seriously
underspecified.

That said, though, it looks fairly good as it is now.

[...more after quote...]

On 7/18/06, Dave Pawson <[hidden email]> wrote:

>
> I just ran that through my rev of the stylesheets and produced
>
>
> void qsort(     dataptr,
>         left,
>         right,
>         comp);
> void *  dataptr[];
> int     left;
> int     right;
> int (*comp) (void *, void *);
>
> 1. I think your version of docbook may be out of date.

I was going by the version of the docs on docbook.org.

> 2. The example in 'the definitive guide' seems wrong.

Right. :)

> 3. You get what you want (from what I see? Is that right)

As I said, I'd prefer ANSI notation, but as long as the parameters are
fully specified in the documentation I'll deal. :)

Cheers!

-Kyle H
______________________________________________________________________
OpenSSL Project                                 http://www.openssl.org
Development Mailing List                       [hidden email]
Automated List Manager                           [hidden email]
Reply | Threaded
Open this post in threaded view
|

Re: Propose replacing POD with DocBook

Dave Pawson-2
On 18/07/06, Kyle Hamilton <[hidden email]> wrote:

> As I said, I'd prefer ANSI notation, but as long as the parameters are
> fully specified in the documentation I'll deal. :)


Input

<article>

<section>
<title>Funcparams test</title>

<funcsynopsis>
<funcprototype>
  <funcdef>void <function>qsort</function></funcdef>
    <paramdef>void *<parameter>dataptr</parameter>[]</paramdef>
    <paramdef>int <parameter>left</parameter></paramdef>
    <paramdef>int <parameter>right</parameter></paramdef>
    <paramdef>int (*<parameter>comp</parameter>)
      <funcparams>void *, void *</funcparams></paramdef>
</funcprototype>
</funcsynopsis>

</section>

</article>

Stylesheet, which calls up the basic docbook, and sets
a parm for what you want

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
  xmlns:xdt="http://www.w3.org/2005/02/xpath-datatypes"
                version="1.0">

  <xsl:import href="/sgml/docbook/docbook-xsl/html/docbook.xsl"/>
  <xsl:output method="xml"/>

  <xsl:template match="/">
        <xsl:apply-templates/>
  </xsl:template>



<xsl:param name="funcsynopsis.style">ansi</xsl:param>


</xsl:stylesheet>


output


Funcparams test
void qsort( void * dataptr[],
  int   left,
  int   right,
  int (* comp) (void *, void *));


HTH




--
Dave Pawson
XSLT XSL-FO FAQ.
http://www.dpawson.co.uk
______________________________________________________________________
OpenSSL Project                                 http://www.openssl.org
Development Mailing List                       [hidden email]
Automated List Manager                           [hidden email]
Reply | Threaded
Open this post in threaded view
|

Re: Propose replacing POD with DocBook

Dave Pawson-2
In reply to this post by Kyle Hamilton
http://docbook.org/tdg5/en/html/funcsynopsis.html

Norm thinks he's fixed it.
I can't argue.

Do you guys agree with him,
see the K&R vs Ansi examples?

regards DaveP

(See the support you get with docbook :-)




> > Only parameterization is to use K&R or ANSI format (do you understand
> > the difference?)
>
> /* K&R */
> int somefunc(x, y)
>     char *x, int *y
> { ... return 1; }
>
> /* ANSI */
> int somefunc(char *x, int *y)
> { ... return 1; }
>
> Either way, the results of the DocBook conversion lose the type
> information for the parameters, so it's not K&R format either.  Since
> OpenSSL makes fairly extensive use of callbacks, the need for the
> functions that get and set them to be well-documented is extremely
> important.
>
> > WhenI find out how to get them back I'll let you know.
> > It may be deliberate, but I can't see why.
>
> Neither can I.  The official docs really can't be put into DocBook
> until this oversight is corrected -- but there's no reason why initial
> work can't be done pending the bugfix.
>
> -Kyle H
> ______________________________________________________________________
> OpenSSL Project                                 http://www.openssl.org
> Development Mailing List                       [hidden email]
> Automated List Manager                           [hidden email]
>


--
Dave Pawson
XSLT XSL-FO FAQ.
http://www.dpawson.co.uk
______________________________________________________________________
OpenSSL Project                                 http://www.openssl.org
Development Mailing List                       [hidden email]
Automated List Manager                           [hidden email]
Reply | Threaded
Open this post in threaded view
|

Re: Propose replacing POD with DocBook

Kyle Hamilton
Looks good to me.  Shall we? :)

-Kyle H

On 7/18/06, Dave Pawson <[hidden email]> wrote:

> http://docbook.org/tdg5/en/html/funcsynopsis.html
>
> Norm thinks he's fixed it.
> I can't argue.
>
> Do you guys agree with him,
> see the K&R vs Ansi examples?
>
> regards DaveP
>
> (See the support you get with docbook :-)
>
>
>
>
> > > Only parameterization is to use K&R or ANSI format (do you understand
> > > the difference?)
> >
> > /* K&R */
> > int somefunc(x, y)
> >     char *x, int *y
> > { ... return 1; }
> >
> > /* ANSI */
> > int somefunc(char *x, int *y)
> > { ... return 1; }
> >
> > Either way, the results of the DocBook conversion lose the type
> > information for the parameters, so it's not K&R format either.  Since
> > OpenSSL makes fairly extensive use of callbacks, the need for the
> > functions that get and set them to be well-documented is extremely
> > important.
> >
> > > WhenI find out how to get them back I'll let you know.
> > > It may be deliberate, but I can't see why.
> >
> > Neither can I.  The official docs really can't be put into DocBook
> > until this oversight is corrected -- but there's no reason why initial
> > work can't be done pending the bugfix.
> >
> > -Kyle H
> > ______________________________________________________________________
> > OpenSSL Project                                 http://www.openssl.org
> > Development Mailing List                       [hidden email]
> > Automated List Manager                           [hidden email]
> >
>
>
> --
> Dave Pawson
> XSLT XSL-FO FAQ.
> http://www.dpawson.co.uk
> ______________________________________________________________________
> OpenSSL Project                                 http://www.openssl.org
> Development Mailing List                       [hidden email]
> Automated List Manager                           [hidden email]
>
______________________________________________________________________
OpenSSL Project                                 http://www.openssl.org
Development Mailing List                       [hidden email]
Automated List Manager                           [hidden email]