docs: 'api-index' and 'howto-index' do not work, and technical docs lack an index

[phil-blain]

URL for broken page

https://git-scm.com/docs/git#_further_documentation

Problem

The api-index and howto-index links do not work.

Also, the technical doc pages are generated, but there is no "technical-index" so they're a little difficult to find (and to link to, see https://git.github.io/Hacking-Git/)

Other details

Some of this might have to be done in git.git, but I thought I'd mention it here.

[pedrorijo91]

hi @phil-blain , and thanks for reporting the issue.

These pages are generated from git man pages, so we have no control over it. Have you reported it to the community at https://git-scm.com/community ?

This doesn't seem a caching issue as reported in #1153 right @peff ?

[peff]

This doesn't seem a caching issue as reported in #1153 right @peff ?

Right, it's definitely not caching. We just don't generate those pages (and doing so is non-trivial; we'd have to replicate Git's Makefile and shell magic that builds them).

My opinion is that it's not a big deal, and possibly even preferable. The api documentation is really for developers working on Git itself, and they'll already have their own checkout. Plus we've been slowly moving most of it into header files where it can live next to the code. The more interesting things in technical/ are the format documents. We do build those, and it can occasionally be useful to have a stable URL by which to refer to them, but I don't think we'd want to direct end users to them.

I wouldn't be opposed to having a manually-curated table of links for them if somebody wanted to do that. But I get the impression the complaint here is just that git.txt links to them, and those links are broken. I'd be just as happy to cut the references out of what we build on the site.

The howto articles in theory would be helpful to end-users, but my general opinion is that they're not well maintained. They're mostly interesting or weird tricks from mailing list posts that somehow got promoted to documentation status. I'd suspect many of them are out of date (even if they still work, there may be better ways to do similar things these days). Some probably could be (or have been) folded into the documentation for relevant commands. Some of them are discussions of workflows that don't fit with a single command, but I think the Pro Git book content covers a lot of that type of material. So IMHO there's not a huge value in trying to build or index them on the site.

[pedrorijo91]

thanks for the insights @peff :)

I'd be just as happy to cut the references out of what we build on the site.

How easy would that be? if I understood correctly, the page is generated from git man pages, so we would have to remove that part somehow?

[jnavila]

I see two paths:

• We try to cut the links in the upstream sources. It could be done with conditionals in ascidoc sources.
  • Advantages: if the pages are used in other parts, they benefit from this clear cut. TBH, I'm interested in this for the translations but I guess most manpages packagers would agree.
  • Drawbacks: that's another burden on doc writers, we have to sell it to the git dev team.
• We do it in git-scm.com import script. This is is our own cooking and we are in charge of maintaining it, following evolutions and so on.

I'm in favor of the first solution, the catch being to define precisely the criteria for inclusion or rejection.

[peff]

Yeah, I was imagining that we would hack up text as we imported it, the way we do with a few other spots. But I think adding conditionals into the sources would be a pretty easy sell upstream. We don't build manpages of the howto docs, for instance, so the link in man git is potentially broken even for local builds (certainly my local build is, since I don't build the HTML, but even the debian git package seems to point to a non-existent /usr/share/doc/git/html, unless you also install git-docs).

[phil-blain]

Regarding your latest comment, I fell upon this stackoverflow question where a user looks for the User Manual that is referred to in git.1 today, and from what I understand all distros/package manager that use the git-{manpages,htmldocs} tarballs to install the documentation end up with unusable "links" in the manpages, because Junio uses "git-htmldocs" as MAN_BASE_URL for generating the doc tarballs:

$ git grep git-htmldocs
man1/git-bisect.1:710:3:\%git-htmldocs/git-bisect-lk2009.html
man1/git-branch.1:498:3:\%git-htmldocs/user-manual.html#what-is-a-branch
man1/git-config.1:8238:3:\%git-htmldocs/technical/protocol-v2.html
man1/git-multi-pack-index.1:166:3:\%git-htmldocs/technical/multi-pack-index.html
man1/git-multi-pack-index.1:171:3:\%git-htmldocs/technical/pack-format.html
man1/git-rebase.1:2102:3:\%git-htmldocs/howto/revert-a-faulty-merge.html
man1/git-revert.1:184:3:\%git-htmldocs/howto/revert-a-faulty-merge.html
man1/git.1:1959:3:\%git-htmldocs/user-manual.html
man1/git.1:1964:3:\%git-htmldocs/technical/api-trace2.html
man1/git.1:1969:3:\%git-htmldocs/user-manual.html#git-concepts
man1/git.1:1974:3:\%git-htmldocs/howto-index.html
man1/git.1:1979:3:\%git-htmldocs/technical/api-index.html
man5/gitrepository-layout.5:523:3:\%git-htmldocs/user-manual.html
man7/gitcore-tutorial.7:2105:3:\%git-htmldocs/user-manual.html
man7/gitcvs-migration.7:221:3:\%git-htmldocs/howto/update-hook-example.html
man7/gitcvs-migration.7:226:3:\%git-htmldocs/user-manual.html
man7/gitdiffcore.7:339:3:\%git-htmldocs/user-manual.html
man7/giteveryday.7:891:3:\%git-htmldocs/howto/update-hook-example.html
man7/gitglossary.7:1091:3:\%git-htmldocs/user-manual.html
man7/gittutorial-2.7:553:3:\%git-htmldocs/user-manual.html
man7/gittutorial-2.7:558:3:\%git-htmldocs/howto-index.html
man7/gittutorial.7:992:3:\%git-htmldocs/user-manual.html

I think it would be great to fix that.

I then dug out this old discussion on the list where @peff you suggested linking to the website instead. I think that would be a good idea, but it would mean that the structure of the htmldocs would need to be the same as the vanilla Asciidoc build.

The reasons I would prefer linking to the website instead of https://mirrors.edge.kernel.org/pub/software/scm/git/docs/ or https://git.github.io/htmldocs/, the two other "official" places I know that host the formatted html documentation, is that:

1. It looks better in Asciidoctor then the Asciidoc version at git.github.io/htmldocs IMO (and the kernel site does not even have CSS)
2. The docs for all versions are hosted on the website, so tarballs could be generated with something like MAN_BASE_URL=https://git-scm.com/docs/$VERSION/, provided that we make that work on the website (for now only links like https://git-scm.com/docs/git*/$VERSION work).

[dlwlb]

I'm novice. Is this an issue with git-scm, git.git, or both? I asked the https://git-scm.com/community mailing list. The response was "howtos-index does get generated by the Git project but doesn't appear to be published on the git-scm site for some reason. git-scm is maintained as a separate project, so the best thing to do is to report the problem there..."

I question obsoleting references to HOW-TO documents, though some may be archaic. Another reference to it is from https://git-scm.com/docs/gittutorial-2. One howto was updated just 7 months ago. See them here: https://github.com/git/git/tree/master/Documentation/howto

[peff]

My opinion is still that these howtos are not generally that useful to show to most users (most of the updates are just fixes for bitrot; I see Junio did update "how to maintain git" which IMHO is easily the most interesting of the bunch, but only to people working on the Git project; it could probably exist alongside SubmittingPatches, etc).

All that said, if somebody really wants to do the work to start building these, I'm not opposed to it. I'd prefer not to link from the main /doc page, but we'd presumably need an appropriately-named index file so that git.txt could link to it (and of course they'd be available for direct linking, too).

[dscho]

Let's just close this, there has not been enough activity to merit keeping this ticket open.