Documentation status (was Re: [PATCH 3/3] Documentation: convert tutorials to man pages)

[Christian Couder <chriscool@tuxfamily.org>]

Le samedi 3 mai 2008, Junio C Hamano a écrit :
> Christian Couder <chriscool@tuxfamily.org> writes:
> > About man page sections, Perl is consistent because every thing is in
> > section 1.
>
> I do not think it is a good example to follow, though.

I agree.

> > 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 ?
>
> My preference is to move git(7) to git(1) because it is describing a
> command at the end-user level (distros are much better than us to come up
> with a way to deal with conflict resolution between us and the other
> git), keep file format description in section 5 (that's where they belong
> to).

Ok, I will do that.
Then what about tutorials (that I put in section 7) ?

After the patch I just sent and if I move git(7) to git(1) we will have:

Section 1:

git, gitk, git-COMMAND

Section 5:

gitattributes gitignore gitmodules githooks gitdiffcore gitrepository-layout

Section 7:

gitcli gittutorial gittutorial-2 gitcvs-migration giteveryday 
gitcore-tutorial gitglossary

The logic is:

- the commands are in section 1 with a name git-COMMAND
- the documents about files and file formats are in section 5 with a name 
gitSTUFF so that it is different from commands
- the tutorials and manual stuff are in section 7 with a name gitSTUFF so 
that it is different from commands

Jakub suggests to use "git-core-tutorial" instead of "gitcore-tutorial" 
and "git-repository-layout" instead of "gitrepository-layout" but 
that would break the gitSTUFF logic for section 5 and 7, except if we decide 
to name everything git-STUFF in these sections too.

Naming everything "git-STUFF" also makes "git help STUFF" works with no code 
change, and is perhaps more readable.

Then there are also the following documents that I may not convert to man 
pages:

- howto-index:

This file lists and describes the documents in the "howto" directory. There 
are 11 documents in this directory but only 2 of them are converted by the 
Makefile into HTML. And those that are converted have their own formating 
rules according to the Makefile. So in the current state there is no point 
to convert the "howto-index".

- user-manual:

It also has its own formatting rules. But it may be usefull to convert it 
though it will be big (the .txt has 4550 lines).

- git-tools:

It lists and describe the git related tools, but seems a bit outdated and 
does not follow the gitSTUFF convention. 

- technical/*

Only the api-* documents here are converted to HTML and many of them are 
stubs. They have their own formating rules too.

Thanks,
Christian.