[PATCH 0/3] Improve credential API documentation

[PATCH 0/3] Improve credential API documentation

[Matthieu Moy]

Follow-up to the discussion here:
http://thread.gmane.org/gmane.comp.version-control.git/198409

Matthieu Moy (3):
  api-credential.txt: show the big picture first
  api-credentials.txt: mention credential.helper explicitly
  api-credentials.txt: add "see also" section

 Documentation/technical/api-credentials.txt | 60 +++++++++++++++++++++++++++--
 1 file changed, 56 insertions(+), 4 deletions(-)

-- 
1.7.11.rc0.57.g84a04c7

[PATCH 1/3] api-credential.txt: show the big picture first

[Matthieu Moy]

The API documentation targets two kinds of developers: those using the
(C) API, and those writing remote-helpers. The document was not clear
about which part was useful to which category, and for example, the C API
could be mistakenly thought as an API for writting remote helpers.

Based-on-patch-by: Jeff King <peff@peff.net>
Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
---
I took Jeff's explanation, but I insist in having a picture ;-).

I made the picture more generic compared to my first proposal, and
just mention remote-helper in the text (I originally was wondering
whether this API could be used from a helper, since the helper has its
STDIN and STDOUT bound to the main Git process already, so this
explanation would have avoided the confusion for me).

 Documentation/technical/api-credentials.txt | 50 +++++++++++++++++++++++++++--
 1 file changed, 47 insertions(+), 3 deletions(-)

diff --git a/Documentation/technical/api-credentials.txt b/Documentation/technical/api-credentials.txt
index 21ca6a2..8804c42 100644
--- a/Documentation/technical/api-credentials.txt
+++ b/Documentation/technical/api-credentials.txt
@@ -6,8 +6,52 @@ password credentials from the user (even though credentials in the wider
 world can take many forms, in this document the word "credential" always
 refers to a username and password pair).
 
+This document describes two interfaces: the C API that the credential
+subsystem provides to the rest of git, and the protocol that git uses to
+communicate with system-specific "credential helpers". If you are
+writing git code that wants to look up or prompt for credentials, see
+the section "C API" below. If you want to write your own helper, see
+the section on "Credential Helpers" below.
+
+Typical setup
+-------------
+
+------------
++-----------------------+
+| git code (C)          |--- to server requiring --->
+|                       |        authentication
+|.......................|
+| C credential API      |--- prompt ---> User
++-----------------------+
+        ^      |
+        | pipe |
+        |      v
++-----------------------+
+| git credential helper |
++-----------------------+
+------------
+
+The git code (typically a remote-helper) will call the C API to obtain
+credential data like a login/password couple (credential_fill). The
+API will itself call a remote helper (e.g. "git credential-cache" or
+"git credential-store") that may retrieve credential data from a
+store. If the credential helper cannot find the information, the C API
+will prompt the user. Then, the caller of the API takes care of
+contacting the server, and do the actual authentication.
+
+C API
+-----
+
+The credential C API is meant to be called by git code which needs to
+acquire or store a credential. It is centered around an object
+representing a single credential and provides three basic operations:
+fill (acquire credentials by calling helpers and/or prompting the user),
+approve (mark a credential as successfully used so that it can be stored
+for later use), and reject (mark a credential as unsuccessful so that it
+can be erased from any persistent storage).
+
 Data Structures
----------------
+~~~~~~~~~~~~~~~
 
 `struct credential`::
 
@@ -28,7 +72,7 @@ This struct should always be initialized with `CREDENTIAL_INIT` or
 
 
 Functions
----------
+~~~~~~~~~
 
 `credential_init`::
 
@@ -72,7 +116,7 @@ Functions
 	Parse a URL into broken-down credential fields.
 
 Example
--------
+~~~~~~~
 
 The example below shows how the functions of the credential API could be
 used to login to a fictitious "foo" service on a remote host:
-- 
1.7.11.rc0.57.g84a04c7

[PATCH 2/3] api-credentials.txt: mention credential.helper explicitly

[Matthieu Moy]

The name of the configuration variable was mentioned only at the very
end of the explanation, in a place specific to a specific rule, hence it
was not very clear what the specification was about.

Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
---
 Documentation/technical/api-credentials.txt | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/technical/api-credentials.txt b/Documentation/technical/api-credentials.txt
