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

From: Christian Couder <chriscool@tuxfamily.org>
Date: May 3, 2008, 04:04 UTC
Message-ID: <200805030604.32123.chriscool@tuxfamily.org>
In-Reply-To: <20080502124900.GA2923@sigill.intra.peff.net>

Le vendredi 2 mai 2008, Jeff King a écrit :

Show 22 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

Yeah:

so the 4 tutorials are much shorter than some other man pages and even shorter than the git(7) man page.

> which is basically the same thing (funny name, and very long).

I would even say that the name is better and that the content is sometimes much shorter compared with perl man pages.

Show 5 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

I agree. Sometimes the man pages are the only thing you can easily read.

> (though I would 
> argue that it should remain "tutorial.txt" and "tutorial.html", but
> generate "gittutorial.1").

I am open to suggestions for a better naming and for choosing man page sections, but I think we should be consistent as much as possible.

For example, the man page starts with:

NAME
       gittutorial - A tutorial introduction to git (for version 1.5.1 or
       newer)

If we keep "gittutorial" in the HTML format man page but we still name the file "tutorial.html", we are not very consistent.

And I think it will be some work to get links or references working in both the man format and HTML format man pages, especially if the naming is the same for some files (gitmodules, gitignore, git, gitk, git-log, ...) but not others (tutorial, everyday, ...)

About man page sections, Perl is consistent because every thing is in section 1. Now for git we already have git commands in section 1 and some other documentation (gitattributes, gitignore, gitmodules) in section 5 and "git" in section 7. Do we want to keep "git" alone in section 7 and put tutorials in section 1 ? Or put everything in section 1 ?

Thanks, Christian.