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: Sat, 3 Mar 2007 22:20:26 +0100 (CET)

On Sat, 3 Mar 2007, Jari Aalto wrote:

> 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

Is that initial table of contents meant to contain links? Is it possible to
inhibit that table from the output?

Anyway, in comparison I find the roffit HTML output preferable. Mostly due to
the cross-reference links it adds.

Compare the --anyauth description for example:

   http://curl.haxx.se/docs/manpage.html#--anyauth
   http://cante.net/~jaalto/tmp/curl/curl.1.html#item__2d_2danyauth

Admittedly only a minor difference, but something I myself enjoy quite a bit.

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

I know you didn't, but I am maintaining both curl and libcurl and I really
would like to edit all man pages in the same format and if pod really is a
better format for dealing with man pages than plain nroff, then I figure it
would be better for all man pages. I realize that's a different focus than
what you work against, but still this is my reality.

> The idea was to see improved curl page so that no more extra "curl web
> teaching pages" would be necessary.

Oh, then I think you need to incorporate TheArtOfHttpScripting into it as
well and then we're talking about quite a large man page! ;-)

> Whether POD is adopted project wide, I leave that to the further
> development.

As mentioned already, for me the question is all POD or no POD. And since
there's no volunteers stepping up to covert the other 52(!) man pages, I'm
leaning towards no POD.

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

I would certainly not mind having examples added to the man page.

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