{"thread":{"id":"30692","subject":"[PATCH 0/3] Improve credential API documentation","startedAt":"2012-06-03T16:10:01Z","lastAt":"2012-06-05T17:28:53Z","messageCount":24,"participants":["Matthieu Moy","Junio C Hamano","Jeff King"],"isPatch":true,"patchVersion":1,"patchTotal":3},"messages":[{"id":"192756","messageId":"1338739804-32167-1-git-send-email-Matthieu.Moy@imag.fr","threadId":"30692","inReplyTo":null,"subject":"[PATCH 0/3] Improve credential API documentation","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@imag.fr","sentAt":"2012-06-03T16:10:01Z","receivedAt":"2012-06-03T16:10:01Z","isPatch":true,"sender":{"key":"git@matthieu-moy.fr","avatar":"https://avatars.githubusercontent.com/u/14709?v=4"},"body":"Follow-up to the discussion here:\nhttp://thread.gmane.org/gmane.comp.version-control.git/198409\n\nMatthieu Moy (3):\n api-credential.txt: show the big picture first\n api-credentials.txt: mention credential.helper explicitly\n api-credentials.txt: add \"see also\" section\n\n Documentation/technical/api-credentials.txt | 60 +++++++++++++++++++++++++++--\n 1 file changed, 56 insertions(+), 4 deletions(-)\n\n-- \n1.7.11.rc0.57.g84a04c7\n"},{"id":"192757","messageId":"1338739804-32167-2-git-send-email-Matthieu.Moy@imag.fr","threadId":"30692","inReplyTo":"1338739804-32167-1-git-send-email-Matthieu.Moy@imag.fr","subject":"[PATCH 1/3] api-credential.txt: show the big picture first","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@imag.fr","sentAt":"2012-06-03T16:10:02Z","receivedAt":"2012-06-03T16:10:02Z","isPatch":true,"sender":{"key":"git@matthieu-moy.fr","avatar":"https://avatars.githubusercontent.com/u/14709?v=4"},"body":"The API documentation targets two kinds of developers: those using the\n(C) API, and those writing remote-helpers. The document was not clear\nabout which part was useful to which category, and for example, the C API\ncould be mistakenly thought as an API for writting remote helpers.\n\nBased-on-patch-by: Jeff King \nSigned-off-by: Matthieu Moy \n---\nI took Jeff's explanation, but I insist in having a picture ;-).\n\nI made the picture more generic compared to my first proposal, and\njust mention remote-helper in the text (I originally was wondering\nwhether this API could be used from a helper, since the helper has its\nSTDIN and STDOUT bound to the main Git process already, so this\nexplanation would have avoided the confusion for me).\n\n Documentation/technical/api-credentials.txt | 50 +++++++++++++++++++++++++++--\n 1 file changed, 47 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/technical/api-credentials.txt b/Documentation/technical/api-credentials.txt\nindex 21ca6a2..8804c42 100644\n--- a/Documentation/technical/api-credentials.txt\n+++ b/Documentation/technical/api-credentials.txt\n@@ -6,8 +6,52 @@ password credentials from the user (even though credentials in the wider\n world can take many forms, in this document the word \"credential\" always\n refers to a username and password pair).\n \n+This document describes two interfaces: the C API that the credential\n+subsystem provides to the rest of git, and the protocol that git uses to\n+communicate with system-specific \"credential helpers\". If you are\n+writing git code that wants to look up or prompt for credentials, see\n+the section \"C API\" below. If you want to write your own helper, see\n+the section on \"Credential Helpers\" below.\n+\n+Typical setup\n+-------------\n+\n+------------\n++-----------------------+\n+| git code (C) |--- to server requiring --->\n+| | authentication\n+|.......................|\n+| C credential API |--- prompt ---> User\n++-----------------------+\n+ ^ |\n+ | pipe |\n+ | v\n++-----------------------+\n+| git credential helper |\n++-----------------------+\n+------------\n+\n+The git code (typically a remote-helper) will call the C API to obtain\n+credential data like a login/password couple (credential_fill). The\n+API will itself call a remote helper (e.g. \"git credential-cache\" or\n+\"git credential-store\") that may retrieve credential data from a\n+store. If the credential helper cannot find the information, the C API\n+will prompt the user. Then, the caller of the API takes care of\n+contacting the server, and do the actual authentication.\n+\n+C API\n+-----\n+\n+The credential C API is meant to be called by git code which needs to\n+acquire or store a credential. It is centered around an object\n+representing a single credential and provides three basic operations:\n+fill (acquire credentials by calling helpers and/or prompting the user),\n+approve (mark a credential as successfully used so that it can be stored\n+for later use), and reject (mark a credential as unsuccessful so that it\n+can be erased from any persistent storage).\n+\n Data Structures\n----------------\n+~~~~~~~~~~~~~~~\n \n `struct credential`::\n \n@@ -28,7 +72,7 @@ This struct should always be initialized with `CREDENTIAL_INIT` or\n \n \n Functions\n----------\n+~~~~~~~~~\n \n `credential_init`::\n \n@@ -72,7 +116,7 @@ Functions\n \tParse a URL into broken-down credential fields.\n \n Example\n--------\n+~~~~~~~\n \n The example below shows how the functions of the credential API could be\n used to login to a fictitious \"foo\" service on a remote host:\n-- \n1.7.11.rc0.57.g84a04c7\n"},{"id":"192759","messageId":"1338739804-32167-3-git-send-email-Matthieu.Moy@imag.fr","threadId":"30692","inReplyTo":"1338739804-32167-1-git-send-email-Matthieu.Moy@imag.fr","subject":"[PATCH 2/3] api-credentials.txt: mention credential.helper explicitly","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@imag.fr","sentAt":"2012-06-03T16:10:03Z","receivedAt":"2012-06-03T16:10:03Z","isPatch":true,"sender":{"key":"git@matthieu-moy.fr","avatar":"https://avatars.githubusercontent.com/u/14709?v=4"},"body":"The name of the configuration variable was mentioned only at the very\nend of the explanation, in a place specific to a specific rule, hence it\nwas not very clear what the specification was about.\n\nSigned-off-by: Matthieu Moy \n---\n Documentation/technical/api-credentials.txt | 3 ++-\n 1 file changed, 2 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/technical/api-credentials.txt b/Documentation/technical/api-credentials.txt\nindex 8804c42..4561469 100644\n--- a/Documentation/technical/api-credentials.txt\n+++ b/Documentation/technical/api-credentials.txt\n@@ -179,7 +179,8 @@ credentials from and to long-term storage (where \"long-term\" is simply\n longer than a single git process; e.g., credentials may be stored\n in-memory for a few minutes, or indefinitely on disk).\n \n-Each helper is specified by a single string. The string is transformed\n+Each helper is specified by a single string in the configuration\n+variable credential.helper. The string is transformed\n by git into a command to be executed using these rules:\n \n 1. If the helper string begins with \"!\", it is considered a shell\n-- \n1.7.11.rc0.57.g84a04c7\n"},{"id":"192758","messageId":"1338739804-32167-4-git-send-email-Matthieu.Moy@imag.fr","threadId":"30692","inReplyTo":"1338739804-32167-1-git-send-email-Matthieu.Moy@imag.fr","subject":"[PATCH 3/3] api-credentials.txt: add \"see also\" section","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@imag.fr","sentAt":"2012-06-03T16:10:04Z","receivedAt":"2012-06-03T16:10:04Z","isPatch":true,"sender":{"key":"git@matthieu-moy.fr","avatar":"https://avatars.githubusercontent.com/u/14709?v=4"},"body":"\nSigned-off-by: Matthieu Moy \n---\n Documentation/technical/api-credentials.txt | 7 +++++++\n 1 file changed, 7 insertions(+)\n\ndiff --git a/Documentation/technical/api-credentials.txt b/Documentation/technical/api-credentials.txt\nindex 4561469..ac6be31 100644\n--- a/Documentation/technical/api-credentials.txt\n+++ b/Documentation/technical/api-credentials.txt\n@@ -288,3 +288,10 @@ request.\n If a helper receives any other operation, it should silently ignore the\n request. This leaves room for future operations to be added (older\n helpers will just ignore the new requests).\n+\n+See also\n+--------\n+\n+linkgit:../gitcredentials[7]\n+\n+linkgit:../git-config[5] (See configuration variables `credential.*`)\n-- \n1.7.11.rc0.57.g84a04c7\n"},{"id":"192778","messageId":"7vsjecvxmc.fsf@alter.siamese.dyndns.org","threadId":"30692","inReplyTo":"1338739804-32167-4-git-send-email-Matthieu.Moy@imag.fr","subject":"Re: [PATCH 3/3] api-credentials.txt: add \"see also\" section","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-06-03T22:28:27Z","receivedAt":"2012-06-03T22:28:27Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Matthieu Moy writes:\n\n> diff --git a/Documentation/technical/api-credentials.txt b/Documentation/technical/api-credentials.txt\n> index 4561469..ac6be31 100644\n> --- a/Documentation/technical/api-credentials.txt\n> +++ b/Documentation/technical/api-credentials.txt\n> @@ -288,3 +288,10 @@ request.\n> If a helper receives any other operation, it should silently ignore the\n> request. This leaves room for future operations to be added (older\n> helpers will just ignore the new requests).\n> +\n> +See also\n> +--------\n> +\n> +linkgit:../gitcredentials[7]\n> +\n> +linkgit:../git-config[5] (See configuration variables `credential.*`)\n\nThanks. All looked good.\n\nThis is the first one that refers to \"../something\" with \"linkgit:\";\ndo they format sensibly?\n"},{"id":"192793","messageId":"vpq1ulvuxd9.fsf@bauges.imag.fr","threadId":"30692","inReplyTo":"7vsjecvxmc.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH 3/3] api-credentials.txt: add \"see also\" section","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@grenoble-inp.fr","sentAt":"2012-06-04T11:31:30Z","receivedAt":"2012-06-04T11:31:30Z","isPatch":true,"sender":{"key":"matthieu.moy@grenoble-inp.fr","avatar":"https://gravatar.com/avatar/72c8a2705971a25dfaff23cece15130d405685845d911aedd5667ace277f3fc5?d=mp&s=160"},"body":"Junio C Hamano writes:\n\n> Thanks. All looked good.\n>\n> This is the first one that refers to \"../something\" with \"linkgit:\";\n> do they format sensibly?\n\nOn my machine (Debian stable), the HTML formatting is correct (and BTW,\nthe other instance of linkgit in technical, \"(see\nlinkgit:gitattributes[5])\" is broken). One can see the .. in the link,\nbut at least the target of the link is OK. I didn't worry too much about\nformatting since this is a technical documentation.\n\n-- \nMatthieu Moy\nhttp://www-verimag.imag.fr/~moy/\n"},{"id":"192796","messageId":"20120604115108.GA27676@sigill.intra.peff.net","threadId":"30692","inReplyTo":"1338739804-32167-2-git-send-email-Matthieu.Moy@imag.fr","subject":"Re: [PATCH 1/3] api-credential.txt: show the big picture first","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2012-06-04T11:51:08Z","receivedAt":"2012-06-04T11:51:08Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Sun, Jun 03, 2012 at 06:10:02PM +0200, Matthieu Moy wrote:\n\n> The API documentation targets two kinds of developers: those using the\n> (C) API, and those writing remote-helpers. The document was not clear\n> about which part was useful to which category, and for example, the C API\n> could be mistakenly thought as an API for writting remote helpers.\n> \n> Based-on-patch-by: Jeff King \n> Signed-off-by: Matthieu Moy \n> ---\n> I took Jeff's explanation, but I insist in having a picture ;-).\n\nThanks. I had meant to follow-up, but it was among the least interesting\nthings for me to work on, so I procrastinated. And here I am being\nrewarded for it with somebody else doing the work. :)\n\nLooks good overall to me. Two minor comments:\n\n> +The git code (typically a remote-helper) will call the C API to obtain\n> +credential data like a login/password couple (credential_fill). The\n\nI found the word \"couple\" odd here; I think \"pair\" would be more\nidiomatic English.\n\n> +API will itself call a remote helper (e.g. \"git credential-cache\" or\n> +\"git credential-store\") that may retrieve credential data from a\n> +store. If the credential helper cannot find the information, the C API\n> +will prompt the user. Then, the caller of the API takes care of\n> +contacting the server, and do the actual authentication.\n\ns/do/does/\n\n-Peff\n"},{"id":"192797","messageId":"20120604115442.GB27676@sigill.intra.peff.net","threadId":"30692","inReplyTo":"1338739804-32167-3-git-send-email-Matthieu.Moy@imag.fr","subject":"Re: [PATCH 2/3] api-credentials.txt: mention credential.helper explicitly","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2012-06-04T11:54:42Z","receivedAt":"2012-06-04T11:54:42Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Sun, Jun 03, 2012 at 06:10:03PM +0200, Matthieu Moy wrote:\n\n> The name of the configuration variable was mentioned only at the very\n> end of the explanation, in a place specific to a specific rule, hence it\n> was not very clear what the specification was about.\n> \n> Signed-off-by: Matthieu Moy \n> ---\n> Documentation/technical/api-credentials.txt | 3 ++-\n> 1 file changed, 2 insertions(+), 1 deletion(-)\n> \n> diff --git a/Documentation/technical/api-credentials.txt b/Documentation/technical/api-credentials.txt\n> index 8804c42..4561469 100644\n> --- a/Documentation/technical/api-credentials.txt\n> +++ b/Documentation/technical/api-credentials.txt\n> @@ -179,7 +179,8 @@ credentials from and to long-term storage (where \"long-term\" is simply\n> longer than a single git process; e.g., credentials may be stored\n> in-memory for a few minutes, or indefinitely on disk).\n> \n> -Each helper is specified by a single string. The string is transformed\n> +Each helper is specified by a single string in the configuration\n> +variable credential.helper. The string is transformed\n> by git into a command to be executed using these rules:\n\nThey may be in other variables, too (like credential.*.helper). I don't\nknow if it is worth making that distinction.\n\nOriginally, helpers could also use these specification strings to chain\nto each other, but in the current implementation, there is no chaining\n(it was more important when prompting wasn't automatic, so storage\nhelpers would chain to prompting helpers). So I think we can disregard\nthat for now, and they really do just appear in config.\n\n-Peff\n"},{"id":"192798","messageId":"20120604115630.GC27676@sigill.intra.peff.net","threadId":"30692","inReplyTo":"vpq1ulvuxd9.fsf@bauges.imag.fr","subject":"Re: [PATCH 3/3] api-credentials.txt: add \"see also\" section","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2012-06-04T11:56:30Z","receivedAt":"2012-06-04T11:56:30Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Mon, Jun 04, 2012 at 01:31:30PM +0200, Matthieu Moy wrote:\n\n> Junio C Hamano writes:\n> \n> > Thanks. All looked good.\n> >\n> > This is the first one that refers to \"../something\" with \"linkgit:\";\n> > do they format sensibly?\n> \n> On my machine (Debian stable), the HTML formatting is correct (and BTW,\n> the other instance of linkgit in technical, \"(see\n> linkgit:gitattributes[5])\" is broken). One can see the .. in the link,\n> but at least the target of the link is OK. I didn't worry too much about\n> formatting since this is a technical documentation.\n\nThere is also a broken reference to linkgit:git-config[1] in\napi-config.txt.\n\nWe only build html documentation from technical/, not manpages. So they\ncould just all be switched to link: (the point of linkgit is to format a\nmanpage reference from either html or a manpage).\n\n-Peff\n"},{"id":"192828","messageId":"vpqehpvrmmy.fsf@bauges.imag.fr","threadId":"30692","inReplyTo":"20120604115442.GB27676@sigill.intra.peff.net","subject":"Re: [PATCH 2/3] api-credentials.txt: mention credential.helper explicitly","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@grenoble-inp.fr","sentAt":"2012-06-04T17:51:33Z","receivedAt":"2012-06-04T17:51:33Z","isPatch":true,"sender":{"key":"matthieu.moy@grenoble-inp.fr","avatar":"https://gravatar.com/avatar/72c8a2705971a25dfaff23cece15130d405685845d911aedd5667ace277f3fc5?d=mp&s=160"},"body":"Jeff King writes:\n\n> On Sun, Jun 03, 2012 at 06:10:03PM +0200, Matthieu Moy wrote:\n>\n>> --- a/Documentation/technical/api-credentials.txt\n>> +++ b/Documentation/technical/api-credentials.txt\n>> @@ -179,7 +179,8 @@ credentials from and to long-term storage (where \"long-term\" is simply\n>> longer than a single git process; e.g., credentials may be stored\n>> in-memory for a few minutes, or indefinitely on disk).\n>> \n>> -Each helper is specified by a single string. The string is transformed\n>> +Each helper is specified by a single string in the configuration\n>> +variable credential.helper. The string is transformed\n>> by git into a command to be executed using these rules:\n>\n> They may be in other variables, too (like credential.*.helper). I don't\n> know if it is worth making that distinction.\n>\n> Originally, helpers could also use these specification strings to chain\n> to each other, but in the current implementation, there is no chaining\n> (it was more important when prompting wasn't automatic, so storage\n> helpers would chain to prompting helpers). So I think we can disregard\n> that for now, and they really do just appear in config.\n\nI'd say it is not worth making the distinction, but we may just say\n\"in the configuration variable credential.helper (and others, see\nlinkgit:../git-config.txt[1])\" to be complete.\n\n-- \nMatthieu Moy\nhttp://www-verimag.imag.fr/~moy/\n"},{"id":"192837","messageId":"7vpq9eswla.fsf@alter.siamese.dyndns.org","threadId":"30692","inReplyTo":"20120604115630.GC27676@sigill.intra.peff.net","subject":"Re: [PATCH 3/3] api-credentials.txt: add \"see also\" section","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-06-04T19:31:13Z","receivedAt":"2012-06-04T19:31:13Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n>> On my machine (Debian stable), the HTML formatting is correct (and BTW,\n>> the other instance of linkgit in technical, \"(see\n>> linkgit:gitattributes[5])\" is broken).\n>\n> There is also a broken reference to linkgit:git-config[1] in\n> api-config.txt.\n\nThanks; we should queue somthing like this.\n\n-- >8 --\nSubject: [PATCH] doc: fix xref link from api docs to manual pages\n\nThey are one-level above, so refer them as linkgit:../git-foo[n] with \"../\"\n\nSigned-off-by: Junio C Hamano \n---\n Documentation/technical/api-config.txt | 2 +-\n Documentation/technical/api-merge.txt | 2 +-\n 2 files changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/technical/api-config.txt b/Documentation/technical/api-config.txt\nindex edf8dfb..bd4d8b8 100644\n--- a/Documentation/technical/api-config.txt\n+++ b/Documentation/technical/api-config.txt\n@@ -2,7 +2,7 @@ config API\n ==========\n \n The config API gives callers a way to access git configuration files\n-(and files which have the same syntax). See linkgit:git-config[1] for a\n+(and files which have the same syntax). See linkgit:../git-config[1] for a\n discussion of the config file syntax.\n \n General Usage\ndiff --git a/Documentation/technical/api-merge.txt b/Documentation/technical/api-merge.txt\nindex 9dc1bed..25158b8 100644\n--- a/Documentation/technical/api-merge.txt\n+++ b/Documentation/technical/api-merge.txt\n@@ -36,7 +36,7 @@ the operation of a low-level (single file) merge. Some options:\n \tancestors in a recursive merge.\n \tIf a helper program is specified by the\n \t`[merge \"\"] recursive` configuration, it will\n-\tbe used (see linkgit:gitattributes[5]).\n+\tbe used (see linkgit:../gitattributes[5]).\n \n `variant`::\n \tResolve local conflicts automatically in favor\n-- \n1.7.11.rc1.2.g33fe195\n"},{"id":"192842","messageId":"vpqpq9en8ol.fsf@bauges.imag.fr","threadId":"30692","inReplyTo":"20120604115630.GC27676@sigill.intra.peff.net","subject":"Re: [PATCH 3/3] api-credentials.txt: add \"see also\" section","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@grenoble-inp.fr","sentAt":"2012-06-04T20:06:34Z","receivedAt":"2012-06-04T20:06:34Z","isPatch":true,"sender":{"key":"matthieu.moy@grenoble-inp.fr","avatar":"https://gravatar.com/avatar/72c8a2705971a25dfaff23cece15130d405685845d911aedd5667ace277f3fc5?d=mp&s=160"},"body":"Jeff King writes:\n\n> We only build html documentation from technical/, not manpages. So they\n> could just all be switched to link: (the point of linkgit is to format a\n> manpage reference from either html or a manpage).\n\nOTOH, using linkgit: makes it easier to cut-and-paste from technical/ to\nman pages (which may be sensible for plumbing commands), so I think it's\nOK to keep linkgit:.\n\n-- \nMatthieu Moy\nhttp://www-verimag.imag.fr/~moy/\n"},{"id":"192844","messageId":"1338841064-32294-1-git-send-email-Matthieu.Moy@imag.fr","threadId":"30692","inReplyTo":"1338739804-32167-1-git-send-email-Matthieu.Moy@imag.fr","subject":"[PATCH 1/4] doc: fix xref link from api docs to manual pages","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@imag.fr","sentAt":"2012-06-04T20:17:41Z","receivedAt":"2012-06-04T20:17:41Z","isPatch":true,"sender":{"key":"git@matthieu-moy.fr","avatar":"https://avatars.githubusercontent.com/u/14709?v=4"},"body":"From: Junio C Hamano \n\nThey are one-level above, so refer them as linkgit:../git-foo[n] with \"../\"\n\nSigned-off-by: Junio C Hamano \n---\nThat's Junio's patch unmodified (I took it at the beginning of the\nserie so that my linkgit:../ isn't the fist to appear)\n\n Documentation/technical/api-config.txt | 2 +-\n Documentation/technical/api-merge.txt | 2 +-\n 2 files changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/technical/api-config.txt b/Documentation/technical/api-config.txt\nindex edf8dfb..bd4d8b8 100644\n--- a/Documentation/technical/api-config.txt\n+++ b/Documentation/technical/api-config.txt\n@@ -2,7 +2,7 @@ config API\n ==========\n \n The config API gives callers a way to access git configuration files\n-(and files which have the same syntax). See linkgit:git-config[1] for a\n+(and files which have the same syntax). See linkgit:../git-config[1] for a\n discussion of the config file syntax.\n \n General Usage\ndiff --git a/Documentation/technical/api-merge.txt b/Documentation/technical/api-merge.txt\nindex 9dc1bed..25158b8 100644\n--- a/Documentation/technical/api-merge.txt\n+++ b/Documentation/technical/api-merge.txt\n@@ -36,7 +36,7 @@ the operation of a low-level (single file) merge. Some options:\n \tancestors in a recursive merge.\n \tIf a helper program is specified by the\n \t`[merge \"\"] recursive` configuration, it will\n-\tbe used (see linkgit:gitattributes[5]).\n+\tbe used (see linkgit:../gitattributes[5]).\n \n `variant`::\n \tResolve local conflicts automatically in favor\n-- \n1.7.11.rc0.57.g84a04c7\n"},{"id":"192845","messageId":"1338841064-32294-2-git-send-email-Matthieu.Moy@imag.fr","threadId":"30692","inReplyTo":"1338841064-32294-1-git-send-email-Matthieu.Moy@imag.fr","subject":"[PATCH 2/4 v2] api-credential.txt: show the big picture first","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@imag.fr","sentAt":"2012-06-04T20:17:42Z","receivedAt":"2012-06-04T20:17:42Z","isPatch":true,"sender":{"key":"git@matthieu-moy.fr","avatar":"https://avatars.githubusercontent.com/u/14709?v=4"},"body":"The API documentation targets two kinds of developers: those using the\n(C) API, and those writing remote-helpers. The document was not clear\nabout which part was useful to which category, and for example, the C API\ncould be mistakenly thought as an API for writting remote helpers.\n\nBased-on-patch-by: Jeff King \nSigned-off-by: Matthieu Moy \n---\nFixed typos noted by Jeff.\n\n Documentation/technical/api-credentials.txt | 50 +++++++++++++++++++++++++++--\n 1 file changed, 47 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/technical/api-credentials.txt b/Documentation/technical/api-credentials.txt\nindex 21ca6a2..2d6e811 100644\n--- a/Documentation/technical/api-credentials.txt\n+++ b/Documentation/technical/api-credentials.txt\n@@ -6,8 +6,52 @@ password credentials from the user (even though credentials in the wider\n world can take many forms, in this document the word \"credential\" always\n refers to a username and password pair).\n \n+This document describes two interfaces: the C API that the credential\n+subsystem provides to the rest of git, and the protocol that git uses to\n+communicate with system-specific \"credential helpers\". If you are\n+writing git code that wants to look up or prompt for credentials, see\n+the section \"C API\" below. If you want to write your own helper, see\n+the section on \"Credential Helpers\" below.\n+\n+Typical setup\n+-------------\n+\n+------------\n++-----------------------+\n+| git code (C) |--- to server requiring --->\n+| | authentication\n+|.......................|\n+| C credential API |--- prompt ---> User\n++-----------------------+\n+ ^ |\n+ | pipe |\n+ | v\n++-----------------------+\n+| git credential helper |\n++-----------------------+\n+------------\n+\n+The git code (typically a remote-helper) will call the C API to obtain\n+credential data like a login/password pair (credential_fill). The\n+API will itself call a remote helper (e.g. \"git credential-cache\" or\n+\"git credential-store\") that may retrieve credential data from a\n+store. If the credential helper cannot find the information, the C API\n+will prompt the user. Then, the caller of the API takes care of\n+contacting the server, and does the actual authentication.\n+\n+C API\n+-----\n+\n+The credential C API is meant to be called by git code which needs to\n+acquire or store a credential. It is centered around an object\n+representing a single credential and provides three basic operations:\n+fill (acquire credentials by calling helpers and/or prompting the user),\n+approve (mark a credential as successfully used so that it can be stored\n+for later use), and reject (mark a credential as unsuccessful so that it\n+can be erased from any persistent storage).\n+\n Data Structures\n----------------\n+~~~~~~~~~~~~~~~\n \n `struct credential`::\n \n@@ -28,7 +72,7 @@ This struct should always be initialized with `CREDENTIAL_INIT` or\n \n \n Functions\n----------\n+~~~~~~~~~\n \n `credential_init`::\n \n@@ -72,7 +116,7 @@ Functions\n \tParse a URL into broken-down credential fields.\n \n Example\n--------\n+~~~~~~~\n \n The example below shows how the functions of the credential API could be\n used to login to a fictitious \"foo\" service on a remote host:\n-- \n1.7.11.rc0.57.g84a04c7\n"},{"id":"192847","messageId":"1338841064-32294-3-git-send-email-Matthieu.Moy@imag.fr","threadId":"30692","inReplyTo":"1338841064-32294-1-git-send-email-Matthieu.Moy@imag.fr","subject":"[PATCH 3/4 v2] api-credentials.txt: mention credential.helper explicitly","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@imag.fr","sentAt":"2012-06-04T20:17:43Z","receivedAt":"2012-06-04T20:17:43Z","isPatch":true,"sender":{"key":"git@matthieu-moy.fr","avatar":"https://avatars.githubusercontent.com/u/14709?v=4"},"body":"The name of the configuration variable was mentioned only at the very\nend of the explanation, in a place specific to a specific rule, hence it\nwas not very clear what the specification was about.\n\nSigned-off-by: Matthieu Moy \n---\nAdded \"and others\" with a link to git-config(1), for completeness.\n\n Documentation/technical/api-credentials.txt | 6 ++++--\n 1 file changed, 4 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/technical/api-credentials.txt b/Documentation/technical/api-credentials.txt\nindex 2d6e811..969a1ff 100644\n--- a/Documentation/technical/api-credentials.txt\n+++ b/Documentation/technical/api-credentials.txt\n@@ -179,8 +179,10 @@ credentials from and to long-term storage (where \"long-term\" is simply\n longer than a single git process; e.g., credentials may be stored\n in-memory for a few minutes, or indefinitely on disk).\n \n-Each helper is specified by a single string. The string is transformed\n-by git into a command to be executed using these rules:\n+Each helper is specified by a single string in the configuration\n+variable `credential.helper` (and others, see\n+linkgit:../git-config[1]). The string is transformed by git into a\n+command to be executed using these rules:\n \n 1. If the helper string begins with \"!\", it is considered a shell\n snippet, and everything after the \"!\" becomes the command.\n-- \n1.7.11.rc0.57.g84a04c7\n"},{"id":"192846","messageId":"1338841064-32294-4-git-send-email-Matthieu.Moy@imag.fr","threadId":"30692","inReplyTo":"1338841064-32294-1-git-send-email-Matthieu.Moy@imag.fr","subject":"[PATCH 4/4 v2] api-credentials.txt: add \"see also\" section","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@imag.fr","sentAt":"2012-06-04T20:17:44Z","receivedAt":"2012-06-04T20:17:44Z","isPatch":true,"sender":{"key":"git@matthieu-moy.fr","avatar":"https://avatars.githubusercontent.com/u/14709?v=4"},"body":"\nSigned-off-by: Matthieu Moy \n---\nUnmodified since v1.\n\n Documentation/technical/api-credentials.txt | 7 +++++++\n 1 file changed, 7 insertions(+)\n\ndiff --git a/Documentation/technical/api-credentials.txt b/Documentation/technical/api-credentials.txt\nindex 969a1ff..597521b 100644\n--- a/Documentation/technical/api-credentials.txt\n+++ b/Documentation/technical/api-credentials.txt\n@@ -289,3 +289,10 @@ request.\n If a helper receives any other operation, it should silently ignore the\n request. This leaves room for future operations to be added (older\n helpers will just ignore the new requests).\n+\n+See also\n+--------\n+\n+linkgit:../gitcredentials[7]\n+\n+linkgit:../git-config[5] (See configuration variables `credential.*`)\n-- \n1.7.11.rc0.57.g84a04c7\n"},{"id":"192871","messageId":"20120605065955.GB25809@sigill.intra.peff.net","threadId":"30692","inReplyTo":"vpqpq9en8ol.fsf@bauges.imag.fr","subject":"Re: [PATCH 3/3] api-credentials.txt: add \"see also\" section","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2012-06-05T06:59:55Z","receivedAt":"2012-06-05T06:59:55Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Mon, Jun 04, 2012 at 10:06:34PM +0200, Matthieu Moy wrote:\n\n> Jeff King writes:\n> \n> > We only build html documentation from technical/, not manpages. So they\n> > could just all be switched to link: (the point of linkgit is to format a\n> > manpage reference from either html or a manpage).\n> \n> OTOH, using linkgit: makes it easier to cut-and-paste from technical/ to\n> man pages (which may be sensible for plumbing commands), so I think it's\n> OK to keep linkgit:.\n\nExcept that you cannot cut-and-paste, since it has \"..\" in it. :)\n\nBut yeah, I guess it does have some other niceties, like adding the\n\".html\" on the end, converting git-config[1] into the right text, etc. I\nwas just thinking that by using link: directly, we would make it look\nnicer (e.g., drop the \"..\" from the actual link text). Maybe we can even\nstrip that in the macro, though.\n\nI wonder if we could even make asciidoc work to convert\nlinkgit:git-config[1] into the right path (i.e., to include the \"..\"\nautomatically) when we are in the subdir.\n\nI don't really have a sense how powerful asciidoc macros are, but this\nseems like an obvious case that they should handle.\n\n-Peff\n"},{"id":"192876","messageId":"20120605073403.GC25809@sigill.intra.peff.net","threadId":"30692","inReplyTo":"20120605065955.GB25809@sigill.intra.peff.net","subject":"Re: [PATCH 3/3] api-credentials.txt: add \"see also\" section","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2012-06-05T07:34:03Z","receivedAt":"2012-06-05T07:34:03Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Tue, Jun 05, 2012 at 02:59:55AM -0400, Jeff King wrote:\n\n> I wonder if we could even make asciidoc work to convert\n> linkgit:git-config[1] into the right path (i.e., to include the \"..\"\n> automatically) when we are in the subdir.\n> \n> I don't really have a sense how powerful asciidoc macros are, but this\n> seems like an obvious case that they should handle.\n\nHere is a simple fix. The Makefile bits are more hacky than I would\nlike. It would be really nice if the asciidoc macro could convert \"we\nare working on X/Y/Z.html\" into \"we need ../../ to get to the relative\nbase\", but I don't think it is that flexible.\n\nWe could also replace asciidoc with a wrapper script that does the\nconversion and sets the appropriate attribute. I don't know if it is\nworth the trouble. It's not like we add documentation subdirectories\nvery often.\n\n-- >8 --\nSubject: docs: fix cross-directory linkgit references\n\nMost of our documentation is in a single directory, so using\nlinkgit:git-config[1] just generates a relative link in the\nsame directory. However, this is not the case with the API\ndocumentation in technical/*, which need to refer to\ngit-config from the parent directory.\n\nWe can fix this by passing a special prefix attribute when building\nin a subdirectory, and respecting that prefix in our linkgit\ndefinitions.\n\nWe only have to modify the html linkgit definition. For\nmanpages, we can ignore this for two reasons:\n\n 1. we do not generate actual links to the file in\n manpages, but instead just give the name and section of\n the linked manpage\n\n 2. we do not currently build manpages for subdirectories,\n only html\n\nSigned-off-by: Jeff King \n---\n Documentation/Makefile | 2 ++\n Documentation/asciidoc.conf | 2 +-\n 2 files changed, 3 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 14286cb..b3693c8 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -280,6 +280,7 @@ technical/api-index.txt: technical/api-index-skel.txt \\\n \ttechnical/api-index.sh $(patsubst %,%.txt,$(API_DOCS))\n \t$(QUIET_GEN)cd technical && '$(SHELL_PATH_SQ)' ./api-index.sh\n \n+technical/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../\n $(patsubst %,%.html,$(API_DOCS) technical/api-index): %.html : %.txt\n \t$(QUIET_ASCIIDOC)$(ASCIIDOC) -b xhtml11 -f asciidoc.conf \\\n \t\t$(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) $*.txt\n@@ -333,6 +334,7 @@ $(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt\n \n WEBDOC_DEST = /pub/software/scm/git/docs\n \n+howto/%.html: ASCIIDOC_EXTRA += git-relative-html-prefix=../\n $(patsubst %.txt,%.html,$(wildcard howto/*.txt)): %.html : %.txt\n \t$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \\\n \tsed -e '1,/^$$/d' $< | $(ASCIIDOC) $(ASCIIDOC_EXTRA) -b xhtml11 - >$@+ && \\\ndiff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf\nindex aea8627..6d06271 100644\n--- a/Documentation/asciidoc.conf\n+++ b/Documentation/asciidoc.conf\n@@ -91,5 +91,5 @@ endif::doctype-manpage[]\n \n ifdef::backend-xhtml11[]\n [linkgit-inlinemacro]\n-{target}{0?({0})}\n+{target}{0?({0})}\n endif::backend-xhtml11[]\n-- \n1.7.11.rc1.3.gf8b4f5c\n"},{"id":"192877","messageId":"20120605073626.GD25809@sigill.intra.peff.net","threadId":"30692","inReplyTo":"1338841064-32294-2-git-send-email-Matthieu.Moy@imag.fr","subject":"Re: [PATCH 2/4 v2] api-credential.txt: show the big picture first","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2012-06-05T07:36:26Z","receivedAt":"2012-06-05T07:36:26Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Mon, Jun 04, 2012 at 10:17:42PM +0200, Matthieu Moy wrote:\n\n> The API documentation targets two kinds of developers: those using the\n> (C) API, and those writing remote-helpers. The document was not clear\n> about which part was useful to which category, and for example, the C API\n> could be mistakenly thought as an API for writting remote helpers.\n> \n> Based-on-patch-by: Jeff King \n> Signed-off-by: Matthieu Moy \n> ---\n> Fixed typos noted by Jeff.\n\nThanks. Patches 2-4 look OK content-wise. If you replace 1/4 with my\nrelative-html-prefix patch, then all of the \"../\" ugliness can go away.\n\n-Peff\n"},{"id":"192891","messageId":"vpqaa0ij98q.fsf@bauges.imag.fr","threadId":"30692","inReplyTo":"20120605073403.GC25809@sigill.intra.peff.net","subject":"Re: [PATCH 3/3] api-credentials.txt: add \"see also\" section","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@grenoble-inp.fr","sentAt":"2012-06-05T11:20:21Z","receivedAt":"2012-06-05T11:20:21Z","isPatch":true,"sender":{"key":"matthieu.moy@grenoble-inp.fr","avatar":"https://gravatar.com/avatar/72c8a2705971a25dfaff23cece15130d405685845d911aedd5667ace277f3fc5?d=mp&s=160"},"body":"Jeff King writes:\n\n>> I wonder if we could even make asciidoc work to convert\n>> linkgit:git-config[1] into the right path (i.e., to include the \"..\"\n>> automatically) when we are in the subdir.\n\nWhy not. I don't really care about eye candiness in technical/, but it\ncan make sense to make an effort at least for howto/ (which doesn't\ncontain links as of now, though).\n\n> diff --git a/Documentation/Makefile b/Documentation/Makefile\n> index 14286cb..b3693c8 100644\n> --- a/Documentation/Makefile\n> +++ b/Documentation/Makefile\n> @@ -280,6 +280,7 @@ technical/api-index.txt: technical/api-index-skel.txt \\\n> \ttechnical/api-index.sh $(patsubst %,%.txt,$(API_DOCS))\n> \t$(QUIET_GEN)cd technical && '$(SHELL_PATH_SQ)' ./api-index.sh\n> \n> +technical/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../\n> $(patsubst %,%.html,$(API_DOCS) technical/api-index): %.html : %.txt\n> \t$(QUIET_ASCIIDOC)$(ASCIIDOC) -b xhtml11 -f asciidoc.conf \\\n> \t\t$(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) $*.txt\n> @@ -333,6 +334,7 @@ $(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt\n> \n> WEBDOC_DEST = /pub/software/scm/git/docs\n> \n> +howto/%.html: ASCIIDOC_EXTRA += git-relative-html-prefix=../\n\nDon't you miss a \"-a\" between += and git-relative-html-prefix?\n\n-- \nMatthieu Moy\nhttp://www-verimag.imag.fr/~moy/\n"},{"id":"192892","messageId":"20120605112209.GA1976@sigill.intra.peff.net","threadId":"30692","inReplyTo":"vpqaa0ij98q.fsf@bauges.imag.fr","subject":"Re: [PATCH 3/3] api-credentials.txt: add \"see also\" section","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2012-06-05T11:22:09Z","receivedAt":"2012-06-05T11:22:09Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Tue, Jun 05, 2012 at 01:20:21PM +0200, Matthieu Moy wrote:\n\n> > diff --git a/Documentation/Makefile b/Documentation/Makefile\n> > index 14286cb..b3693c8 100644\n> > --- a/Documentation/Makefile\n> > +++ b/Documentation/Makefile\n> > @@ -280,6 +280,7 @@ technical/api-index.txt: technical/api-index-skel.txt \\\n> > \ttechnical/api-index.sh $(patsubst %,%.txt,$(API_DOCS))\n> > \t$(QUIET_GEN)cd technical && '$(SHELL_PATH_SQ)' ./api-index.sh\n> > \n> > +technical/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../\n> > $(patsubst %,%.html,$(API_DOCS) technical/api-index): %.html : %.txt\n> > \t$(QUIET_ASCIIDOC)$(ASCIIDOC) -b xhtml11 -f asciidoc.conf \\\n> > \t\t$(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) $*.txt\n> > @@ -333,6 +334,7 @@ $(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt\n> > \n> > WEBDOC_DEST = /pub/software/scm/git/docs\n> > \n> > +howto/%.html: ASCIIDOC_EXTRA += git-relative-html-prefix=../\n> \n> Don't you miss a \"-a\" between += and git-relative-html-prefix?\n\nUgh, thank you. I added the line for howto/* while doing a final review\non the patch, but running \"make\" again did not actually trigger a\nrebuild).\n\n-Peff\n"},{"id":"192912","messageId":"7v1ultrdwi.fsf@alter.siamese.dyndns.org","threadId":"30692","inReplyTo":"20120605073403.GC25809@sigill.intra.peff.net","subject":"Re: [PATCH 3/3] api-credentials.txt: add \"see also\" section","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-06-05T15:12:29Z","receivedAt":"2012-06-05T15:12:29Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> On Tue, Jun 05, 2012 at 02:59:55AM -0400, Jeff King wrote:\n>\n>> I wonder if we could even make asciidoc work to convert\n>> linkgit:git-config[1] into the right path (i.e., to include the \"..\"\n>> automatically) when we are in the subdir.\n>> \n>> I don't really have a sense how powerful asciidoc macros are, but this\n>> seems like an obvious case that they should handle.\n>\n> Here is a simple fix. The Makefile bits are more hacky than I would\n> like. It would be really nice if the asciidoc macro could convert \"we\n> are working on X/Y/Z.html\" into \"we need ../../ to get to the relative\n> base\", but I don't think it is that flexible.\n>\n> We could also replace asciidoc with a wrapper script that does the\n> conversion and sets the appropriate attribute. I don't know if it is\n> worth the trouble. It's not like we add documentation subdirectories\n> very often.\n\nSorry, but I am not sure what problem is this trying to solve. An\nAPI documentation page should only refer to command documentaion\npages, and never another API documentation page that is at the same\nlevel?\n\n> -- >8 --\n> Subject: docs: fix cross-directory linkgit references\n>\n> Most of our documentation is in a single directory, so using\n> linkgit:git-config[1] just generates a relative link in the\n> same directory. However, this is not the case with the API\n> documentation in technical/*, which need to refer to\n> git-config from the parent directory.\n>\n> We can fix this by passing a special prefix attribute when building\n> in a subdirectory, and respecting that prefix in our linkgit\n> definitions.\n>\n> We only have to modify the html linkgit definition. For\n> manpages, we can ignore this for two reasons:\n>\n> 1. we do not generate actual links to the file in\n> manpages, but instead just give the name and section of\n> the linked manpage\n>\n> 2. we do not currently build manpages for subdirectories,\n> only html\n>\n> Signed-off-by: Jeff King \n> ---\n> Documentation/Makefile | 2 ++\n> Documentation/asciidoc.conf | 2 +-\n> 2 files changed, 3 insertions(+), 1 deletion(-)\n>\n> diff --git a/Documentation/Makefile b/Documentation/Makefile\n> index 14286cb..b3693c8 100644\n> --- a/Documentation/Makefile\n> +++ b/Documentation/Makefile\n> @@ -280,6 +280,7 @@ technical/api-index.txt: technical/api-index-skel.txt \\\n> \ttechnical/api-index.sh $(patsubst %,%.txt,$(API_DOCS))\n> \t$(QUIET_GEN)cd technical && '$(SHELL_PATH_SQ)' ./api-index.sh\n> \n> +technical/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../\n> $(patsubst %,%.html,$(API_DOCS) technical/api-index): %.html : %.txt\n> \t$(QUIET_ASCIIDOC)$(ASCIIDOC) -b xhtml11 -f asciidoc.conf \\\n> \t\t$(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) $*.txt\n> @@ -333,6 +334,7 @@ $(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt\n> \n> WEBDOC_DEST = /pub/software/scm/git/docs\n> \n> +howto/%.html: ASCIIDOC_EXTRA += git-relative-html-prefix=../\n> $(patsubst %.txt,%.html,$(wildcard howto/*.txt)): %.html : %.txt\n> \t$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \\\n> \tsed -e '1,/^$$/d' $< | $(ASCIIDOC) $(ASCIIDOC_EXTRA) -b xhtml11 - >$@+ && \\\n> diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf\n> index aea8627..6d06271 100644\n> --- a/Documentation/asciidoc.conf\n> +++ b/Documentation/asciidoc.conf\n> @@ -91,5 +91,5 @@ endif::doctype-manpage[]\n> \n> ifdef::backend-xhtml11[]\n> [linkgit-inlinemacro]\n> -{target}{0?({0})}\n> +{target}{0?({0})}\n> endif::backend-xhtml11[]\n"},{"id":"192913","messageId":"20120605153512.GA20148@sigill.intra.peff.net","threadId":"30692","inReplyTo":"7v1ultrdwi.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH 3/3] api-credentials.txt: add \"see also\" section","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2012-06-05T15:35:12Z","receivedAt":"2012-06-05T15:35:12Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Tue, Jun 05, 2012 at 08:12:29AM -0700, Junio C Hamano wrote:\n\n> > Here is a simple fix. The Makefile bits are more hacky than I would\n> > like. It would be really nice if the asciidoc macro could convert \"we\n> > are working on X/Y/Z.html\" into \"we need ../../ to get to the relative\n> > base\", but I don't think it is that flexible.\n> >\n> > We could also replace asciidoc with a wrapper script that does the\n> > conversion and sets the appropriate attribute. I don't know if it is\n> > worth the trouble. It's not like we add documentation subdirectories\n> > very often.\n> \n> Sorry, but I am not sure what problem is this trying to solve. An\n> API documentation page should only refer to command documentaion\n> pages, and never another API documentation page that is at the same\n> level?\n\nNo, but it should not use linkgit to do so (and if we did ever grow\nlinkgit targets in a subdirectory, it should call them with the full\ndirectory name from the documentation root, just as documents in the\nroot would do).\n\n-Peff\n"},{"id":"192932","messageId":"7v1ultpt0q.fsf@alter.siamese.dyndns.org","threadId":"30692","inReplyTo":"20120605153512.GA20148@sigill.intra.peff.net","subject":"Re: [PATCH 3/3] api-credentials.txt: add \"see also\" section","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-06-05T17:28:53Z","receivedAt":"2012-06-05T17:28:53Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> No, but it should not use linkgit to do so\n\nAh, of course, because linkgit is about manual pages with sections.\n\nThanks.\n"}]}