{"thread":{"id":"37933","subject":"[PATCH] doc: add some crossrefs between manual pages","startedAt":"2014-11-11T20:17:07Z","lastAt":"2014-12-09T17:14:38Z","messageCount":6,"participants":["Max Horn","Junio C Hamano","Jonathan Nieder"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"251726","messageId":"1415737027-44589-1-git-send-email-max@quendi.de","threadId":"37933","inReplyTo":null,"subject":"[PATCH] doc: add some crossrefs between manual pages","fromName":"Max Horn","fromEmail":"max@quendi.de","sentAt":"2014-11-11T20:17:07Z","receivedAt":"2014-11-11T20:17:07Z","isPatch":true,"sender":{"key":"max@quendi.de","avatar":"https://avatars.githubusercontent.com/u/241512?v=4"},"body":"In particular, git-fast-import and -export link to each\nother, and gitremote-helpers links to existing remote\nhelpers, and vice versa. Also link to fast-import from the\nremote helper spec, as this is relevant for remote helpers\nusing the fast-import format.\n\nSigned-off-by: Max Horn \n---\nI did this because I was browsing the remote helper docs online quite a bit,\nand was wishing for some more direct links between the pages. While I can\nmanyally edit the URL, it seems logical to offer these links directly.\n\n Documentation/git-fast-export.txt | 4 ++++\n Documentation/git-fast-import.txt | 4 ++++\n Documentation/git-remote-ext.txt | 5 ++++-\n Documentation/git-remote-fd.txt | 4 ++++\n Documentation/gitremote-helpers.txt | 6 ++++++\n 5 files changed, 22 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-fast-export.txt b/Documentation/git-fast-export.txt\nindex 221506b..769689d 100644\n--- a/Documentation/git-fast-export.txt\n+++ b/Documentation/git-fast-export.txt\n@@ -148,6 +148,10 @@ Since 'git fast-import' cannot tag trees, you will not be\n able to export the linux.git repository completely, as it contains\n a tag referencing a tree instead of a commit.\n \n+SEE ALSO\n+--------\n+linkgit:git-fast-import[1]\n+\n GIT\n ---\n Part of the linkgit:git[1] suite\ndiff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt\nindex 377eeaa..f71fb01 100644\n--- a/Documentation/git-fast-import.txt\n+++ b/Documentation/git-fast-import.txt\n@@ -1441,6 +1441,10 @@ operator can use this facility to peek at the objects and refs from an\n import in progress, at the cost of some added running time and worse\n compression.\n \n+SEE ALSO\n+--------\n+linkgit:git-fast-export[1]\n+\n GIT\n ---\n Part of the linkgit:git[1] suite\ndiff --git a/Documentation/git-remote-ext.txt b/Documentation/git-remote-ext.txt\nindex cd0bb77..74817b0 100644\n--- a/Documentation/git-remote-ext.txt\n+++ b/Documentation/git-remote-ext.txt\n@@ -72,7 +72,6 @@ GIT_EXT_SERVICE_NOPREFIX::\n \tSet to long name (upload-pack, etc...) of service helper needs\n \tto invoke.\n \n-\n EXAMPLES:\n ---------\n This remote helper is transparently used by Git when\n@@ -116,6 +115,10 @@ begins with `ext::`. Examples:\n \tdetermined by the helper using environment variables (see\n \tabove).\n \n+SEE ALSO\n+--------\n+linkgit:gitremote-helpers[1]\n+\n GIT\n ---\n Part of the linkgit:git[1] suite\ndiff --git a/Documentation/git-remote-fd.txt b/Documentation/git-remote-fd.txt\nindex bcd3766..e700baf 100644\n--- a/Documentation/git-remote-fd.txt\n+++ b/Documentation/git-remote-fd.txt\n@@ -50,6 +50,10 @@ EXAMPLES\n `git push fd::7,8/bar master`::\n \tSame as above.\n \n+SEE ALSO\n+--------\n+linkgit:gitremote-helpers[1]\n+\n GIT\n ---\n Part of the linkgit:git[1] suite\ndiff --git a/Documentation/gitremote-helpers.txt b/Documentation/gitremote-helpers.txt\nindex 64f7ad2..8edf72c 100644\n--- a/Documentation/gitremote-helpers.txt\n+++ b/Documentation/gitremote-helpers.txt\n@@ -452,8 +452,14 @@ SEE ALSO\n --------\n linkgit:git-remote[1]\n \n+linkgit:git-remote-ext[1]\n+\n+linkgit:git-remote-fd[1]\n+\n linkgit:git-remote-testgit[1]\n \n+linkgit:git-fast-import[1]\n+\n GIT\n ---\n Part of the linkgit:git[1] suite\n-- \n2.1.3.dirty\n"},{"id":"251727","messageId":"xmqqppct5p1q.fsf@gitster.dls.corp.google.com","threadId":"37933","inReplyTo":"1415737027-44589-1-git-send-email-max@quendi.de","subject":"Re: [PATCH] doc: add some crossrefs between manual pages","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2014-11-11T22:51:29Z","receivedAt":"2014-11-11T22:51:29Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Max Horn writes:\n\n> I did this because I was browsing the remote helper docs online quite a bit,\n> and was wishing for some more direct links between the pages. While I can\n> manyally edit the URL, it seems logical to offer these links directly.\n\n> diff --git a/Documentation/git-fast-export.txt b/Documentation/git-fast-export.txt\n> ...\n> +linkgit:git-fast-import[1]\n\n> diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt\n> ...\n> +linkgit:git-fast-export[1]\n\nMakes sense to have these pair refer to each other.\n\n> diff --git a/Documentation/git-remote-ext.txt b/Documentation/git-remote-ext.txt\n> ...\n> +linkgit:gitremote-helpers[1]\n\n> diff --git a/Documentation/git-remote-fd.txt b/Documentation/git-remote-fd.txt\n> +linkgit:gitremote-helpers[1]\n\nLikewise. git-remote-* are instances of gitremote-helpers.\n\n> diff --git a/Documentation/gitremote-helpers.txt b/Documentation/gitremote-helpers.txt\n> index 64f7ad2..8edf72c 100644\n> --- a/Documentation/gitremote-helpers.txt\n> +++ b/Documentation/gitremote-helpers.txt\n> @@ -452,8 +452,14 @@ SEE ALSO\n> --------\n> linkgit:git-remote[1]\n> \n> +linkgit:git-remote-ext[1]\n> +\n> +linkgit:git-remote-fd[1]\n> +\n> linkgit:git-remote-testgit[1]\n\nMakes sense.\n\n> +linkgit:git-fast-import[1]\n\nThis looks somewhat out of place; fast-import is not the only or\neven the primary way to do a remote-helper, is it?\n"},{"id":"251772","messageId":"96693472-344E-4ED3-B027-49A8303AF8C0@quendi.de","threadId":"37933","inReplyTo":"xmqqppct5p1q.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH] doc: add some crossrefs between manual pages","fromName":"Max Horn","fromEmail":"max@quendi.de","sentAt":"2014-11-12T20:47:18Z","receivedAt":"2014-11-12T20:47:18Z","isPatch":true,"sender":{"key":"max@quendi.de","avatar":"https://avatars.githubusercontent.com/u/241512?v=4"},"body":"\nOn 11.11.2014, at 23:51, Junio C Hamano wrote:\n\n> Max Horn writes:\n> \n>> I did this because I was browsing the remote helper docs online quite a bit,\n>> and was wishing for some more direct links between the pages. While I can\n>> manyally edit the URL, it seems logical to offer these links directly.\n> \n>> diff --git a/Documentation/git-fast-export.txt b/Documentation/git-fast-export.txt\n>> ...\n>> +linkgit:git-fast-import[1]\n> \n>> diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt\n>> ...\n>> +linkgit:git-fast-export[1]\n> \n> Makes sense to have these pair refer to each other.\n> \n>> diff --git a/Documentation/git-remote-ext.txt b/Documentation/git-remote-ext.txt\n>> ...\n>> +linkgit:gitremote-helpers[1]\n> \n>> diff --git a/Documentation/git-remote-fd.txt b/Documentation/git-remote-fd.txt\n>> +linkgit:gitremote-helpers[1]\n> \n> Likewise. git-remote-* are instances of gitremote-helpers.\n> \n>> diff --git a/Documentation/gitremote-helpers.txt b/Documentation/gitremote-helpers.txt\n>> index 64f7ad2..8edf72c 100644\n>> --- a/Documentation/gitremote-helpers.txt\n>> +++ b/Documentation/gitremote-helpers.txt\n>> @@ -452,8 +452,14 @@ SEE ALSO\n>> --------\n>> linkgit:git-remote[1]\n>> \n>> +linkgit:git-remote-ext[1]\n>> +\n>> +linkgit:git-remote-fd[1]\n>> +\n>> linkgit:git-remote-testgit[1]\n> \n> Makes sense.\n> \n>> +linkgit:git-fast-import[1]\n> \n> This looks somewhat out of place; fast-import is not the only or\n> even the primary way to do a remote-helper, is it?\n\nIt depends on how you look at it, I'd say. If you write a remote-helper that\nuses the import/export feature, it is absolutely vital. All remote helpers\nI ever worked on are of that kind, so to me it is the primary way ;-),\nalthough of course I realize there are others. So, how would you determine\nwhich of the various methods is the \"primary\" one?\n\nIn fact, this single link is the one that motivated me to write the whole\npatch; all the others were afterthoughts ;-).\n\nTo elaborate on that: In the past, I did some work on various import/export\nremote-helpers; and I recall wishing for this precise link several times.\nMore recently, I worked on some tweaks and fixes for Felipe's git-remote-hg.\nWhenever doing that, the place in the docs I start to refresh my memory on\nhow remote helpers work is gitremote-helpers. But then at some point I\nrealize \"ah wait, *that* particular bit is actually part of the \"fastimport\"\nprotocol\". So I need to look that up. And again and again thought \"dang, why\nisn't there a hyperlink for that here\". Fact is, I need both man pages to\nunderstand what's going on.\n\nNow, clearly, I can live without that link. But I feel that there is a clear\nconnection. And if you say it doesn't belong here because it is only\nrelevant for one of multiple ways to do a remote-helper, then shouldn't one\ndrop the links to git-remote-ext etc., too? After all, they are only\nexamples for one of multiple ways, too...\n\nIn other words, I find it arbitrary to exclude one link that is useful for\nsome, but not all remote-helper authors, while adding some other links that\nare also useful for some, but not all remote-helper authors...\n\nThat said, I certainly don't plan to hold that patch hostage to this one\nline. :-)\n\n\nCheers,\nMax"},{"id":"251774","messageId":"xmqqbnoc3zli.fsf@gitster.dls.corp.google.com","threadId":"37933","inReplyTo":"96693472-344E-4ED3-B027-49A8303AF8C0@quendi.de","subject":"Re: [PATCH] doc: add some crossrefs between manual pages","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2014-11-12T20:58:49Z","receivedAt":"2014-11-12T20:58:49Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Max Horn writes:\n\n> On 11.11.2014, at 23:51, Junio C Hamano wrote:\n> ...\n>>> +linkgit:git-fast-import[1]\n>> \n>> This looks somewhat out of place; fast-import is not the only or\n>> even the primary way to do a remote-helper, is it?\n>\n> It depends on how you look at it, I'd say. If you write a remote-helper that\n> uses the import/export feature, it is absolutely vital. All remote helpers\n> I ever worked on are of that kind, so to me it is the primary way ;-),\n> although of course I realize there are others. So, how would you determine\n> which of the various methods is the \"primary\" one?\n\nYou don't. If there exists no clear \"primary\" one, you do not have\nto designate a random one as the \"primary\".\n\nI just thought that these references are to related/relevant pages\nin the same family of commands, and not a place to list possible\nimplementation technologies. We do not say \"see also libcurl\" only\nbecause we have the curl-based remote helper that almost everybody\nuses to interact with other repositories over https:// URLs here,\nand do not list send-pack or receive-pack, even though the pair\nwould be a natural way to implement 'fetch' and 'push' methods to a\nhelper to interact with a native Git repository, either.\n"},{"id":"251775","messageId":"xmqq7fz03z7i.fsf@gitster.dls.corp.google.com","threadId":"37933","inReplyTo":"xmqqbnoc3zli.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH] doc: add some crossrefs between manual pages","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2014-11-12T21:07:13Z","receivedAt":"2014-11-12T21:07:13Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> Max Horn writes:\n>\n>> On 11.11.2014, at 23:51, Junio C Hamano wrote:\n>> ...\n>>>> +linkgit:git-fast-import[1]\n>>> \n>>> This looks somewhat out of place; fast-import is not the only or\n>>> even the primary way to do a remote-helper, is it?\n>>\n>> It depends on how you look at it, I'd say. If you write a remote-helper that\n>> uses the import/export feature, it is absolutely vital. All remote helpers\n>> I ever worked on are of that kind, so to me it is the primary way ;-),\n>> although of course I realize there are others. So, how would you determine\n>> which of the various methods is the \"primary\" one?\n>\n> You don't. If there exists no clear \"primary\" one, you do not have\n> to designate a random one as the \"primary\".\n>\n> I just thought that these references are to related/relevant pages\n> in the same family of commands, and not a place to list possible\n> implementation technologies. We do not say \"see also libcurl\" only\n> because we have the curl-based remote helper that almost everybody\n> uses to interact with other repositories over https:// URLs here,\n> and do not list send-pack or receive-pack, even though the pair\n> would be a natural way to implement 'fetch' and 'push' methods to a\n> helper to interact with a native Git repository, either.\n\nSorry, the final paragraph did not make it for some reason, which\nread like this:\n\n Having said that, we do seem to refer to fast-import quite\n extensively in the text of this manual page, so I think it is good\n to have a reference to its documentation at the bottom.\n\nSo I am OK to special case fast-import and single it out as a\nnotable implementation technology, which is what your patch does.\n\nThanks.\n"},{"id":"253419","messageId":"20141209171438.GA22606@google.com","threadId":"37933","inReplyTo":"xmqq7fz03z7i.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH] doc: add some crossrefs between manual pages","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2014-12-09T17:14:38Z","receivedAt":"2014-12-09T17:14:38Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Junio C Hamano wrote:\n\n> So I am OK to special case fast-import and single it out as a\n> notable implementation technology, which is what your patch does.\n\nMore importantly, helpers implementing the \"import\" or \"export\"\ncapability are indicating that they grok the fast-import format. What\nthey use behind the scenes to produce or parse it is not so important\n--- the relevant thing is that a fast-import stream (with format\ndocumented in git-fast-import(1)) is part of the remote helper\nprotocol in this case.\n\nThanks,\nJonathan\n"}]}