index 8804c42..4561469 100644
--- a/Documentation/technical/api-credentials.txt
+++ b/Documentation/technical/api-credentials.txt
@@ -179,7 +179,8 @@ credentials from and to long-term storage (where "long-term" is simply
 longer than a single git process; e.g., credentials may be stored
 in-memory for a few minutes, or indefinitely on disk).
 
-Each helper is specified by a single string. The string is transformed
+Each helper is specified by a single string in the configuration
+variable credential.helper. The string is transformed
 by git into a command to be executed using these rules:
 
   1. If the helper string begins with "!", it is considered a shell
-- 
1.7.11.rc0.57.g84a04c7

[PATCH 3/3] api-credentials.txt: add "see also" section

[Matthieu Moy]

Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
---
 Documentation/technical/api-credentials.txt | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/Documentation/technical/api-credentials.txt b/Documentation/technical/api-credentials.txt
index 4561469..ac6be31 100644
--- a/Documentation/technical/api-credentials.txt
+++ b/Documentation/technical/api-credentials.txt
@@ -288,3 +288,10 @@ request.
 If a helper receives any other operation, it should silently ignore the
 request. This leaves room for future operations to be added (older
 helpers will just ignore the new requests).
+
+See also
+--------
+
+linkgit:../gitcredentials[7]
+
+linkgit:../git-config[5] (See configuration variables `credential.*`)
-- 
1.7.11.rc0.57.g84a04c7

Re: [PATCH 3/3] api-credentials.txt: add "see also" section

[Junio C Hamano]

Matthieu Moy <Matthieu.Moy@imag.fr> writes:

> diff --git a/Documentation/technical/api-credentials.txt b/Documentation/technical/api-credentials.txt
> index 4561469..ac6be31 100644
> --- a/Documentation/technical/api-credentials.txt
> +++ b/Documentation/technical/api-credentials.txt
> @@ -288,3 +288,10 @@ request.
>  If a helper receives any other operation, it should silently ignore the
>  request. This leaves room for future operations to be added (older
>  helpers will just ignore the new requests).
> +
> +See also
> +--------
> +
> +linkgit:../gitcredentials[7]
> +
> +linkgit:../git-config[5] (See configuration variables `credential.*`)

Thanks.  All looked good.

This is the first one that refers to "../something" with "linkgit:";
do they format sensibly?

Re: [PATCH 3/3] api-credentials.txt: add "see also" section

[Matthieu Moy]

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

> Thanks.  All looked good.
>
> This is the first one that refers to "../something" with "linkgit:";
> do they format sensibly?

On my machine (Debian stable), the HTML formatting is correct (and BTW,
the other instance of linkgit in technical, "(see
linkgit:gitattributes[5])" is broken). One can see the .. in the link,
but at least the target of the link is OK. I didn't worry too much about
formatting since this is a technical documentation.

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

Re: [PATCH 1/3] api-credential.txt: show the big picture first

[Jeff King]

On Sun, Jun 03, 2012 at 06:10:02PM +0200, Matthieu Moy wrote:

> The API documentation targets two kinds of developers: those using the
> (C) API, and those writing remote-helpers. The document was not clear
> about which part was useful to which category, and for example, the C API
> could be mistakenly thought as an API for writting remote helpers.
> 
> Based-on-patch-by: Jeff King <peff@peff.net>
> Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
> ---
> I took Jeff's explanation, but I insist in having a picture ;-).

Thanks. I had meant to follow-up, but it was among the least interesting
things for me to work on, so I procrastinated. And here I am being
rewarded for it with somebody else doing the work. :)

Looks good overall to me. Two minor comments:

> +The git code (typically a remote-helper) will call the C API to obtain
> +credential data like a login/password couple (credential_fill). The

I found the word "couple" odd here; I think "pair" would be more
idiomatic English.

> +API will itself call a remote helper (e.g. "git credential-cache" or
> +"git credential-store") that may retrieve credential data from a
> +store. If the credential helper cannot find the information, the C API
> +will prompt the user. Then, the caller of the API takes care of
> +contacting the server, and do the actual authentication.

s/do/does/

-Peff

Re: [PATCH 2/3] api-credentials.txt: mention credential.helper explicitly

[Jeff King]

On Sun, Jun 03, 2012 at 06:10:03PM +0200, Matthieu Moy wrote:

