Bad Man Page URLs

Bad Man Page URLs

[David E. Wheeler]

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

Re: Bad Man Page URLs

[Jeff King]

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`:
> [...]
> >         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

Re: Bad Man Page URLs

[Jeff King]

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

Re: Bad Man Page URLs

[Jonathan Nieder]

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.

Re: Bad Man Page URLs

[Jeff King]

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

> 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.

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

Re: Bad Man Page URLs

[Jonathan Nieder]

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 <jrnieder@gmail.com>
---
 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 \
-- 

Re: Bad Man Page URLs

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> 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/...".

I think git-manpages repo already sets the base to the old k.org location
(see dodoc.sh in the 'todo' branch), but I forgot about that setting when
I cobbled together the tarball releasing script to be run on my home box
in a hurry. The releases used to be cut on a k.org machine and I initially
planned to stop generating the manpage/html tarballs when we lost shell
access to it, but some distro people demanded it, so...

I do not know how well things would behave if we set it to "git-htmldocs/"
as Jonathan suggests, but we will see what happens.

I think there is no need to patch any Makefile; the make variable is
designed to be overridable by the callers of make, so patches should go to
either 'dodoc.sh' or the tarball release scripts, which are not checked in
to the 'todo' branch yet, but I will do so if I remember ;-).

FWIW, here is the (updated) 'RelBuild' script.

-- >8 --
#!/bin/sh

version=$(git describe --exact) &&
label=$(echo "$version" | sed -e 's|^v||') &&
version=$(echo "$label" | sed -e 's|-|.|g') || exit

make clean && make dist &&

ASCIIDOC_NO_ROFF=YesPlease \
ASCIIDOC8=YesPlease \
MAN_BASE_URL="git-htmldocs/" \
make dist-doc || exit

# The above used to be
# MAN_BASE_URL="http://www.kernel.org/pub/software/scm/git/docs/"

files="
	git-$version.tar.gz
	git-htmldocs-$version.tar.gz
	git-manpages-$version.tar.gz
"

for file in $files
do
	test -f $file || exit
done

sha1sum $files | gpg --clearsign >git-$version.sign

ls -l git-$version.sign $files

Re: Bad Man Page URLs

[Jeff King]

On Fri, Apr 06, 2012 at 12:15:07AM -0700, Junio C Hamano 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/...".
> 
> I think git-manpages repo already sets the base to the old k.org location
> (see dodoc.sh in the 'todo' branch), but I forgot about that setting when
> I cobbled together the tarball releasing script to be run on my home box
> in a hurry.

Ah, I didn't notice that. The k.org location is dead, of course, but I
hope we will eventually turn it into at least a redirect to the official
location.

Scott, I know you've been working hard on the git-scm.com redesign. Any
word on when that will be ready, or whether it will contain a mirror of
the reference docs?

> I do not know how well things would behave if we set it to "git-htmldocs/"
> as Jonathan suggests, but we will see what happens.

Users will see reference to "git-htmldocs/everyday.html" in their
manpage. Not quite as nice as a real URL, but at least not entirely
misleading.

-Peff

Re: Bad Man Page URLs

[David E. Wheeler]

On Apr 6, 2012, at 12:15 AM, Junio C Hamano 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/...".
> 
> I think git-manpages repo already sets the base to the old k.org location
> (see dodoc.sh in the 'todo' branch), but I forgot about that setting when
> I cobbled together the tarball releasing script to be run on my home box
> in a hurry. The releases used to be cut on a k.org machine and I initially
> planned to stop generating the manpage/html tarballs when we lost shell
> access to it, but some distro people demanded it, so...
> 
> I do not know how well things would behave if we set it to "git-htmldocs/"
> as Jonathan suggests, but we will see what happens.
> 
> I think there is no need to patch any Makefile; the make variable is
> designed to be overridable by the callers of make, so patches should go to
> either 'dodoc.sh' or the tarball release scripts, which are not checked in
> to the 'todo' branch yet, but I will do so if I remember ;-).
> 
> FWIW, here is the (updated) 'RelBuild' script.

Don't know if you've applied this fix, but I just downloaded the 1.7.10 man pages, and they URLs are now:

        1. Everyday Git
           git-htmldocs/everyday.html

        2. Git User's Manual
           git-htmldocs/user-manual.html

        3. git concepts chapter of the user-manual
           git-htmldocs/user-manual.html#git-concepts

        4. howto
           git-htmldocs/howto-index.html

        5. GIT API documentation
           git-htmldocs/technical/api-index.html

Which also aren't very useful. :-(

David

Re: Bad Man Page URLs

[Jonathan Nieder]

David E. Wheeler wrote:

>         5. GIT API documentation
>            git-htmldocs/technical/api-index.html
>
> Which also aren't very useful. :-(

Sure they are --- they tell you where in the git-htmldocs tarball
from [1] to find the relevant pages.

Do you know of a public webpage we can count on to continue to serve
the docs?  I agree that that would be even better.

Hope that helps,
Jonathan

[1] http://code.google.com/p/git-core/downloads/list

Re: Bad Man Page URLs

[David E. Wheeler]

On Apr 26, 2012, at 1:19 PM, Jonathan Nieder wrote:

> Sure they are --- they tell you where in the git-htmldocs tarball
> from [1] to find the relevant pages.
> 
> Do you know of a public webpage we can count on to continue to serve
> the docs?  I agree that that would be even better.

All of those titles have links on gitmanual.org:

  http://www.gitmanual.org/

Although it looks like the “GIT API documentation” link is broken (404).

Best,

David

Re: Bad Man Page URLs

[Jonathan Nieder]

David E. Wheeler wrote:
> On Apr 26, 2012, at 1:19 PM, Jonathan Nieder wrote:

>> Do you know of a public webpage we can count on to continue to serve
>> the docs?  I agree that that would be even better.
>
> All of those titles have links on gitmanual.org:
>
>   http://www.gitmanual.org/

Who runs that webpage?  Would they mind the increased traffic?  Can we
count on them to continue to serve the docs?

Re: Bad Man Page URLs

[David E. Wheeler]

On Apr 26, 2012, at 1:29 PM, Jonathan Nieder wrote:

>> All of those titles have links on gitmanual.org:
>> 
>>  http://www.gitmanual.org/
> 
> Who runs that webpage?  Would they mind the increased traffic?  Can we
> count on them to continue to serve the docs?

Oh, not an official Git site? Seems to me that the project ought to have something like that. Many of the same links are on http://git-scm.com/documentation. As for gitmanual.org, whois says:

Registrant Name:Loic d'Anterroches
Registrant Organization:Ceondo Ltd
Registrant City:London
Registrant Email:pnwr10o0vs6u6a82ixx9@o.o-w-o.info

Best,

David

Re: Bad Man Page URLs

[Jakub Narebski]

"David E. Wheeler" <david@justatheory.com> writes:
> On Apr 26, 2012, at 1:29 PM, Jonathan Nieder wrote:
>>> 
>>> All of those titles have links on gitmanual.org:
>>> 
>>>  http://www.gitmanual.org/
>> 
>> Who runs that webpage?  Would they mind the increased traffic?  Can we
>> count on them to continue to serve the docs?
> 
> Oh, not an official Git site? Seems to me that the project ought to
> have something like that. Many of the same links are on
> http://git-scm.com/documentation.
>
> As for gitmanual.org, whois says:
> 
> Registrant Name:Loic d'Anterroches
> Registrant Organization:Ceondo Ltd
> Registrant City:London
> Registrant Email:pnwr10o0vs6u6a82ixx9@o.o-w-o.info

If I am not mistaken this is the person behind InDefero git hosting
site (http://www.indefero.net) and git hosting software powering it
(http://projects.ceondo.com/p/indefero) in PHP.

I don't remember it being announced on git mailing list...

-- 
Jakub Narebski

Re: Bad Man Page URLs

[Jeff King]

On Thu, Apr 26, 2012 at 03:19:22PM -0500, Jonathan Nieder wrote:

> David E. Wheeler wrote:
> 
> >         5. GIT API documentation
> >            git-htmldocs/technical/api-index.html
> >
> > Which also aren't very useful. :-(
> 
> Sure they are --- they tell you where in the git-htmldocs tarball
> from [1] to find the relevant pages.
> 
> Do you know of a public webpage we can count on to continue to serve
> the docs?  I agree that that would be even better.

I think http://git-scm.com/ would be the ideal place. My understanding
is that the re-work of the site is nearing completion. Scott, ETA?

-Peff

Re: Bad Man Page URLs

[Scott Chacon]

Hey,

On Thu, Apr 26, 2012 at 2:02 PM, Jeff King <peff@peff.net> wrote:
>>
>> Do you know of a public webpage we can count on to continue to serve
>> the docs?  I agree that that would be even better.
>
> I think http://git-scm.com/ would be the ideal place. My understanding
> is that the re-work of the site is nearing completion. Scott, ETA?

Yes, we are very close to launching a big redesign of git-scm.com.
The manpages will be automatically updated on that site, you can
certainly link to them there.

If you want to preview what it's going to look like and the URL
structure, you can check out the current working version here:

http://git-scm.herokuapp.com/docs/git-fetch

There are a number of known bugs and I want to make it much faster
before I officially launch it and redirect DNS, but you can get an
idea of how it will be structured and what it will look like.  If you
want to start generating docs with static urls for man pages, they can
be of the form: http://git-scm.com/docs/git-command

You can also put a version number after them to permalink them at a
certain version:

http://git-scm.herokuapp.com/docs/git-fetch/1.7.3.2

When it's close to what I think is ready, I'll do a post to this list
looking for feedback and bugs, etc.

Scott

>
> -Peff

Re: Bad Man Page URLs

[David E. Wheeler]

On Apr 26, 2012, at 2:58 PM, Scott Chacon wrote:

> Yes, we are very close to launching a big redesign of git-scm.com.
> The manpages will be automatically updated on that site, you can
> certainly link to them there.
> 
> If you want to preview what it's going to look like and the URL
> structure, you can check out the current working version here:
> 
> http://git-scm.herokuapp.com/docs/git-fetch

Wow, the new site looks *awesome*! :-)

> There are a number of known bugs and I want to make it much faster
> before I officially launch it and redirect DNS, but you can get an
> idea of how it will be structured and what it will look like.  If you
> want to start generating docs with static urls for man pages, they can
> be of the form: http://git-scm.com/docs/git-command
> 
> You can also put a version number after them to permalink them at a
> certain version:
> 
> http://git-scm.herokuapp.com/docs/git-fetch/1.7.3.2

Very nice. I only found one of the links from the manpage there, though:

  Everyday Git
  http://git-scm.herokuapp.com/docs/everyday.html

Here are the others on gitmanual.org (maybe I just couldn't find them on the new site?):

  User Manual
  http://www.gitmanual.org/user-manual.html

  git concepts chapter of the user-manual
  http://www.gitmanual.org/user-manual.html#git-concepts

  howto
  http://www.gitmanual.org/howto-index.html

And this one is a broken link on gitmanual.org and other places on the internetz.

  GIT API documentation
  ????

Best,

David

Re: Bad Man Page URLs

[Jonathan Nieder]

Scott Chacon wrote:
> On Thu, Apr 26, 2012 at 2:02 PM, Jeff King <peff@peff.net> wrote:

>>> Do you know of a public webpage we can count on to continue to serve
>>> the docs?  I agree that that would be even better.
>>
>> I think http://git-scm.com/ would be the ideal place. My understanding
>> is that the re-work of the site is nearing completion. Scott, ETA?
[...]
> If you want to preview what it's going to look like and the URL
> structure, you can check out the current working version here:
>
> http://git-scm.herokuapp.com/docs/git-fetch

Is it intended to include documents such as "technical/api-credentials"?
I ask because David was looking for some permanent place for the
references section of pages like gitcredentials(7) to link to.

Curious,
Jonathan

Re: Bad Man Page URLs

[Junio C Hamano]

Scott Chacon <schacon@gmail.com> writes:

> If you want to preview what it's going to look like and the URL
> structure, you can check out the current working version here:
>
> http://git-scm.herokuapp.com/docs/git-fetch

Nicely done.

Is it possible to have a link to Release Notes (not manual pages, which
you already have links to) for each release from "http://site/docs/git"
like we used to have at k.org site?  It is not a big deal, but that is
one thing I miss the most.

Re: Bad Man Page URLs

[Scott Chacon]

On Thu, Apr 26, 2012 at 3:16 PM, Junio C Hamano <gitster@pobox.com> wrote:
> Is it possible to have a link to Release Notes (not manual pages, which
> you already have links to) for each release from "http://site/docs/git"
> like we used to have at k.org site?  It is not a big deal, but that is
> one thing I miss the most.

Yes, this is pretty easy to do - just about everything in
Documentation/ will eventually be rendered - including the user-manual
that is currently missing and the release notes.

Scott

Re: Bad Man Page URLs

[Jonathan Nieder]

Scott Chacon wrote:

> Yes, this is pretty easy to do - just about everything in
> Documentation/ will eventually be rendered - including the user-manual
> that is currently missing and the release notes.

Nice. :)  Thanks much for doing this.

It seems from adaa3caf that to add the links to release notes, the
appropriate incantation is ASCIIDOC_EXTRA='-a stalenotes'.

Jonathan