From: Jeff King <peff@peff.net>
Date: Fri, 02 May 2008 12:49:01 GMT
Subject: Re: [PATCH 3/3] Documentation: convert tutorials to man pages
Message-ID: <20080502124900.GA2923@sigill.intra.peff.net>
In-Reply-To: <8fe92b430805020255r1a06e169te583c371bde83ade@mail.gmail.com>

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

> On 5/2/08, Christian Couder <chriscool@tuxfamily.org> wrote:
> > 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