[I've discussed the issue with Daniel and now moving the issue here]

INTRODUCTION

    The current curl.1 manual contains very technical specification
    and virtually no instructions how the tool is used. This measn
    that the user learning curl needs to GOOGLE and run around web in
    order to understand what curl is good for.

    Statistics (From Debian/unstable). Values should not be considered
    absolute:

          64 lines of description
        1000 lines of option documentation
         185 lines of environment, exit codes and all the rest

    The problem: manual needs new section "EXAMPLES".

    THE PLAN

    The material user is really interested to get going is listed in
    <http://curl.haxx.se/docs/manual.html>. This can be used to make
    the EXMAPLES section to the manual.

    Pros:
    - All information is in the manual
    - You can search with your manual browser text backward forward
      for all related information
    - If user has questions, point them to "read the manaul"
    - If anything is lacking "improve the manual".

    Cons:
    - Manual gets lengthy

    However, I believe that the search capabilities outweight greatly the
    the size of the increased manual. It's nice to search backward,
    forward and grep from one canonical place.

THE IMPLEMENTATION

    The manu is currently written in *.1 format. There would be
    a better choice to move to Perl *.pod format. The plan would be

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

    Pros:
    - Productivity and ease of maintenance is improved at least
      by 10x
    - POD is simple, elegant and sufficiently lightweight
      markup language. Docbook or other XML formats would not be be
      really much improvement over *.1 from editing perspective.

    Cons:
    - Introduces dependency to standard Perl

    Given that it is an exception to find Perl installed nowadays, the
    dependency problem is not serious one. And the distributed package
    doe snot need to depend on perl, because the *.1 files can be
    generaed prior release in development environment.

    The great thing about POD is this:

        pod2text manualpage.1.pod > manualpage.txt
        pod2html manualpage.1.pod > manualpage.html
        pod2man manualpage.1.pod > manualpage.1

    From there on other tools to make e.g. PDFs can be used.

WHERE IS THE CODE

    I'll give a taste, how time effective the *.pod format it. It took me
    only some effert to convert:

        http://curl.haxx.se/docs/manual.html'

    into this example:

        http://cante.net/~jaalto/tmp/curl/manualpage.1.pod

    And then:

        pod2text manualpage.1.pod > manualpage.txt
        pod2html manualpage.1.pod > manualpage.html
        pod2man manualpage.1.pod > manualpage.1

    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.

WHAT NEXT

    If the plan looks good, I'll volunteer to make 2nd generation
    curl manual page. With added improvements to include EXAMPLES.

Jari
Received on 2007-03-02