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

From: Jeff King <peff@peff.net>
Date: May 2, 2008, 12:49 UTC
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:

Show 15 quoted lines

> 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