Re: [PATCH 3/3] Documentation: convert tutorials to man pages

On Fri, May 02, 2008 at 11:55:10AM +0200, Jakub Narebski wrote:

On 5/2/08, Christian Couder [off-list ref] wrote:

quoted

This patch renames the following documents and at the same time converts
 them to the man page format:

 cvs-migration.txt -> gitcvs-migration.txt
 everyday.txt      -> giteveryday.txt
 tutorial.txt      -> gittutorial.txt
 tutorial-2.txt    -> gittutorial-2.txt

I like the rest of the series, but this I have serious doubts about. I think
that manpage format is just not suitable for guides and tutorials (larger
works), especially that we have HTML and beginnings of info versions.

Beside, the filenames looks stupid... githooks would go in a pinch, but
other names...

I don't know about that:

  $ man perlretut | wc -l
  2348

which is basically the same thing (funny name, and very long). At least
for me, looking at a manpage is much more convenient than info or HTML.
It's quick to load and easy to search through. Sure, the HTML will look
a lot nicer. But it seems like if even a few people use the man version,
the almost zero effort to generate them is worth it (though I would
argue that it should remain "tutorial.txt" and "tutorial.html", but
generate "gittutorial.1").

-Peff