> The name of the configuration variable was mentioned only at the very
> end of the explanation, in a place specific to a specific rule, hence it
> was not very clear what the specification was about.
> 
> Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
> ---
>  Documentation/technical/api-credentials.txt | 3 ++-
>  1 file changed, 2 insertions(+), 1 deletion(-)
> 
> diff --git a/Documentation/technical/api-credentials.txt b/Documentation/technical/api-credentials.txt
> index 8804c42..4561469 100644
> --- a/Documentation/technical/api-credentials.txt
> +++ b/Documentation/technical/api-credentials.txt
> @@ -179,7 +179,8 @@ credentials from and to long-term storage (where "long-term" is simply
>  longer than a single git process; e.g., credentials may be stored
>  in-memory for a few minutes, or indefinitely on disk).
>  
> -Each helper is specified by a single string. The string is transformed
> +Each helper is specified by a single string in the configuration
> +variable credential.helper. The string is transformed
>  by git into a command to be executed using these rules:

They may be in other variables, too (like credential.*.helper). I don't
know if it is worth making that distinction.

Originally, helpers could also use these specification strings to chain
to each other, but in the current implementation, there is no chaining
(it was more important when prompting wasn't automatic, so storage
helpers would chain to prompting helpers). So I think we can disregard
that for now, and they really do just appear in config.

-Peff

Re: [PATCH 3/3] api-credentials.txt: add "see also" section

[Jeff King]

On Mon, Jun 04, 2012 at 01:31:30PM +0200, Matthieu Moy wrote:

> Junio C Hamano <gitster@pobox.com> writes:
> 
> > Thanks.  All looked good.
> >
> > This is the first one that refers to "../something" with "linkgit:";
> > do they format sensibly?
> 
> On my machine (Debian stable), the HTML formatting is correct (and BTW,
> the other instance of linkgit in technical, "(see
> linkgit:gitattributes[5])" is broken). One can see the .. in the link,
> but at least the target of the link is OK. I didn't worry too much about
> formatting since this is a technical documentation.

There is also a broken reference to linkgit:git-config[1] in
api-config.txt.

We only build html documentation from technical/, not manpages. So they
could just all be switched to link: (the point of linkgit is to format a
manpage reference from either html or a manpage).

-Peff

Re: [PATCH 2/3] api-credentials.txt: mention credential.helper explicitly

[Matthieu Moy]

Jeff King <peff@peff.net> writes:

> On Sun, Jun 03, 2012 at 06:10:03PM +0200, Matthieu Moy wrote:
>
>> --- a/Documentation/technical/api-credentials.txt
>> +++ b/Documentation/technical/api-credentials.txt
>> @@ -179,7 +179,8 @@ credentials from and to long-term storage (where "long-term" is simply
>>  longer than a single git process; e.g., credentials may be stored
>>  in-memory for a few minutes, or indefinitely on disk).
>>  
>> -Each helper is specified by a single string. The string is transformed
>> +Each helper is specified by a single string in the configuration
>> +variable credential.helper. The string is transformed
>>  by git into a command to be executed using these rules:
>
> They may be in other variables, too (like credential.*.helper). I don't
> know if it is worth making that distinction.
>
> Originally, helpers could also use these specification strings to chain
> to each other, but in the current implementation, there is no chaining
> (it was more important when prompting wasn't automatic, so storage
> helpers would chain to prompting helpers). So I think we can disregard
> that for now, and they really do just appear in config.

I'd say it is not worth making the distinction, but we may just say
"in the configuration variable credential.helper (and others, see
linkgit:../git-config.txt[1])" to be complete.

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

Re: [PATCH 3/3] api-credentials.txt: add "see also" section

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

>> On my machine (Debian stable), the HTML formatting is correct (and BTW,
>> the other instance of linkgit in technical, "(see
>> linkgit:gitattributes[5])" is broken).
>
> There is also a broken reference to linkgit:git-config[1] in
> api-config.txt.

Thanks; we should queue somthing like this.

-- >8 --
Subject: [PATCH] doc: fix xref link from api docs to manual pages

They are one-level above, so refer them as linkgit:../git-foo[n] with "../"

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/technical/api-config.txt | 2 +-
 Documentation/technical/api-merge.txt  | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/technical/api-config.txt b/Documentation/technical/api-config.txt
