[PATCH] doc: add some crossrefs between manual pages

[PATCH] doc: add some crossrefs between manual pages

[Max Horn]

In particular, git-fast-import and -export link to each
other, and gitremote-helpers links to existing remote
helpers, and vice versa. Also link to fast-import from the
remote helper spec, as this is relevant for remote helpers
using the fast-import format.

Signed-off-by: Max Horn <max@quendi.de>
---
I did this because I was browsing the remote helper docs online quite a bit,
and was wishing for some more direct links between the pages. While I can
manyally edit the URL, it seems logical to offer these links directly.

 Documentation/git-fast-export.txt   | 4 ++++
 Documentation/git-fast-import.txt   | 4 ++++
 Documentation/git-remote-ext.txt    | 5 ++++-
 Documentation/git-remote-fd.txt     | 4 ++++
 Documentation/gitremote-helpers.txt | 6 ++++++
 5 files changed, 22 insertions(+), 1 deletion(-)

diff --git a/Documentation/git-fast-export.txt b/Documentation/git-fast-export.txt
index 221506b..769689d 100644
--- a/Documentation/git-fast-export.txt
+++ b/Documentation/git-fast-export.txt
@@ -148,6 +148,10 @@ Since 'git fast-import' cannot tag trees, you will not be
 able to export the linux.git repository completely, as it contains
 a tag referencing a tree instead of a commit.
 
+SEE ALSO
+--------
+linkgit:git-fast-import[1]
+
 GIT
 ---
 Part of the linkgit:git[1] suite
diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt
index 377eeaa..f71fb01 100644
--- a/Documentation/git-fast-import.txt
+++ b/Documentation/git-fast-import.txt
@@ -1441,6 +1441,10 @@ operator can use this facility to peek at the objects and refs from an
 import in progress, at the cost of some added running time and worse
 compression.
 
+SEE ALSO
+--------
+linkgit:git-fast-export[1]
+
 GIT
 ---
 Part of the linkgit:git[1] suite
diff --git a/Documentation/git-remote-ext.txt b/Documentation/git-remote-ext.txt
index cd0bb77..74817b0 100644
--- a/Documentation/git-remote-ext.txt
+++ b/Documentation/git-remote-ext.txt
@@ -72,7 +72,6 @@ GIT_EXT_SERVICE_NOPREFIX::
 	Set to long name (upload-pack, etc...) of service helper needs
 	to invoke.
 
-
 EXAMPLES:
 ---------
 This remote helper is transparently used by Git when
@@ -116,6 +115,10 @@ begins with `ext::`.  Examples:
 	determined by the helper using environment variables (see
 	above).
 
+SEE ALSO
+--------
+linkgit:gitremote-helpers[1]
+
 GIT
 ---
 Part of the linkgit:git[1] suite
diff --git a/Documentation/git-remote-fd.txt b/Documentation/git-remote-fd.txt
index bcd3766..e700baf 100644
--- a/Documentation/git-remote-fd.txt
+++ b/Documentation/git-remote-fd.txt
@@ -50,6 +50,10 @@ EXAMPLES
 `git push fd::7,8/bar master`::
 	Same as above.
 
+SEE ALSO
+--------
+linkgit:gitremote-helpers[1]
+
 GIT
 ---
 Part of the linkgit:git[1] suite
diff --git a/Documentation/gitremote-helpers.txt b/Documentation/gitremote-helpers.txt
index 64f7ad2..8edf72c 100644
--- a/Documentation/gitremote-helpers.txt
+++ b/Documentation/gitremote-helpers.txt
@@ -452,8 +452,14 @@ SEE ALSO
 --------
 linkgit:git-remote[1]
 
+linkgit:git-remote-ext[1]
+
+linkgit:git-remote-fd[1]
+
 linkgit:git-remote-testgit[1]
 
+linkgit:git-fast-import[1]
+
 GIT
 ---
 Part of the linkgit:git[1] suite
-- 
2.1.3.dirty

Re: [PATCH] doc: add some crossrefs between manual pages

[Junio C Hamano]

Max Horn <max@quendi.de> writes:

