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

[Christian Couder <chriscool@tuxfamily.org>]

Le vendredi 2 mai 2008, Jeff King a écrit :
> 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:

$ man perlfunc | wc -l
6708
$ man bash | wc -l
4916
$ man git | wc -l
825
$ man gittutorial | wc -l
691
$ man gittutorial-2 | wc -l
472
$ man giteveryday | wc -l
478
$ man gitcvs-migration | wc -l
201

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. 

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