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@xxxxxxxxxxxxx> 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.
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