> I did this because I was browsing the remote helper docs online quite a bit,
> and was wishing for some more direct links between the pages. While I can
> manyally edit the URL, it seems logical to offer these links directly.

> diff --git a/Documentation/git-fast-export.txt b/Documentation/git-fast-export.txt
> ...
> +linkgit:git-fast-import[1]

> diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt
> ...
> +linkgit:git-fast-export[1]

Makes sense to have these pair refer to each other.

> diff --git a/Documentation/git-remote-ext.txt b/Documentation/git-remote-ext.txt
> ...
> +linkgit:gitremote-helpers[1]

> diff --git a/Documentation/git-remote-fd.txt b/Documentation/git-remote-fd.txt
> +linkgit:gitremote-helpers[1]

Likewise.  git-remote-* are instances of gitremote-helpers.

> diff --git a/Documentation/gitremote-helpers.txt b/Documentation/gitremote-helpers.txt
> index 64f7ad2..8edf72c 100644
> --- a/Documentation/gitremote-helpers.txt
> +++ b/Documentation/gitremote-helpers.txt
> @@ -452,8 +452,14 @@ SEE ALSO
>  --------
>  linkgit:git-remote[1]
>  
> +linkgit:git-remote-ext[1]
> +
> +linkgit:git-remote-fd[1]
> +
>  linkgit:git-remote-testgit[1]

Makes sense.

> +linkgit:git-fast-import[1]

This looks somewhat out of place; fast-import is not the only or
even the primary way to do a remote-helper, is it?

Re: [PATCH] doc: add some crossrefs between manual pages

[Max Horn]

On 11.11.2014, at 23:51, Junio C Hamano <gitster@pobox.com> wrote:

> Max Horn <max@quendi.de> writes:
> 
>> I did this because I was browsing the remote helper docs online quite a bit,
>> and was wishing for some more direct links between the pages. While I can
>> manyally edit the URL, it seems logical to offer these links directly.
> 
>> diff --git a/Documentation/git-fast-export.txt b/Documentation/git-fast-export.txt
>> ...
>> +linkgit:git-fast-import[1]
> 
>> diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt
>> ...
>> +linkgit:git-fast-export[1]
> 
> Makes sense to have these pair refer to each other.
> 
>> diff --git a/Documentation/git-remote-ext.txt b/Documentation/git-remote-ext.txt
>> ...
>> +linkgit:gitremote-helpers[1]
> 
>> diff --git a/Documentation/git-remote-fd.txt b/Documentation/git-remote-fd.txt
>> +linkgit:gitremote-helpers[1]
> 
> Likewise.  git-remote-* are instances of gitremote-helpers.
> 
>> diff --git a/Documentation/gitremote-helpers.txt b/Documentation/gitremote-helpers.txt
>> index 64f7ad2..8edf72c 100644
>> --- a/Documentation/gitremote-helpers.txt
>> +++ b/Documentation/gitremote-helpers.txt
>> @@ -452,8 +452,14 @@ SEE ALSO
>> --------
>> linkgit:git-remote[1]
>> 
>> +linkgit:git-remote-ext[1]
>> +
>> +linkgit:git-remote-fd[1]
>> +
>> linkgit:git-remote-testgit[1]
> 
> Makes sense.
> 
>> +linkgit:git-fast-import[1]
> 
> This looks somewhat out of place; fast-import is not the only or
> even the primary way to do a remote-helper, is it?

It depends on how you look at it, I'd say. If you write a remote-helper that
uses the import/export feature, it is absolutely vital.  All remote helpers
I ever worked on are of that kind, so to me it is the primary way ;-),
although of course I realize there are others. So, how would you determine
which of the various methods is the "primary" one?

In fact, this single link is the one that motivated me to write the whole
patch; all the others were afterthoughts ;-).

To elaborate on that: In the past, I did some work on various import/export
remote-helpers; and I recall wishing for this precise link several times.
More recently, I worked on some tweaks and fixes for Felipe's git-remote-hg.
Whenever doing that, the place in the docs I start to refresh my memory on
how remote helpers work is gitremote-helpers. But then at some point I
realize "ah wait, *that* particular bit is actually part of the "fastimport"
protocol". So I need to look that up. And again and again thought "dang, why
isn't there a hyperlink for that here". Fact is, I need both man pages to
understand what's going on.

