Although we do not include the HTML renderings of our manual pages in any distribution packages at present, this may change in the future, so we begin by addressing some issues with the HTML conversion, as well as including some missing manual pages in our build (both for HTML and roff output) and making some other revisions.

This PR should be reviewable commit-by-commit or as a single diff, but the former is likely simpler.

Missing Manual Pages

Two of our manual source pages, for git-lfs-dedup(1) and git-lfs-standalone-file(1), are not currently built into finished roff and HTML versions. We therefore add them to the list of targets to be built with ronn(1).

We also reorganize the list of Git LFS porcelain commands in the git-lfs(1) page to ensure it is in alphabetical order.

Build Reference URL Map Dynamically

The docs/man/index.txt file is intended to provide URL mappings for the HTML hyperlinks ronn(1) can generate for references it finds in our manual page Markdown source files; e.g., the text strings git-config(1) and gitignore(5) can be hyperlinked to appropriate URLs wherever they appear.

However, because we run ronn in the top-level directory of the project, the docs/man/index.txt file is never seen or used. Moreover, it contains only a single URL mapping, and that goes to an older manual page hosting site (and uses HTTP not HTTPS).

If we generate the index.txt file dynamically before running ronn then we can extract all the currently listed external manual page references (i.e., those not referring to other Git LFS manual pages) from the SEE ALSO sections of our *.ronn source files, and map those to corresponding URLs under either https://git-scm.com/docs/ for Git manual pages or https://man7.org/linux/man-pages/ for other references.

We can also generate a listing of all our own manual pages and create a map of internal references as well, e.g., for git-lfs-config(5) and git-lfs(1), which ronn will use to create relative hyperlinks between our rendered HTML pages.

And by placing this dynamically generated index.txt file in the top-level directory, we can ensure that ronn will find and utilize it.

Finally, we add our new index.txt to our .gitignore because it's now generated at build time, and we remove the old docs/man/index.txt file.

Removing Parentheses from Headers

In commit 08cb542 of PR #4458 we have previously attempted to address the fact that ronn(1) does not handle parentheses in header text well. Although that change may have resolved issues with the headers themselves, we still generate pages with broken references and links to such headers, as evidenced by the git-lfs-migrate(1) page. In roff format, rendered by man(1) on macOS, the INCLUDE AND EXCLUDE (REFS) header appears in references like:

See [INCLUDE AND EXCLUDE (REFS)]\.

instead of:

See \fIINCLUDE AND EXCLUDE (REFS)\fR\.

which would be correct.

And in HTML format, it appears in references like:

See [INCLUDE AND EXCLUDE (REFS)].

instead of:

See <a href="#INCLUDE-AND-EXCLUDE-REFS-" title="INCLUDE AND EXCLUDE (REFS)" data-bare-link="true">INCLUDE AND EXCLUDE (REFS)</a>.

So we revert that commit, and just rewrite our manual pages' headers and all references to them so that they do not contain any unsupported characters like parentheses or slashes. This also has the advantage of making some of these headers more explicit and descriptive.