[PATCH] provide a Git user-manual man page

[PATCH] provide a Git user-manual man page

[Philip Oakley]

The Git User Manual is formatted as a doc book, rather than as
a man page so isn't directly accessible via the 'hit help <guide>'
command.

This patch provides a simple man page with onward links to the true
User-Manual. 

The man page is based directly on a very cut down version of the git(1)
page.

This patch is based on master, so the update to the help.c list of
guides may need a simple merge resolution with the 'git help everyday'
patch currently in pu.

Philip Oakley (1):
  Provide a 'git help user-manual' route to the docbook

 Documentation/Makefile           |  1 +
 Documentation/gituser-manual.txt | 34 ++++++++++++++++++++++++++++++++++
 builtin/help.c                   |  1 +
 3 files changed, 36 insertions(+)
 create mode 100644 Documentation/gituser-manual.txt

-- 
1.8.3.msysgit.0

[PATCH] provide a Git user-manual man page

[Philip Oakley]

This is a resend of my original patch ($gman/240486), which disappeared
without comment. I've cc'd those who have touched the User-Manual in
the last year for comment on the provision of this access mechanism.

The Git User Manual is formatted as a doc book, rather than as
a man page so isn't directly accessible via the usual 'git help
<guide>' command.

This patch provides a simple man page with onward links to the true
User-Manual. 

The man page is based directly on a very cut down version of the git(1)
page.

This patch is based on 1.9.0 master.

Philip Oakley (1):
  Provide a 'git help user-manual' route to the docbook

 Documentation/Makefile           |  1 +
 Documentation/gituser-manual.txt | 34 ++++++++++++++++++++++++++++++++++
 builtin/help.c                   |  1 +
 3 files changed, 36 insertions(+)
 create mode 100644 Documentation/gituser-manual.txt

-- 
1.8.3.msysgit.0

[PATCH] Provide a 'git help user-manual' route to the docbook

[Philip Oakley]

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
 Documentation/Makefile           |  1 +
 Documentation/gituser-manual.txt | 34 ++++++++++++++++++++++++++++++++++
 builtin/help.c                   |  1 +
 3 files changed, 36 insertions(+)
 create mode 100644 Documentation/gituser-manual.txt

diff --git a/Documentation/Makefile b/Documentation/Makefile
index fc6b2cf..657523f 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -31,6 +31,7 @@ MAN7_TXT += gitnamespaces.txt
 MAN7_TXT += gitrevisions.txt
 MAN7_TXT += gittutorial-2.txt
 MAN7_TXT += gittutorial.txt
+MAN7_TXT += gituser-manual.txt
 MAN7_TXT += gitworkflows.txt
 
 MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)