index edf8dfb..bd4d8b8 100644
--- a/Documentation/technical/api-config.txt
+++ b/Documentation/technical/api-config.txt
@@ -2,7 +2,7 @@ config API
 ==========
 
 The config API gives callers a way to access git configuration files
-(and files which have the same syntax). See linkgit:git-config[1] for a
+(and files which have the same syntax). See linkgit:../git-config[1] for a
 discussion of the config file syntax.
 
 General Usage
diff --git a/Documentation/technical/api-merge.txt b/Documentation/technical/api-merge.txt
index 9dc1bed..25158b8 100644
--- a/Documentation/technical/api-merge.txt
+++ b/Documentation/technical/api-merge.txt
@@ -36,7 +36,7 @@ the operation of a low-level (single file) merge.  Some options:
 	ancestors in a recursive merge.
 	If a helper program is specified by the
 	`[merge "<driver>"] recursive` configuration, it will
-	be used (see linkgit:gitattributes[5]).
+	be used (see linkgit:../gitattributes[5]).
 
 `variant`::
 	Resolve local conflicts automatically in favor
-- 
1.7.11.rc1.2.g33fe195

Re: [PATCH 3/3] api-credentials.txt: add "see also" section

[Matthieu Moy]

Jeff King <peff@peff.net> writes:

> We only build html documentation from technical/, not manpages. So they
> could just all be switched to link: (the point of linkgit is to format a
> manpage reference from either html or a manpage).

OTOH, using linkgit: makes it easier to cut-and-paste from technical/ to
man pages (which may be sensible for plumbing commands), so I think it's
OK to keep linkgit:.

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

[PATCH 1/4] doc: fix xref link from api docs to manual pages

[Matthieu Moy]

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

