From: Jeff King <peff@peff.net>
Date: Tue, 05 Jun 2012 06:59:55 GMT
Subject: Re: [PATCH 3/3] api-credentials.txt: add "see also" section
Message-ID: <20120605065955.GB25809@sigill.intra.peff.net>
In-Reply-To: <vpqpq9en8ol.fsf@bauges.imag.fr>

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