Bad Man Page URLs

Hello,

I noticed this in 1.7.7.3, but just rebuilt 1.7.9.6 from source on OS X Lion and am still seeing it. These are the links at the end of `man git`:

NOTES
        1. Everyday Git
           file:///home/junio/share/doc/git-doc/everyday.html

        2. Git User's Manual
           file:///home/junio/share/doc/git-doc/user-manual.html

        3. git concepts chapter of the user-manual
           file:///home/junio/share/doc/git-doc/user-manual.html#git-concepts

        4. howto
           file:///home/junio/share/doc/git-doc/howto-index.html

        5. GIT API documentation
           file:///home/junio/share/doc/git-doc/technical/api-index.html

        6. git@vger.kernel.org
           mailto:git@vger.kernel.org

Those URLs are sadly not useful. :-( FYI, here’s the script I use to build Git:

  https://github.com/theory/my-cap/blob/master/bin/git.sh

Note that the man pages are installed with these two lines:

    curl -O http://git-core.googlecode.com/files/git-manpages-$VERSION.tar.gz
    sudo tar xzv -C /usr/local/share/man -f git-manpages-$VERSION.tar.gz

Is there a bug reporting system I should report this to?

Thanks,

David

On Thu, Apr 05, 2012 at 06:48:19PM -0700, David E. Wheeler wrote:

I noticed this in 1.7.7.3, but just rebuilt 1.7.9.6 from source on OS
X Lion and am still seeing it. These are the links at the end of `man
git`:
[...]

quoted

        1. Everyday Git
           file:///home/junio/share/doc/git-doc/everyday.html

The problem is that you are not really rebuilding the manpages at all,
but rather just untarring prebuilt copies. If you built them yourself,
they would have the proper prefix for your system.

That being said, it would be nice for the prebuilt manpages to have
something more location-agnostic in them. These links are generated by
asciidoc's "link:" directive. The HTML versions properly use relative
links, but the links are expanded into full URLs for the manpages. Which
makes sense, since there's no concept of a relative link here.

So we can tweak it by using a custom link macro (we already have
"linkgit" for linking to actual commands). But what should the agnostic
version say? Just saying "look at everday.html in the git documentation"
is not as nice as a real URL, but we really don't have any more
information than that. Maybe they should be pointing to some canonical
version on the web?

Is there a bug reporting system I should report this to?

This list, and you just did. :)

-Peff

On Thu, Apr 05, 2012 at 10:32:23PM -0400, Jeff King wrote:

That being said, it would be nice for the prebuilt manpages to have
something more location-agnostic in them. These links are generated by
asciidoc's "link:" directive. The HTML versions properly use relative
links, but the links are expanded into full URLs for the manpages. Which
makes sense, since there's no concept of a relative link here.

So we can tweak it by using a custom link macro (we already have
"linkgit" for linking to actual commands). But what should the agnostic
version say? Just saying "look at everday.html in the git documentation"
is not as nice as a real URL, but we really don't have any more
information than that. Maybe they should be pointing to some canonical
version on the web?

I dug on this a little more. It seems that the "link" macro in asciidoc
is overridable, so we could just redefine it as appropriate. However,
the existing implementation actually generates a reasonable-looking
docbook <ulink>, and it is docbook that is responsible for turning it
into an absolute URL.

So I think technically the docbook part of the toolchain would be the
right place to fix this. But it may be easier to hack around it at the
asciidoc level.

Something like the code below would work:

diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf
index aea8627..1edbabe 100644
--- a/Documentation/asciidoc.conf
+++ b/Documentation/asciidoc.conf

@@ -93,3 +93,10 @@ ifdef::backend-xhtml11[]
 [linkgit-inlinemacro]
 <a href="{target}.html">{target}{0?({0})}</a>
 endif::backend-xhtml11[]
+
+ifdef::generic-location[]
+ifdef::backend-docbook[]
+[link-inlinemacro]
+<ulink url="http://official-location/{target}">{0={target}}</ulink>
+endif::backend-docbook[]
+endif::generic-location[]

though it assumes that link targets are relative. There are a handful of
instances where that is not the case (we can either introduce a linkabs
for them, or leave them and switch most of the existing link: macros
over to linkrel: or something).

-Peff

Jeff King wrote:

So I think technically the docbook part of the toolchain would be the
right place to fix this. But it may be easier to hack around it at the
asciidoc level.

Isn't this what MAN_BASE_URL in Documentation/Makefile is for?  I
don't think a lower level fix is needed.

On Thu, Apr 05, 2012 at 11:22:15PM -0500, Jonathan Nieder wrote:

Jeff King wrote:

quoted

So I think technically the docbook part of the toolchain would be the
right place to fix this. But it may be easier to hack around it at the
asciidoc level.

Isn't this what MAN_BASE_URL in Documentation/Makefile is for?  I
don't think a lower level fix is needed.

Thanks for a dose of sanity. Having been here so long, I sometimes think
that if something exists in git, I would already know about it. But
sometimes that is not true. :)

Junio, what do you think of building the git-manpages-* tarballs (and
the git-manpages repo) with MAN_BASE_URL set to "http://some-official-place/"?
As of now, they mention "file:///home/junio/...".

We could need to have an official place, of course. I'd rather not use
http://schacon.github.com/git/docs because these links will be embedded
in release tarballs. Maybe it is time to make http://git-scm.com/docs
happen.

-Peff

Jeff King wrote:

Junio, what do you think of building the git-manpages-* tarballs (and
the git-manpages repo) with MAN_BASE_URL set to "http://some-official-place/"?
As of now, they mention "file:///home/junio/...".

Could be as simple as this, no?

Signed-off-by: Jonathan Nieder <redacted>
---
 Documentation/Makefile |   10 ++++++++--
 Makefile               |    1 +
 2 files changed, 9 insertions(+), 2 deletions(-)

diff --git i/Documentation/Makefile w/Documentation/Makefile
index d40e211f..0edad3a2 100644
--- i/Documentation/Makefile
+++ w/Documentation/Makefile

@@ -248,8 +248,14 @@ $(MAN_HTML): %.html : %.txt
 		$(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< && \
 	mv $@+ $@
 
-manpage-base-url.xsl: manpage-base-url.xsl.in
-	sed "s|@@MAN_BASE_URL@@|$(MAN_BASE_URL)|" $< > $@
+manpage-base-url.xsl: manpage-base-url.xsl.in FORCE
+	$(QUIET_GEN)$(RM) $@+ && \
+	sed "s|@@MAN_BASE_URL@@|$(MAN_BASE_URL)|" $< > $@+ && \
+	if test -e $@ && cmp -s $@+ $@; then \
+		$(RM) $@+; \
+	else \
+		mv $@+ $@; \
+	fi
 
 %.1 %.5 %.7 : %.xml manpage-base-url.xsl
 	$(QUIET_XMLTO)$(RM) $@ && \

diff --git i/Makefile w/Makefile
index be1957a5..ce6f805c 100644
--- i/Makefile
+++ w/Makefile

@@ -2623,6 +2623,7 @@ dist-doc:
 	$(RM) -r .doc-tmp-dir
 	mkdir -p .doc-tmp-dir/man1 .doc-tmp-dir/man5 .doc-tmp-dir/man7
 	$(MAKE) -C Documentation DESTDIR=./ \
+		MAN_BASE_URL=git-htmldocs/ \
 		man1dir=../.doc-tmp-dir/man1 \
 		man5dir=../.doc-tmp-dir/man5 \
 		man7dir=../.doc-tmp-dir/man7 \

--