Re: Bad Man Page URLs

Jeff King [off-list ref] 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

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

quoted

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

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

quoted

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

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

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

David E. Wheeler wrote:

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

quoted

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?

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

quoted

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

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

David E. Wheeler wrote:

quoted

        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

Hey,

On Thu, Apr 26, 2012 at 2:02 PM, Jeff King [off-list ref] wrote:

quoted

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

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

Scott Chacon wrote:

On Thu, Apr 26, 2012 at 2:02 PM, Jeff King [off-list ref] wrote:

quoted

quoted

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

"David E. Wheeler" [off-list ref] writes:

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

quoted

quoted

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