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

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

[Christian Couder]

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

Other documents that reference the above ones are change accordingly.

In "giteveryday.txt" some changes were needed to make links inside
the document accepted by the documentation tool chain.

Signed-off-by: Christian Couder <chriscool@tuxfamily.org>
---
 Documentation/Makefile                             |    9 +--
 Documentation/core-tutorial.txt                    |    4 +-
 Documentation/git.txt                              |   12 ++--
 .../{cvs-migration.txt => gitcvs-migration.txt}    |   68 ++++++++++++------
 Documentation/{everyday.txt => giteveryday.txt}    |   76 +++++++++++++-------
 .../{tutorial-2.txt => gittutorial-2.txt}          |   35 +++++++--
 Documentation/{tutorial.txt => gittutorial.txt}    |   40 ++++++++---
 Documentation/user-manual.txt                      |   18 +++---
 8 files changed, 175 insertions(+), 87 deletions(-)
 rename Documentation/{cvs-migration.txt => gitcvs-migration.txt} (83%)
 rename Documentation/{everyday.txt => giteveryday.txt} (89%)
 rename Documentation/{tutorial-2.txt => gittutorial-2.txt} (95%)
 rename Documentation/{tutorial.txt => gittutorial.txt} (96%)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 4144d1e..9a8043f 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -3,7 +3,8 @@ MAN1_TXT= \
 		$(wildcard git-*.txt)) \
 	gitk.txt
 MAN5_TXT=gitattributes.txt gitignore.txt gitmodules.txt githooks.txt
-MAN7_TXT=git.txt gitcli.txt
+MAN7_TXT=git.txt gitcli.txt gittutorial.txt gittutorial-2.txt \
+	gitcvs-migration.txt giteveryday.txt
 
 MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)
 MAN_XML=$(patsubst %.txt,%.xml,$(MAN_TXT))
@@ -11,14 +12,10 @@ MAN_HTML=$(patsubst %.txt,%.html,$(MAN_TXT))
 
 DOC_HTML=$(MAN_HTML)
 
-ARTICLES = tutorial
-ARTICLES += tutorial-2
-ARTICLES += core-tutorial
-ARTICLES += cvs-migration
+ARTICLES = core-tutorial
 ARTICLES += diffcore
 ARTICLES += howto-index
 ARTICLES += repository-layout
-ARTICLES += everyday
 ARTICLES += git-tools
 ARTICLES += glossary
 # with their own formatting rules.
diff --git a/Documentation/core-tutorial.txt b/Documentation/core-tutorial.txt
index 5a55312..b50b5dd 100644
--- a/Documentation/core-tutorial.txt
+++ b/Documentation/core-tutorial.txt
@@ -8,7 +8,7 @@ This tutorial explains how to use the "core" git programs to set up and
 work with a git repository.
 
 If you just need to use git as a revision control system you may prefer
-to start with link:tutorial.html[a tutorial introduction to git] or
+to start with linkgit:gittutorial[7][a tutorial introduction to git] or
 link:user-manual.html[the git user manual].
 
 However, an understanding of these low-level tools can be helpful if
@@ -1581,7 +1581,7 @@ suggested in the previous section may be new to you. You do not
 have to worry. git supports "shared public repository" style of
 cooperation you are probably more familiar with as well.
 
-See link:cvs-migration.html[git for CVS users] for the details.
+See linkgit:gitcvs-migration[7][git for CVS users] for the details.
 
 Bundling your work together
 ---------------------------
diff --git a/Documentation/git.txt b/Documentation/git.txt
index adcd3e0..1c3c56e 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -20,12 +20,12 @@ Git is a fast, scalable, distributed revision control system with an
 unusually rich command set that provides both high-level operations
 and full access to internals.
 
