cURL / Mailing Lists / curl-users / Single Mail

curl-users

Re: [devel] curl.1 manual restructuring (exampes, POD)

From: Daniel Stenberg <daniel_at_haxx.se>
Date: Fri, 2 Mar 2007 22:24:49 +0100 (CET)

On Fri, 2 Mar 2007, Jari Aalto wrote:

> Cons:
> - Manual gets lengthy

I don't consider that much of a problem, as long as the information we add
makes curl easier to understand and use.

> - rewrite curl.1 into curl.1.pod
> - edit the *pod from now on
> - convert *.pod into other formats (.txt, .html, .1)

I don't think we should do pod => html but instead continue to do .1 => html,
as we can then remain using roffit. Unless something has happened to the pod
=> html conversion that now makes it produce nicer html than what roffit does.

Also, if you could convert at least a small part of the curl.1 man page and
show us that the pod format really is good enough and can produce a fine
man-page looking .1 file.

> - Productivity and ease of maintenance is improved at least
> by 10x

What metric are you using when you claim 10x? Being the number one man page
editor, I must confess that I do expect that pod outperforms .1 in the long
run, but at least initially it will cause a productivity decrease and in the
long run it'll only slightly improve it since I have no problems using the .1
format.

> - Introduces dependency to standard Perl

That's not a problem, since the .1 file would be generated at release-time and
we already require perl to build a release.

> If you compare how much effort it wouls take editing between these
> two:
>
> http://cante.net/~jaalto/tmp/curl/
> http://cante.net/~jaalto/tmp/curl/manualpage.1.pod
> http://cante.net/~jaalto/tmp/curl/manualpage.1
>
> I'm sure that brings a revelating experience. Note, that those
> files are not final, just a working copy.

I strongly object to that comparison. The nroff file you show there was
clearly generated by some kind of tool that has messed it up beyond all sense.
No hand-edited nroff file would look like that, as all the existing nroff
files in the curl distro will show.

I'm a bit reluctant to this suggestion for these reasons:

  o this doesn't take into account the numerous docs/libcurl/*.3 files, and
    since I am the maintainer of both curl and libcurl I prefer a single man
    page format for all man pages.
  o I have not seen a nice converter, so all nroff => pod would have to be done
    manually.
  o I don't personally have a problem with the nroff format, even though it
    certainly isn't the smoothest or smartest format available

This said, if people are in favour of pod files and we can do the transition
to pod without too much of the conversion job ends up on my desk, then I don't
see any major arguments against.

-- 
  Commercial curl and libcurl Technical Support: http://haxx.se/curl.html
Received on 2007-03-02