Re: [PATCH 3/3] Documentation: convert tutorials to man pages
- From
- J. Bruce Fields <bfields@fieldses.org>
- Date
- May 2, 2008, 14:31 UTC
- Message-ID
- <20080502143118.GB16959@fieldses.org>
- In-Reply-To
- <20080502124900.GA2923@sigill.intra.peff.net>
On Fri, May 02, 2008 at 08:49:01AM -0400, Jeff King wrote:
Show 24 quoted lines
> 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).
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?).
Show 7 quoted lines
> 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.