Now, clearly, I can live without that link. But I feel that there is a clear
connection.  And if you say it doesn't belong here because it is only
relevant for one of multiple ways to do a remote-helper, then shouldn't one
drop the links to git-remote-ext etc., too? After all, they are only
examples for one of multiple ways, too...

In other words, I find it arbitrary to exclude one link that is useful for
some, but not all remote-helper authors, while adding some other links that
are also useful for some, but not all remote-helper authors...

That said, I certainly don't plan to hold that patch hostage to this one
line. :-)


Cheers,
Max

Re: [PATCH] doc: add some crossrefs between manual pages

[Junio C Hamano]

Max Horn <max@quendi.de> writes:

> On 11.11.2014, at 23:51, Junio C Hamano <gitster@pobox.com> wrote:
> ...
>>> +linkgit:git-fast-import[1]
>> 
>> This looks somewhat out of place; fast-import is not the only or
>> even the primary way to do a remote-helper, is it?
>
> It depends on how you look at it, I'd say. If you write a remote-helper that
> uses the import/export feature, it is absolutely vital.  All remote helpers
> I ever worked on are of that kind, so to me it is the primary way ;-),
> although of course I realize there are others. So, how would you determine
> which of the various methods is the "primary" one?

You don't.  If there exists no clear "primary" one, you do not have
to designate a random one as the "primary".

I just thought that these references are to related/relevant pages
in the same family of commands, and not a place to list possible
implementation technologies.  We do not say "see also libcurl" only
because we have the curl-based remote helper that almost everybody
uses to interact with other repositories over https:// URLs here,
and do not list send-pack or receive-pack, even though the pair
would be a natural way to implement 'fetch' and 'push' methods to a
helper to interact with a native Git repository, either.

Re: [PATCH] doc: add some crossrefs between manual pages

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

> Max Horn <max@quendi.de> writes:
>
>> On 11.11.2014, at 23:51, Junio C Hamano <gitster@pobox.com> wrote:
>> ...
>>>> +linkgit:git-fast-import[1]
>>> 
>>> This looks somewhat out of place; fast-import is not the only or
>>> even the primary way to do a remote-helper, is it?
>>
>> It depends on how you look at it, I'd say. If you write a remote-helper that
>> uses the import/export feature, it is absolutely vital.  All remote helpers
>> I ever worked on are of that kind, so to me it is the primary way ;-),
>> although of course I realize there are others. So, how would you determine
>> which of the various methods is the "primary" one?
>
> You don't.  If there exists no clear "primary" one, you do not have
> to designate a random one as the "primary".
>
> I just thought that these references are to related/relevant pages
> in the same family of commands, and not a place to list possible
> implementation technologies.  We do not say "see also libcurl" only
> because we have the curl-based remote helper that almost everybody
> uses to interact with other repositories over https:// URLs here,
> and do not list send-pack or receive-pack, even though the pair
> would be a natural way to implement 'fetch' and 'push' methods to a
> helper to interact with a native Git repository, either.

Sorry, the final paragraph did not make it for some reason, which
read like this:

    Having said that, we do seem to refer to fast-import quite
    extensively in the text of this manual page, so I think it is good
    to have a reference to its documentation at the bottom.

So I am OK to special case fast-import and single it out as a
notable implementation technology, which is what your patch does.

Thanks.

Re: [PATCH] doc: add some crossrefs between manual pages

[Jonathan Nieder]

Junio C Hamano wrote:

> So I am OK to special case fast-import and single it out as a
> notable implementation technology, which is what your patch does.

More importantly, helpers implementing the "import" or "export"
capability are indicating that they grok the fast-import format.  What
they use behind the scenes to produce or parse it is not so important
--- the relevant thing is that a fast-import stream (with format
documented in git-fast-import(1)) is part of the remote helper
protocol in this case.

Thanks,
Jonathan