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

On Fri, May 02, 2008 at 08:49:01AM -0400, Jeff King wrote:

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

quoted

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

I'm with Jakub--I always found it awkward reading all that perl
documentation with man.

But I think that's outweighed by the advantages of much easier
cross-referencing.  (Sure, git(7) can tell them to fire up a web browser
and go find tutorial.html.  If you're lucky, your distro installed it
someplace, but where?  And it seems much more polite to refer them to
something that can be read with the same program they're already using.)

it seems rude to reference documents
in the man pages without giving users an immediate way to find them (if
you're lucky then your distro installed them someplace, but where?).

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

Yeah, that would be nice if it were easy to do.

--b.