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`:

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:

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?

This list, and you just did. :)

-Peff

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

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:

Jeff King wrote:

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:

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:

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(-)

Jeff King <peff@peff.net> writes:

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

On Fri, Apr 06, 2012 at 12:15:07AM -0700, Junio C Hamano wrote:

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?

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

On Apr 6, 2012, at 12:15 AM, Junio C Hamano wrote:

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

David E. Wheeler 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.

Hope that helps, Jonathan

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

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

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

David E. Wheeler wrote:

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

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

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

"David E. Wheeler" <david@justatheory.com> writes:

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

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

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

Hey,

On Thu, Apr 26, 2012 at 2:02 PM, Jeff King <peff@peff.net> 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

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

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

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

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

Scott Chacon wrote:

[...]

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

Scott Chacon <schacon@gmail.com> writes:

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.

On Thu, Apr 26, 2012 at 3:16 PM, Junio C Hamano <gitster@pobox.com> 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.

Scott

Scott Chacon wrote:

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