`man 1 git`: Invalid link to online documentation

`man 1 git`: Invalid link to online documentation

[Daniel Campbell]

[-- Attachment #1.1: Type: text/plain, Size: 1220 bytes --]

In `man 1 git`, the Description section outlines an address to
pre-generated documentation [0]. That link returns a 404 error. Playing
around, I found the repository at [1] and found that it hasn't been
updated since August 2015. Given that 2.8.3 is more recent than that, it
seems like this is something that should be updated (if the
pre-generated docs still exist somewhere) or removed altogether.

Also worth considering is Google Code was shut down earlier this year.
While archives exist, it can't be relied upon for future use. The
closest approximation I could find that was up to date is [2], though
[3] is a repository that's even fresher than 2.8.3.

Since I'm not familiar with Git development I figured it was wiser to
let you know instead of making a decision on what to do and patching.

I know this is minor but I figured it was overlooked. Thanks for reading.

0: http://git-htmldocs.googlecode.com/git/git.html
1: https://code.google.com/archive/p/git-htmldocs/
2: https://git-scm.com/docs
3: https://github.com/gitster/git-htmldocs
-- 
Daniel Campbell - Gentoo Developer
OpenPGP Key: 0x1EA055D6 @ hkp://keys.gnupg.net
fpr: AE03 9064 AE00 053C 270C  1DE4 6F7A 9091 1EA0 55D6


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 819 bytes --]

Re: `man 1 git`: Invalid link to online documentation

[Jeff King]

On Sun, Jun 05, 2016 at 08:59:00PM -0700, Daniel Campbell wrote:

> In `man 1 git`, the Description section outlines an address to
> pre-generated documentation [0]. That link returns a 404 error. Playing
> around, I found the repository at [1] and found that it hasn't been
> updated since August 2015. Given that 2.8.3 is more recent than that, it
> seems like this is something that should be updated (if the
> pre-generated docs still exist somewhere) or removed altogether.
> 
> Also worth considering is Google Code was shut down earlier this year.
> While archives exist, it can't be relied upon for future use. The
> closest approximation I could find that was up to date is [2], though
> [3] is a repository that's even fresher than 2.8.3.

Yeah, I think Google Code is out. The git-scm.com page automatically
pulls in released versions of the pages, but not the tip of master
(which is what the git-htmldocs repository has).

That repository is hosted at kernel.org and at GitHub, so either of:

  https://git.kernel.org/cgit/git/git-htmldocs.git/plain/git.html

  https://raw.githubusercontent.com/gitster/git-htmldocs/master/git.html

but in both cases the content-type is such that it doesn't render in a
browser (and at least in the GitHub case, that is intentional; we don't
want people using their repos directly as a CDN. They should build a
Pages site and push to it).

So I think the options are basically:

  1. Point to git-scm.com/docs as "new enough" as it covers released
     versions (and lets you walk back to earlier versions, too). People
     who want bleeding edge can clone htmldocs themselves.

  2. Make git-htmldocs a real site on GitHub. I think this should be as
     simple as pushing to the `gh-pages` branch of the repository, which
     would make it available as https://gitster.github.io/git-htmldocs.
     You can do a bunch of Jekyll magic, but you don't have to; it should
     serve arbitrary html files (though I think we'd maybe want to add
     an "index.html"; we may also want to host it under a git/htmldocs
     project just to make the repo more official looking).

  3. Publish to some other Pages-like service. I don't think kernel.org
     has one, but it's not like there's a lack of sites you can push
     static HTML files to. I mentioned GitHub in (2) mostly because
     Junio already pushes there.

-Peff

Re: `man 1 git`: Invalid link to online documentation

[Jeff King]

On Mon, Jun 06, 2016 at 07:19:36PM -0400, Jeff King wrote:

>   2. Make git-htmldocs a real site on GitHub. I think this should be as
>      simple as pushing to the `gh-pages` branch of the repository, which
>      would make it available as https://gitster.github.io/git-htmldocs.
>      You can do a bunch of Jekyll magic, but you don't have to; it should
>      serve arbitrary html files (though I think we'd maybe want to add
>      an "index.html"; we may also want to host it under a git/htmldocs
>      project just to make the repo more official looking).

Just to make sure I wasn't spewing nonsense, I tried pushing the tip of
gitster/git-htmldocs to the "gh-pages" branch of git/htmldocs, and
indeed:

  https://git.github.io/htmldocs/git.html

now works. If we like that solution, Junio, you should already have
access to just push there (instead of gitster/git-htmldocs, or in
addition to if you prefer).

If not, I'll delete the repository (I don't plan on doing further
pushes, so leaving it will just confuse people).

I see that we _do_ have an index.html symlink in the built tree, but it
does not seem to actually work via GitHub Pages.

-Peff

Re: `man 1 git`: Invalid link to online documentation

[Michael J Gruber]

Jeff King venit, vidit, dixit 07.06.2016 01:25:
> On Mon, Jun 06, 2016 at 07:19:36PM -0400, Jeff King wrote:
> 
>>   2. Make git-htmldocs a real site on GitHub. I think this should be as
>>      simple as pushing to the `gh-pages` branch of the repository, which
>>      would make it available as https://gitster.github.io/git-htmldocs.
>>      You can do a bunch of Jekyll magic, but you don't have to; it should
>>      serve arbitrary html files (though I think we'd maybe want to add
>>      an "index.html"; we may also want to host it under a git/htmldocs
>>      project just to make the repo more official looking).
> 
> Just to make sure I wasn't spewing nonsense, I tried pushing the tip of
> gitster/git-htmldocs to the "gh-pages" branch of git/htmldocs, and
> indeed:
> 
>   https://git.github.io/htmldocs/git.html
> 
> now works. If we like that solution, Junio, you should already have
> access to just push there (instead of gitster/git-htmldocs, or in
> addition to if you prefer).
> 
> If not, I'll delete the repository (I don't plan on doing further
> pushes, so leaving it will just confuse people).
> 
> I see that we _do_ have an index.html symlink in the built tree, but it
> does not seem to actually work via GitHub Pages.
> 
> -Peff
> 

I like that a lot. It makes good use of the existing infrastructure at
github, and the rendering uses screen real estate much better than the
version on git-scm.com.

If Junio integrates it into his usual workflow then we don't have the
update issues that we have over there. Rendered documentation in-sync
with the code, hooray :)

Michael