-See this link:tutorial.html[tutorial] to get started, then see
-link:everyday.html[Everyday Git] for a useful minimum set of commands, and
-"man git-commandname" for documentation of each command.  CVS users may
-also want to read link:cvs-migration.html[CVS migration].  See
-link:user-manual.html[Git User's Manual] for a more in-depth
-introduction.
+See this linkgit:gittutorial[7][tutorial] to get started, then see
+linkgit:giteveryday[7][Everyday Git] for a useful minimum set of
+commands, and "man git-commandname" for documentation of each command.
+CVS users may also want to read linkgit:gitcvs-migration[7][CVS
+migration].  See link:user-manual.html[Git User's Manual] for a more
+in-depth introduction.
 
 The COMMAND is either a name of a Git command (see below) or an alias
 as defined in the configuration file (see linkgit:git-config[1]).
diff --git a/Documentation/cvs-migration.txt b/Documentation/gitcvs-migration.txt
similarity index 83%
rename from Documentation/cvs-migration.txt
rename to Documentation/gitcvs-migration.txt
index 374bc87..4e5ea33 100644
--- a/Documentation/cvs-migration.txt
+++ b/Documentation/gitcvs-migration.txt
@@ -1,14 +1,25 @@
-git for CVS users
-=================
+gitcvs-migration(7)
+===================
 
-Git differs from CVS in that every working tree contains a repository with
-a full copy of the project history, and no repository is inherently more
-important than any other.  However, you can emulate the CVS model by
-designating a single shared repository which people can synchronize with;
-this document explains how to do that.
+NAME
+----
+gitcvs-migration - git for CVS users
+
+SYNOPSIS
+--------
+git cvsimport *
+
+DESCRIPTION
+-----------
+
+Git differs from CVS in that every working tree contains a repository
+with a full copy of the project history, and no repository is
+inherently more important than any other.  However, you can emulate
+the CVS model by designating a single shared repository which people
+can synchronize with; this document explains how to do that.
 
 Some basic familiarity with git is required.  This
-link:tutorial.html[tutorial introduction to git] and the
+linkgit:gittutorial[7][tutorial introduction to git] and the
 link:glossary.html[git glossary] should be sufficient.
 
 Developing against a shared repository
@@ -30,19 +41,20 @@ $ git pull origin
 ------------------------------------------------
 
 which merges in any work that others might have done since the clone
-operation.  If there are uncommitted changes in your working tree, commit
-them first before running git pull.
+operation.  If there are uncommitted changes in your working tree,
+commit them first before running git pull.
 
 [NOTE]
 ================================
 The `pull` command knows where to get updates from because of certain
 configuration variables that were set by the first `git clone`
-command; see `git config -l` and the linkgit:git-config[1] man
-page for details.
+command; see `git config -l` and the linkgit:git-config[1] man page
+for details.
 ================================
 
-You can update the shared repository with your changes by first committing
-your changes, and then using the linkgit:git-push[1] command:
+You can update the shared repository with your changes by first
+committing your changes, and then using the linkgit:git-push[1]
+command:
 
 ------------------------------------------------
 $ git push origin master
@@ -71,12 +83,12 @@ Setting Up a Shared Repository
 
 We assume you have already created a git repository for your project,
 possibly created from scratch or from a tarball (see the
-link:tutorial.html[tutorial]), or imported from an already existing CVS
-repository (see the next section).
+linkgit:gittutorial[7][tutorial]), or imported from an already
+existing CVS repository (see the next section).
 
-Assume your existing repo is at /home/alice/myproject.  Create a new "bare"
-repository (a repository without a working tree) and fetch your project into
-it:
+Assume your existing repo is at /home/alice/myproject.  Create a new
+"bare" repository (a repository without a working tree) and fetch your
+project into it:
 
 ------------------------------------------------
 $ mkdir /pub/my-repo.git
@@ -136,12 +148,13 @@ Advanced Shared Repository Management
 -------------------------------------
 
 Git allows you to specify scripts called "hooks" to be run at certain
-points.  You can use these, for example, to send all commits to the shared
-repository to a mailing list.  See linkgit:githooks[5][Hooks used by git].
+points.  You can use these, for example, to send all commits to the
+shared repository to a mailing list.  See linkgit:githooks[5][Hooks
+used by git].
 
 You can enforce finer grained permissions using update hooks.  See
-link:howto/update-hook-example.txt[Controlling access to branches using
-update hooks].
+link:howto/update-hook-example.txt[Controlling access to branches
+using update hooks].
 
 Providing CVS Access to a git Repository
 ----------------------------------------
@@ -170,3 +183,12 @@ variants of this model.
 
 With a small group, developers may just pull changes from each other's
 repositories without the need for a central maintainer.
+
+SEE ALSO
+--------
+linkgit:gittutorial[7], linkgit:gittutorial-2[7],
+linkgit:giteveryday[7], link:user-manual.html[The Git User's Manual]
+
+GIT
+---
+Part of the linkgit:git[7] suite.
diff --git a/Documentation/everyday.txt b/Documentation/giteveryday.txt
similarity index 89%
rename from Documentation/everyday.txt
rename to Documentation/giteveryday.txt
index e598cdd..d7c3a35 100644
--- a/Documentation/everyday.txt
+++ b/Documentation/giteveryday.txt
@@ -1,27 +1,39 @@
-Everyday GIT With 20 Commands Or So
-===================================
+giteveryday(7)
+==============
 
-<<Basic Repository>> commands are needed by people who have a
-repository --- that is everybody, because every working tree of
-git is a repository.
+NAME
+----
+giteveryday - Everyday GIT With 20 Commands Or So
 
-In addition, <<Individual Developer (Standalone)>> commands are
-essential for anybody who makes a commit, even for somebody who
-works alone.
+SYNOPSIS
+--------
+git *
 
-If you work with other people, you will need commands listed in
-the <<Individual Developer (Participant)>> section as well.
+DESCRIPTION
+-----------
 
-People who play the <<Integrator>> role need to learn some more
-commands in addition to the above.
+<<Basic_Repository,'Basic Repository'>> commands are needed by people
+who have a repository --- that is everybody, because every working
+tree of git is a repository.
 
-<<Repository Administration>> commands are for system
-administrators who are responsible for the care and feeding
-of git repositories.
+In addition, <<Individual_Developer_Standalone,'Individual Developer
+(Standalone)'>> commands are essential for anybody who makes a commit,
+even for somebody who works alone.
+
+If you work with other people, you will need commands listed in the
+<<Individual_Developer_Participant,'Individual Developer
+(Participant)'>> section as well.
+
+People who play the <<Integrator,'Integrator'>> role need to learn
+some more commands in addition to the above.
 
+<<Repository_Administration,'Repository Administration'>> commands are
+for system administrators who are responsible for the care and feeding
+of git repositories.
 
-Basic Repository[[Basic Repository]]
-------------------------------------
+[[Basic_Repository]]
+Basic Repository
+----------------
 
 Everybody uses these commands to maintain git repositories.
 
@@ -60,8 +72,9 @@ $ git gc <1>
 then remove the other packs.
 
 
-Individual Developer (Standalone)[[Individual Developer (Standalone)]]
-----------------------------------------------------------------------
+[[Individual_Developer_Standalone]]
+Individual Developer (Standalone)
+---------------------------------
 
 A standalone individual developer does not exchange patches with
 other people, and works alone in a single repository, using the
@@ -147,8 +160,9 @@ combined and include `\--max-count=10` (show 10 commits),
 directory, since `v2.43` tag.
 
 
-Individual Developer (Participant)[[Individual Developer (Participant)]]
-------------------------------------------------------------------------
+[[Individual_Developer_Participant]]
+Individual Developer (Participant)
+----------------------------------
 
 A developer working as a participant in a group project needs to
 learn how to communicate with others, and uses these commands in
@@ -248,8 +262,9 @@ tag.
 without a formal "merging".
 
 
-Integrator[[Integrator]]
-------------------------
+[[Integrator]]
+Integrator
+----------
 
 A fairly central person acting as the integrator in a group
 project receives changes made by others, reviews and integrates
@@ -335,8 +350,9 @@ everything `ko-next` has.
 <13> push the tag out, too.
 
 
-Repository Administration[[Repository Administration]]
-------------------------------------------------------
+[[Repository_Administration]]
+Repository Administration
+-------------------------
 
 A repository administrator uses the following tools to set up
 and maintain access to the repository by developers.
@@ -454,3 +470,13 @@ ftp> cp -r .git /home/user/myproject.git
 +
 <1> make sure your info/refs and objects/info/packs are up-to-date
 <2> upload to public HTTP server hosted by your ISP.
+
+SEE ALSO
+--------
+linkgit:gittutorial[7], linkgit:gittutorial-2[7],
+linkgit:gitcvs-migration[7], link:user-manual.html[The Git User's
+Manual]
+
+GIT
+---
+Part of the linkgit:git[7] suite.
diff --git a/Documentation/tutorial-2.txt b/Documentation/gittutorial-2.txt
similarity index 95%
rename from Documentation/tutorial-2.txt
rename to Documentation/gittutorial-2.txt
index 7fac47d..4af9073 100644
--- a/Documentation/tutorial-2.txt
+++ b/Documentation/gittutorial-2.txt
@@ -1,8 +1,19 @@
-A tutorial introduction to git: part two
-========================================
+gittutorial-2(7)
+==============
 
-You should work through link:tutorial.html[A tutorial introduction to
-git] before reading this tutorial.
+NAME
+----
+gittutorial-2 - A tutorial introduction to git: part two
+
+SYNOPSIS
+--------
+git *
+
+DESCRIPTION
+-----------
+
+You should work through linkgit:gittutorial[7][A tutorial introduction
+to git] before reading this tutorial.
 
 The goal of this tutorial is to introduce two fundamental pieces of
 git's architecture--the object database and the index file--and to
@@ -387,14 +398,14 @@ What next?
 
 At this point you should know everything necessary to read the man
 pages for any of the git commands; one good place to start would be
-with the commands mentioned in link:everyday.html[Everyday git].  You
-should be able to find any unknown jargon in the
+with the commands mentioned in linkgit:giteveryday[7][Everyday git].
+You should be able to find any unknown jargon in the
 link:glossary.html[Glossary].
 
 The link:user-manual.html[Git User's Manual] provides a more
 comprehensive introduction to git.
 
-The link:cvs-migration.html[CVS migration] document explains how to
+The linkgit:gitcvs-migration[7][CVS migration] document explains how to
 import a CVS repository into git, and shows how to use git in a
 CVS-like way.
 
@@ -404,3 +415,13 @@ link:howto-index.html[howtos].
 For git developers, the link:core-tutorial.html[Core tutorial] goes
 into detail on the lower-level git mechanisms involved in, for
 example, creating a new commit.
+
+SEE ALSO
+--------
+linkgit:gittutorial[7], linkgit:giteveryday[7],
+linkgit:gitcvs-migration[7], link:user-manual.html[The Git User's
+Manual]
+
+GIT
+---
+Part of the linkgit:git[7] suite.
diff --git a/Documentation/tutorial.txt b/Documentation/gittutorial.txt
similarity index 96%
rename from Documentation/tutorial.txt
rename to Documentation/gittutorial.txt
index e2bbda5..470f7f7 100644
--- a/Documentation/tutorial.txt
+++ b/Documentation/gittutorial.txt
@@ -1,12 +1,24 @@
-A tutorial introduction to git (for version 1.5.1 or newer)
-===========================================================
+gittutorial(7)
+==============
+
+NAME
+----
+gittutorial - A tutorial introduction to git (for version 1.5.1 or newer)
+
+SYNOPSIS
+--------
+git *
+
+DESCRIPTION
+-----------
 
 This tutorial explains how to import a new project into git, make
 changes to it, and share changes with other developers.
 
-If you are instead primarily interested in using git to fetch a project,
-for example, to test the latest version, you may prefer to start with
-the first two chapters of link:user-manual.html[The Git User's Manual].
+If you are instead primarily interested in using git to fetch a
+project, for example, to test the latest version, you may prefer to
+start with the first two chapters of link:user-manual.html[The Git
+User's Manual].
 
 First, note that you can get documentation for a command such as "git
 diff" with:
@@ -381,7 +393,7 @@ see linkgit:git-pull[1] for details.
 
 Git can also be used in a CVS-like mode, with a central repository
 that various users push changes to; see linkgit:git-push[1] and
-link:cvs-migration.html[git for CVS users].
+linkgit:gitcvs-migration[7][git for CVS users].
 
 Exploring history
 -----------------
@@ -560,7 +572,7 @@ is based:
     used to create commits, check out working directories, and
     hold the various trees involved in a merge.
 
-link:tutorial-2.html[Part two of this tutorial] explains the object
+linkgit:gittutorial-2[7][Part two of this tutorial] explains the object
 database, the index file, and a few other odds and ends that you'll
 need to make the most of git.
 
@@ -579,6 +591,16 @@ digressions that may be interesting at this point are:
     smart enough to perform a close-to-optimal search even in the
     case of complex non-linear history with lots of merged branches.
 
-  * link:everyday.html[Everyday GIT with 20 Commands Or So]
+  * linkgit:giteveryday[7][Everyday GIT with 20 Commands Or So]
+
+  * linkgit:gitcvs-migration[7][git for CVS users].
+
+SEE ALSO
+--------
+linkgit:gittutorial-2[7], linkgit:giteveryday[7],
+linkgit:gitcvs-migration[7], link:user-manual.html[The Git User's
+Manual]
 
-  * link:cvs-migration.html[git for CVS users].
+GIT
+---
+Part of the linkgit:git[7] suite.
diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index e2db850..b2c4f2c 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -1988,22 +1988,22 @@ way to publish a work-in-progress patch series, and it is an acceptable
 compromise as long as you warn other developers that this is how you
 intend to manage the branch.
 
-It's also possible for a push to fail in this way when other people have
-the right to push to the same repository.  In that case, the correct
-solution is to retry the push after first updating your work by either a
-pull or a fetch followed by a rebase; see the
+It's also possible for a push to fail in this way when other people
+have the right to push to the same repository.  In that case, the
+correct solution is to retry the push after first updating your work
+by either a pull or a fetch followed by a rebase; see the
 <<setting-up-a-shared-repository,next section>> and
-link:cvs-migration.html[git for CVS users] for more.
+linkgit:gitcvs-migration[7][git for CVS users] for more.
 
 [[setting-up-a-shared-repository]]
 Setting up a shared repository
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Another way to collaborate is by using a model similar to that
-commonly used in CVS, where several developers with special rights
-all push to and pull from a single shared repository.  See
-link:cvs-migration.html[git for CVS users] for instructions on how to
-set this up.
+commonly used in CVS, where several developers with special rights all
+push to and pull from a single shared repository.  See
+linkgit:gitcvs-migration[7][git for CVS users] for instructions on how
+to set this up.
 
 However, while there is nothing wrong with git's support for shared
 repositories, this mode of operation is not generally recommended,
-- 
1.5.5.1.124.g7e5fa.dirty

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

[Jakub Narebski]

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

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

[Jeff King]

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

which is basically the same thing (funny name, and very long). 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 (though I would
argue that it should remain "tutorial.txt" and "tutorial.html", but
generate "gittutorial.1").

-Peff

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

[J. Bruce Fields]

On Fri, May 02, 2008 at 08:49:01AM -0400, Jeff King wrote:
> 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
> 
> which is basically the same thing (funny name, and very long).

I'm with Jakub--I always found it awkward reading all that perl
documentation with man.

But I think that's outweighed by the advantages of much easier
cross-referencing.  (Sure, git(7) can tell them to fire up a web browser
and go find tutorial.html.  If you're lucky, your distro installed it
someplace, but where?  And it seems much more polite to refer them to
something that can be read with the same program they're already using.)

it seems rude to reference documents
in the man pages without giving users an immediate way to find them (if
you're lucky then your distro installed them someplace, but where?).

> 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 (though I would
> argue that it should remain "tutorial.txt" and "tutorial.html", but
> generate "gittutorial.1").

Yeah, that would be nice if it were easy to do.

--b.

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

[Christian Couder]

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.

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

[Junio C Hamano]

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.

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

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

[Christian Couder]

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.
 

Re: Documentation status

[Junio C Hamano]

Christian Couder <chriscool@tuxfamily.org> writes:

> 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) ?

Please step back a bit.  What's the reason why you need to make everything
into manpages?

Re: Documentation status

[Jakub Narebski]

Junio C Hamano wrote:
> Christian Couder <chriscool@tuxfamily.org> writes:
[...] 
>> Ok, I will do that.
>> Then what about tutorials (that I put in section 7) ?
> 
> Please step back a bit.  What's the reason why you need to make
> everything into manpages?

I think the main idea was to make into manpages all documentation which 
is referenced from manpages, perhaps with the exception of 
documentation listed in git(7)/git(1).

This way one use man viewer such as 'pinfo', and follow references to 
other manpages...

-- 
Jakub Narebski
Poland

Re: Documentation status

[Christian Couder]

Le lundi 5 mai 2008, Junio C Hamano a écrit :
> Christian Couder <chriscool@tuxfamily.org> writes:
> > Le samedi 3 mai 2008, Junio C Hamano a écrit :
> >>
> >> 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) ?
>
> Please step back a bit.  What's the reason why you need to make
> everything into manpages?

Some people prefer to use man pages and they like it when all the 
documentation is available as man pages.

Regards,
Christian.