Re: pod2mdoc, docbook2mdoc

[Thomas Klausner <wiz@NetBSD.org>]

Hi Kristaps!

On Thu, Apr 03, 2014 at 02:02:41PM +0200, Kristaps Dzonsons wrote:
> I suggest you check out the latest version... run as:
> 
>  pod2mdoc foo.pm | mandoc
> 
> The output is much nicer than pod2man in the same way.  Lots more semantic
> content as mentioned in the "Smarts" subsection of the manual.  Most
> visibly, since the SYNOPSIS is now rendered with Nm, Oo/Oc, Ar, and Fl,
> mandoc can properly format sections.

Thanks.

I've tried DSA_SIG_new.pod, basically at random. Here's the output:

.Dd July 20, 2009
.Dt DSA_SIG_NEW 1
.Os
.Sh NAME
.Nm DSA_SIG_new ,
.Nm DSA_SIG_free 
.Nd allocate and free DSA signature objects
.Sh SYNOPSIS
.Bd -literal
 #include <openssl/dsa.h>
.Ed
.Bd -literal
 DSA_SIG *DSA_SIG_new(void);
.Ed
.Bd -literal
 void   DSA_SIG_free(DSA_SIG *a);
.Ed
.Sh DESCRIPTION
DSA_SIG_new() allocates and initializes a 
.Sy DSA_SIG
structure.
.Pp
DSA_SIG_free() frees the 
.Sy DSA_SIG
structure and its components. The
values are erased before the memory is returned to the system.
.Sh RETURN VALUES
If the allocation fails, DSA_SIG_new() returns 
.Sy NULL
and sets an
error code that can be obtained by
.Xr ERR_get_error 3 Ns  .
Otherwise it returns a pointer
to the newly allocated structure.
.Pp
DSA_SIG_free() returns no value.
.Sh SEE ALSO
.Xr dsa 3 Ns  ,
.Xr ERR_get_error 3 Ns  ,
.Xr DSA_do_sign 3
.Sh HISTORY
DSA_SIG_new() and DSA_SIG_free() were added in OpenSSL 0.9.3.

It's already quite nice!

Some suggestions:
* foo() -> .Fn foo
* too many Ns before punctuation
* section number is 1 instead of 3 (not sure how to detect that)
* .Bd -literal + #include <foo> + Ed -> .In foo
* splitting up the functions in the SYNOPSIS the same way is probably too much effort?

Related question:
How do people use Sy vs. Dv?

I personally always mark up NULL as a Dv and similarly for most other
defined C symbols.

Thanks,
 Thomas
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv