Le samedi 3 mai 2008, Junio C Hamano a écrit : > Christian Couder <chriscool@xxxxxxxxxxxxx> 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. -- 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