They are one-level above, so refer them as linkgit:../git-foo[n] with "../"

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
That's Junio's patch unmodified (I took it at the beginning of the
serie so that my linkgit:../ isn't the fist to appear)

 Documentation/technical/api-config.txt | 2 +-
 Documentation/technical/api-merge.txt  | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/technical/api-config.txt b/Documentation/technical/api-config.txt
index edf8dfb..bd4d8b8 100644
--- a/Documentation/technical/api-config.txt
+++ b/Documentation/technical/api-config.txt
@@ -2,7 +2,7 @@ config API
 ==========
 
 The config API gives callers a way to access git configuration files
-(and files which have the same syntax). See linkgit:git-config[1] for a
+(and files which have the same syntax). See linkgit:../git-config[1] for a
 discussion of the config file syntax.
 
 General Usage
diff --git a/Documentation/technical/api-merge.txt b/Documentation/technical/api-merge.txt
index 9dc1bed..25158b8 100644
--- a/Documentation/technical/api-merge.txt
+++ b/Documentation/technical/api-merge.txt
@@ -36,7 +36,7 @@ the operation of a low-level (single file) merge.  Some options:
 	ancestors in a recursive merge.
 	If a helper program is specified by the
 	`[merge "<driver>"] recursive` configuration, it will
-	be used (see linkgit:gitattributes[5]).
+	be used (see linkgit:../gitattributes[5]).
 
 `variant`::
 	Resolve local conflicts automatically in favor
-- 
1.7.11.rc0.57.g84a04c7

[PATCH 2/4 v2] api-credential.txt: show the big picture first

[Matthieu Moy]

The API documentation targets two kinds of developers: those using the
(C) API, and those writing remote-helpers. The document was not clear
about which part was useful to which category, and for example, the C API
could be mistakenly thought as an API for writting remote helpers.

Based-on-patch-by: Jeff King <peff@peff.net>
Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
---
Fixed typos noted by Jeff.

 Documentation/technical/api-credentials.txt | 50 +++++++++++++++++++++++++++--
 1 file changed, 47 insertions(+), 3 deletions(-)

diff --git a/Documentation/technical/api-credentials.txt b/Documentation/technical/api-credentials.txt
index 21ca6a2..2d6e811 100644
--- a/Documentation/technical/api-credentials.txt
+++ b/Documentation/technical/api-credentials.txt
@@ -6,8 +6,52 @@ password credentials from the user (even though credentials in the wider
 world can take many forms, in this document the word "credential" always
 refers to a username and password pair).
 
+This document describes two interfaces: the C API that the credential
+subsystem provides to the rest of git, and the protocol that git uses to
+communicate with system-specific "credential helpers". If you are
+writing git code that wants to look up or prompt for credentials, see
+the section "C API" below. If you want to write your own helper, see
+the section on "Credential Helpers" below.
+
+Typical setup
+-------------
+
+------------
++-----------------------+
+| git code (C)          |--- to server requiring --->
+|                       |        authentication
+|.......................|
+| C credential API      |--- prompt ---> User
++-----------------------+
+        ^      |
+        | pipe |
+        |      v
++-----------------------+
+| git credential helper |
++-----------------------+
+------------
+
+The git code (typically a remote-helper) will call the C API to obtain
+credential data like a login/password pair (credential_fill). The
+API will itself call a remote helper (e.g. "git credential-cache" or
+"git credential-store") that may retrieve credential data from a
+store. If the credential helper cannot find the information, the C API
+will prompt the user. Then, the caller of the API takes care of
+contacting the server, and does the actual authentication.
+
+C API
+-----
+
+The credential C API is meant to be called by git code which needs to
+acquire or store a credential. It is centered around an object
+representing a single credential and provides three basic operations:
+fill (acquire credentials by calling helpers and/or prompting the user),
+approve (mark a credential as successfully used so that it can be stored
+for later use), and reject (mark a credential as unsuccessful so that it
+can be erased from any persistent storage).
+
 Data Structures
----------------
+~~~~~~~~~~~~~~~
 
 `struct credential`::
 
@@ -28,7 +72,7 @@ This struct should always be initialized with `CREDENTIAL_INIT` or
 
 
 Functions
----------
+~~~~~~~~~
 
 `credential_init`::
 
@@ -72,7 +116,7 @@ Functions
 	Parse a URL into broken-down credential fields.
 
 Example
--------
+~~~~~~~
 
 The example below shows how the functions of the credential API could be
 used to login to a fictitious "foo" service on a remote host:
-- 
1.7.11.rc0.57.g84a04c7

[PATCH 3/4 v2] api-credentials.txt: mention credential.helper explicitly

[Matthieu Moy]

The name of the configuration variable was mentioned only at the very
end of the explanation, in a place specific to a specific rule, hence it
was not very clear what the specification was about.

Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
---
Added "and others" with a link to git-config(1), for completeness.

 Documentation/technical/api-credentials.txt | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/Documentation/technical/api-credentials.txt b/Documentation/technical/api-credentials.txt
index 2d6e811..969a1ff 100644
--- a/Documentation/technical/api-credentials.txt
+++ b/Documentation/technical/api-credentials.txt
@@ -179,8 +179,10 @@ credentials from and to long-term storage (where "long-term" is simply
 longer than a single git process; e.g., credentials may be stored
 in-memory for a few minutes, or indefinitely on disk).
 
-Each helper is specified by a single string. The string is transformed
-by git into a command to be executed using these rules:
+Each helper is specified by a single string in the configuration
+variable `credential.helper` (and others, see
+linkgit:../git-config[1]). The string is transformed by git into a
+command to be executed using these rules:
 
   1. If the helper string begins with "!", it is considered a shell
      snippet, and everything after the "!" becomes the command.
-- 
1.7.11.rc0.57.g84a04c7

[PATCH 4/4 v2] api-credentials.txt: add "see also" section

[Matthieu Moy]

Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
---
Unmodified since v1.

 Documentation/technical/api-credentials.txt | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/Documentation/technical/api-credentials.txt b/Documentation/technical/api-credentials.txt
index 969a1ff..597521b 100644
--- a/Documentation/technical/api-credentials.txt
+++ b/Documentation/technical/api-credentials.txt
@@ -289,3 +289,10 @@ request.
 If a helper receives any other operation, it should silently ignore the
 request. This leaves room for future operations to be added (older
 helpers will just ignore the new requests).
+
+See also
+--------
+
+linkgit:../gitcredentials[7]
+
+linkgit:../git-config[5] (See configuration variables `credential.*`)
-- 
1.7.11.rc0.57.g84a04c7

Re: [PATCH 3/3] api-credentials.txt: add "see also" section

[Jeff King]

On Mon, Jun 04, 2012 at 10:06:34PM +0200, Matthieu Moy wrote:

> Jeff King <peff@peff.net> writes:
> 
> > We only build html documentation from technical/, not manpages. So they
> > could just all be switched to link: (the point of linkgit is to format a
> > manpage reference from either html or a manpage).
> 
> OTOH, using linkgit: makes it easier to cut-and-paste from technical/ to
> man pages (which may be sensible for plumbing commands), so I think it's
> OK to keep linkgit:.

Except that you cannot cut-and-paste, since it has ".." in it. :)

