Daniel Stenberg <daniel_at_haxx.se> writes:
>> - 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.

A proper CSS will do wonders.

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

Heres a sample. I'm no expert in CSS, so this can be made look
whatever is wanted. The HTML:

    http://cante.net/~jaalto/tmp/curl/curl.1.html

And after "nroff -man curl.1" how it looks like when user is reading
"man curl(1)":

    http://cante.net/~jaalto/tmp/curl/curl.1.nroff.txt

Plain text after "pod2text curl.1.pod":

    http://cante.net/~jaalto/tmp/curl/curl.1.txt

All files in:

    http://cante.net/~jaalto/tmp/curl/

> I strongly object to that comparison. The nroff file you show there
> was clearly generated by some kind of tool

Yes, that was the pod2man converter from Perl.

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

Actually I wasn't planning to suggest to convert all manual pages to
.pod.

- I had an itch of missing information from manual
- because manual was in *.1 format, I would not spend time modifying,
  neither patching, it. Too time consuming and error prone for me.
- but in POD, that would motivate to do contributions.
  Possibly encouraging others to do as well.

The idea was to see improved curl page so that no more extra "curl web
teaching pages" would be necessary. Whether POD is adopted project
wide, I leave that to the further development.

What do you think about examples, is it a go?

Jari
Received on 2007-03-03