diff --git a/Documentation/gituser-manual.txt b/Documentation/gituser-manual.txt
new file mode 100644
index 0000000..9fd4744
--- /dev/null
+++ b/Documentation/gituser-manual.txt
@@ -0,0 +1,34 @@
+gituser-manual(7)
+=================
+
+NAME
+----
+gituser-manual - a link to the user-manual docbook
+
+
+SYNOPSIS
+--------
+[verse]
+'git help user-manual'
+
+link:user-manual.html[Git User's Manual]
+
+DESCRIPTION
+-----------
+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.
+
+The link:user-manual.html[Git User's Manual] provides an
+in-depth introduction to Git.
+
+SEE ALSO
+--------
+linkgit:gittutorial[7],
+linkgit:giteveryday[7],
+linkgit:gitcli[7],
+linkgit:gitworkflows[7]
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/builtin/help.c b/builtin/help.c
index 1fdefeb..be7c39d 100644
--- a/builtin/help.c
+++ b/builtin/help.c
@@ -427,6 +427,7 @@ static struct {
 	{ "modules", N_("Defining submodule properties") },
 	{ "revisions", N_("Specifying revisions and ranges for Git") },
 	{ "tutorial", N_("A tutorial introduction to Git (for version 1.5.1 or newer)") },
+	{ "user-manual", N_("A link to the user-manual docbook") },
 	{ "workflows", N_("An overview of recommended workflows with Git") },
 };
 
-- 
1.8.3.msysgit.0

Re: [PATCH] Provide a 'git help user-manual' route to the docbook

[Junio C Hamano]

Philip Oakley <philipoakley@iee.org> writes:

> diff --git a/Documentation/gituser-manual.txt b/Documentation/gituser-manual.txt
> new file mode 100644
> index 0000000..9fd4744
> --- /dev/null
> +++ b/Documentation/gituser-manual.txt
> @@ -0,0 +1,34 @@
> +gituser-manual(7)
> +=================
> +
> +NAME
> +----
> +gituser-manual - a link to the user-manual docbook
> +
> +
> +SYNOPSIS
> +--------
> +[verse]
> +'git help user-manual'
> +
> +link:user-manual.html[Git User's Manual]

Is it just me, or is typing

	$ git help user-manual

and not seeing the manual itself, but only a link you have to click
to get there a worthwhile addition?

I would not mind having a clickable link in the output from

	$ git help git

or something that does already have other useful information, though.

> +
> +DESCRIPTION
> +-----------
> +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.
> +
> +The link:user-manual.html[Git User's Manual] provides an
> +in-depth introduction to Git.
> +
> +SEE ALSO
> +--------
> +linkgit:gittutorial[7],
> +linkgit:giteveryday[7],
> +linkgit:gitcli[7],
> +linkgit:gitworkflows[7]
> +
> +GIT
> +---
> +Part of the linkgit:git[1] suite
> diff --git a/builtin/help.c b/builtin/help.c
> index 1fdefeb..be7c39d 100644
> --- a/builtin/help.c
> +++ b/builtin/help.c
> @@ -427,6 +427,7 @@ static struct {
>  	{ "modules", N_("Defining submodule properties") },
>  	{ "revisions", N_("Specifying revisions and ranges for Git") },
>  	{ "tutorial", N_("A tutorial introduction to Git (for version 1.5.1 or newer)") },
> +	{ "user-manual", N_("A link to the user-manual docbook") },
>  	{ "workflows", N_("An overview of recommended workflows with Git") },
>  };

Re: [PATCH] Provide a 'git help user-manual' route to the docbook

[Philip Oakley]

From: "Junio C Hamano" <gitster@pobox.com>
> Philip Oakley <philipoakley@iee.org> writes:
>
>> diff --git a/Documentation/gituser-manual.txt 
>> b/Documentation/gituser-manual.txt
>> new file mode 100644
>> index 0000000..9fd4744
>> --- /dev/null
>> +++ b/Documentation/gituser-manual.txt
>> @@ -0,0 +1,34 @@
>> +gituser-manual(7)
>> +=================
>> +
>> +NAME
>> +----
>> +gituser-manual - a link to the user-manual docbook
>> +
>> +
>> +SYNOPSIS
>> +--------
>> +[verse]
>> +'git help user-manual'
>> +
>> +link:user-manual.html[Git User's Manual]
>
> Is it just me, or is typing
>
> $ git help user-manual
>
> and not seeing the manual itself, but only a link you have to click
> to get there a worthwhile addition?

It is a half-way house, partly because the current 'git help <name>' 
processing always assumes that the target is a man page, and that the 
page name will always be 'git<name>. Thus the current user-manual isn't 
immediately visible to the help system. Also it's not (quite reasonably) 
formatted as a man page either.

This was an attempt to offer more ways for users to discover the 
user-manual, as it would also be listed in the 'git help -g' output. To 
make that work required a proper man-page, hence the patch. Also I was 
avoiding the renaming of the user-manual.txt & user-manual.html file 
because of possible link breakages from external sources.

>
> I would not mind having a clickable link in the output from
>
> $ git help git

There is now a link within the git(1) page, though folk maybe leaping 
past it to the list of commands and env variables, etc.

I'm generally in favour of providing more help sign-posting from more 
directions where possible.

>
> or something that does already have other useful information, though.
>
>> +
>> +DESCRIPTION
>> +-----------
>> +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.
>> +
>> +The link:user-manual.html[Git User's Manual] provides an
>> +in-depth introduction to Git.
>> +
>> +SEE ALSO
>> +--------
>> +linkgit:gittutorial[7],
>> +linkgit:giteveryday[7],
>> +linkgit:gitcli[7],
>> +linkgit:gitworkflows[7]
>> +
>> +GIT
>> +---
>> +Part of the linkgit:git[1] suite
>> diff --git a/builtin/help.c b/builtin/help.c
>> index 1fdefeb..be7c39d 100644
>> --- a/builtin/help.c
>> +++ b/builtin/help.c
>> @@ -427,6 +427,7 @@ static struct {
>>  { "modules", N_("Defining submodule properties") },
>>  { "revisions", N_("Specifying revisions and ranges for Git") },
>>  { "tutorial", N_("A tutorial introduction to Git (for version 1.5.1 
>> or newer)") },
>> + { "user-manual", N_("A link to the user-manual docbook") },
>>  { "workflows", N_("An overview of recommended workflows with 
>> Git") },
>>  };
> --
> To unsubscribe from this list: send the line "unsubscribe git" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
>