But yeah, I guess it does have some other niceties, like adding the
".html" on the end, converting git-config[1] into the right text, etc. I
was just thinking that by using link: directly, we would make it look
nicer (e.g., drop the ".." from the actual link text). Maybe we can even
strip that in the macro, though.

I wonder if we could even make asciidoc work to convert
linkgit:git-config[1] into the right path (i.e., to include the ".."
automatically) when we are in the subdir.

I don't really have a sense how powerful asciidoc macros are, but this
seems like an obvious case that they should handle.

-Peff

Re: [PATCH 3/3] api-credentials.txt: add "see also" section

[Jeff King]

On Tue, Jun 05, 2012 at 02:59:55AM -0400, Jeff King wrote:

> I wonder if we could even make asciidoc work to convert
> linkgit:git-config[1] into the right path (i.e., to include the ".."
> automatically) when we are in the subdir.
> 
> I don't really have a sense how powerful asciidoc macros are, but this
> seems like an obvious case that they should handle.

Here is a simple fix. The Makefile bits are more hacky than I would
like. It would be really nice if the asciidoc macro could convert "we
are working on X/Y/Z.html" into "we need ../../ to get to the relative
base", but I don't think it is that flexible.

We could also replace asciidoc with a wrapper script that does the
conversion and sets the appropriate attribute. I don't know if it is
worth the trouble. It's not like we add documentation subdirectories
very often.

-- >8 --
Subject: docs: fix cross-directory linkgit references

Most of our documentation is in a single directory, so using
linkgit:git-config[1] just generates a relative link in the
same directory. However, this is not the case with the API
documentation in technical/*, which need to refer to
git-config from the parent directory.

We can fix this by passing a special prefix attribute when building
in a subdirectory, and respecting that prefix in our linkgit
definitions.

We only have to modify the html linkgit definition.  For
manpages, we can ignore this for two reasons:

  1. we do not generate actual links to the file in
     manpages, but instead just give the name and section of
     the linked manpage

  2. we do not currently build manpages for subdirectories,
     only html

Signed-off-by: Jeff King <peff@peff.net>
---
 Documentation/Makefile      | 2 ++
 Documentation/asciidoc.conf | 2 +-
 2 files changed, 3 insertions(+), 1 deletion(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 14286cb..b3693c8 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -280,6 +280,7 @@ technical/api-index.txt: technical/api-index-skel.txt \
 	technical/api-index.sh $(patsubst %,%.txt,$(API_DOCS))
 	$(QUIET_GEN)cd technical && '$(SHELL_PATH_SQ)' ./api-index.sh
 
+technical/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../
 $(patsubst %,%.html,$(API_DOCS) technical/api-index): %.html : %.txt
 	$(QUIET_ASCIIDOC)$(ASCIIDOC) -b xhtml11 -f asciidoc.conf \
 		$(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) $*.txt
@@ -333,6 +334,7 @@ $(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt
 
 WEBDOC_DEST = /pub/software/scm/git/docs
 
+howto/%.html: ASCIIDOC_EXTRA += git-relative-html-prefix=../
 $(patsubst %.txt,%.html,$(wildcard howto/*.txt)): %.html : %.txt
 	$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
 	sed -e '1,/^$$/d' $< | $(ASCIIDOC) $(ASCIIDOC_EXTRA) -b xhtml11 - >$@+ && \
diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf
index aea8627..6d06271 100644
--- a/Documentation/asciidoc.conf
+++ b/Documentation/asciidoc.conf
@@ -91,5 +91,5 @@ endif::doctype-manpage[]
 
 ifdef::backend-xhtml11[]
 [linkgit-inlinemacro]
-<a href="{target}.html">{target}{0?({0})}</a>
+<a href="{git-relative-html-prefix}{target}.html">{target}{0?({0})}</a>
 endif::backend-xhtml11[]
-- 
1.7.11.rc1.3.gf8b4f5c

Re: [PATCH 2/4 v2] api-credential.txt: show the big picture first

[Jeff King]

On Mon, Jun 04, 2012 at 10:17:42PM +0200, Matthieu Moy wrote:

> The API documentation targets two kinds of developers: those using the
> (C) API, and those writing remote-helpers. The document was not clear
> about which part was useful to which category, and for example, the C API
> could be mistakenly thought as an API for writting remote helpers.
> 
> Based-on-patch-by: Jeff King <peff@peff.net>
> Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
> ---
> Fixed typos noted by Jeff.

Thanks. Patches 2-4 look OK content-wise. If you replace 1/4 with my
relative-html-prefix patch, then all of the "../" ugliness can go away.

-Peff

Re: [PATCH 3/3] api-credentials.txt: add "see also" section

[Matthieu Moy]

Jeff King <peff@peff.net> writes:

>> I wonder if we could even make asciidoc work to convert
>> linkgit:git-config[1] into the right path (i.e., to include the ".."
>> automatically) when we are in the subdir.

Why not. I don't really care about eye candiness in technical/, but it
can make sense to make an effort at least for howto/ (which doesn't
contain links as of now, though).

> diff --git a/Documentation/Makefile b/Documentation/Makefile
> index 14286cb..b3693c8 100644
> --- a/Documentation/Makefile
> +++ b/Documentation/Makefile
> @@ -280,6 +280,7 @@ technical/api-index.txt: technical/api-index-skel.txt \
>  	technical/api-index.sh $(patsubst %,%.txt,$(API_DOCS))
>  	$(QUIET_GEN)cd technical && '$(SHELL_PATH_SQ)' ./api-index.sh
>  
> +technical/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../
>  $(patsubst %,%.html,$(API_DOCS) technical/api-index): %.html : %.txt
>  	$(QUIET_ASCIIDOC)$(ASCIIDOC) -b xhtml11 -f asciidoc.conf \
>  		$(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) $*.txt
> @@ -333,6 +334,7 @@ $(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt
>  
>  WEBDOC_DEST = /pub/software/scm/git/docs
>  
> +howto/%.html: ASCIIDOC_EXTRA += git-relative-html-prefix=../

Don't you miss a "-a" between += and git-relative-html-prefix?

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

Re: [PATCH 3/3] api-credentials.txt: add "see also" section

[Jeff King]

On Tue, Jun 05, 2012 at 01:20:21PM +0200, Matthieu Moy wrote:

> > diff --git a/Documentation/Makefile b/Documentation/Makefile
> > index 14286cb..b3693c8 100644
> > --- a/Documentation/Makefile
> > +++ b/Documentation/Makefile
> > @@ -280,6 +280,7 @@ technical/api-index.txt: technical/api-index-skel.txt \
> >  	technical/api-index.sh $(patsubst %,%.txt,$(API_DOCS))
> >  	$(QUIET_GEN)cd technical && '$(SHELL_PATH_SQ)' ./api-index.sh
> >  
> > +technical/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../
> >  $(patsubst %,%.html,$(API_DOCS) technical/api-index): %.html : %.txt
> >  	$(QUIET_ASCIIDOC)$(ASCIIDOC) -b xhtml11 -f asciidoc.conf \
> >  		$(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) $*.txt
> > @@ -333,6 +334,7 @@ $(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt
> >  
> >  WEBDOC_DEST = /pub/software/scm/git/docs
> >  
> > +howto/%.html: ASCIIDOC_EXTRA += git-relative-html-prefix=../
> 
> Don't you miss a "-a" between += and git-relative-html-prefix?

Ugh, thank you. I added the line for howto/* while doing a final review
on the patch, but running "make" again did not actually trigger a
rebuild).

-Peff

Re: [PATCH 3/3] api-credentials.txt: add "see also" section

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> On Tue, Jun 05, 2012 at 02:59:55AM -0400, Jeff King wrote:
>
>> I wonder if we could even make asciidoc work to convert
>> linkgit:git-config[1] into the right path (i.e., to include the ".."
>> automatically) when we are in the subdir.
>> 
>> I don't really have a sense how powerful asciidoc macros are, but this
>> seems like an obvious case that they should handle.
>
> Here is a simple fix. The Makefile bits are more hacky than I would
> like. It would be really nice if the asciidoc macro could convert "we
> are working on X/Y/Z.html" into "we need ../../ to get to the relative
> base", but I don't think it is that flexible.
>
> We could also replace asciidoc with a wrapper script that does the
> conversion and sets the appropriate attribute. I don't know if it is
> worth the trouble. It's not like we add documentation subdirectories
> very often.

Sorry, but I am not sure what problem is this trying to solve.  An
API documentation page should only refer to command documentaion
pages, and never another API documentation page that is at the same
level?

> -- >8 --
> Subject: docs: fix cross-directory linkgit references
>
> Most of our documentation is in a single directory, so using
> linkgit:git-config[1] just generates a relative link in the
> same directory. However, this is not the case with the API
> documentation in technical/*, which need to refer to
> git-config from the parent directory.
>
> We can fix this by passing a special prefix attribute when building
> in a subdirectory, and respecting that prefix in our linkgit
> definitions.
>
> We only have to modify the html linkgit definition.  For
> manpages, we can ignore this for two reasons:
>
>   1. we do not generate actual links to the file in
>      manpages, but instead just give the name and section of
>      the linked manpage
>
>   2. we do not currently build manpages for subdirectories,
>      only html
>
> Signed-off-by: Jeff King <peff@peff.net>
> ---
>  Documentation/Makefile      | 2 ++
>  Documentation/asciidoc.conf | 2 +-
>  2 files changed, 3 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/Makefile b/Documentation/Makefile
> index 14286cb..b3693c8 100644
> --- a/Documentation/Makefile
> +++ b/Documentation/Makefile
> @@ -280,6 +280,7 @@ technical/api-index.txt: technical/api-index-skel.txt \
>  	technical/api-index.sh $(patsubst %,%.txt,$(API_DOCS))
>  	$(QUIET_GEN)cd technical && '$(SHELL_PATH_SQ)' ./api-index.sh
>  
> +technical/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../
>  $(patsubst %,%.html,$(API_DOCS) technical/api-index): %.html : %.txt
>  	$(QUIET_ASCIIDOC)$(ASCIIDOC) -b xhtml11 -f asciidoc.conf \
>  		$(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) $*.txt
> @@ -333,6 +334,7 @@ $(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt
>  
>  WEBDOC_DEST = /pub/software/scm/git/docs
>  
> +howto/%.html: ASCIIDOC_EXTRA += git-relative-html-prefix=../
>  $(patsubst %.txt,%.html,$(wildcard howto/*.txt)): %.html : %.txt
>  	$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
>  	sed -e '1,/^$$/d' $< | $(ASCIIDOC) $(ASCIIDOC_EXTRA) -b xhtml11 - >$@+ && \
> diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf
> index aea8627..6d06271 100644
> --- a/Documentation/asciidoc.conf
> +++ b/Documentation/asciidoc.conf
> @@ -91,5 +91,5 @@ endif::doctype-manpage[]
>  
>  ifdef::backend-xhtml11[]
>  [linkgit-inlinemacro]
> -<a href="{target}.html">{target}{0?({0})}</a>
> +<a href="{git-relative-html-prefix}{target}.html">{target}{0?({0})}</a>
>  endif::backend-xhtml11[]

Re: [PATCH 3/3] api-credentials.txt: add "see also" section

[Jeff King]

On Tue, Jun 05, 2012 at 08:12:29AM -0700, Junio C Hamano wrote:

> > Here is a simple fix. The Makefile bits are more hacky than I would
> > like. It would be really nice if the asciidoc macro could convert "we
> > are working on X/Y/Z.html" into "we need ../../ to get to the relative
> > base", but I don't think it is that flexible.
> >
> > We could also replace asciidoc with a wrapper script that does the
> > conversion and sets the appropriate attribute. I don't know if it is
> > worth the trouble. It's not like we add documentation subdirectories
> > very often.
> 
> Sorry, but I am not sure what problem is this trying to solve.  An
> API documentation page should only refer to command documentaion
> pages, and never another API documentation page that is at the same
> level?

No, but it should not use linkgit to do so (and if we did ever grow
linkgit targets in a subdirectory, it should call them with the full
directory name from the documentation root, just as documents in the
root would do).

-Peff

Re: [PATCH 3/3] api-credentials.txt: add "see also" section

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> No, but it should not use linkgit to do so

Ah, of course, because linkgit is about manual pages with sections.

Thanks.