git/Documentation/Makefile, branch v2.45.2

unit tests: add a project plan document

2023-11-09T23:15:25Z

In our current testing environment, we spend a significant amount of effort crafting end-to-end tests for error conditions that could easily be captured by unit tests (or we simply forgo some hard-to-setup and rare error conditions). Describe what we hope to accomplish by implementing unit tests, and explain some open questions and milestones. Discuss desired features for test frameworks/harnesses, and provide a comparison of several different frameworks. Finally, document our rationale for implementing a custom framework. Co-authored-by: Calvin Wan Signed-off-by: Calvin Wan Signed-off-by: Josh Steadmon Signed-off-by: Junio C Hamano

doc: set actual revdate for manpages

2023-04-14T17:37:41Z

manpages expect the date of the last revision, if that is not found DocBook Stylesheets go through a series of hacks to generate one with the format `%d/%d/%Y` which is not ideal. In addition to this format not being standard, different tools generate dates with different formats. There's no need for any confusion if we specify the revision date, so let's do so. Signed-off-by: Felipe Contreras Signed-off-by: Junio C Hamano

Merge branch 'fc/doc-stop-using-manversion' into fc/doc-use-datestamp-in-commit

2023-04-14T17:33:32Z

* fc/doc-stop-using-manversion: doc: simplify man version

doc: simplify man version

2023-04-10T15:39:26Z

The hacks to add version information to the man pages comes from 2007 7ef195ba3e (Documentation: Add version information to man pages, 2007-03-25). In that code we passed three fields to DocBook Stylesheets: `source`, `version`, and `manual`, however, all the stylesheets do is join the strings `source` and `version` [1]. Their own documentation explains that in pracice the source is just a combination of two fields [2]: In practice, there are many pages that simply have a version number in the "source" field. Splitting that information might have seemed more proper in 2007, but it not achieve anything in practice. Asciidoctor had support for this information in their manpage backend since day 1: v1.5.3 (2015), but it didn't include the version. In the docbook5 backend they did in v1.5.7 (2018), but again: no version. There is no need for us to demand that that they add support for the version field when in reality all that is going to happen is that both fields are going to be joined. Let's do that ourselves so we can forget about all our hacks for this and so it works for both asciidoc.py, and docbook5 and manpage backends of asciidoctor. [1] https://github.com/docbook/xslt10-stylesheets/blob/master/xsl/common/refentry.xsl#L545 [2] https://docbook.sourceforge.net/release/xsl/current/doc/common/template.get.refentry.source.html Signed-off-by: Felipe Contreras Signed-off-by: Junio C Hamano

doc: remove manpage-base-url workaround

2023-04-05T21:18:53Z

Commit 50d9bbba92 (Documentation: Avoid use of xmlto --stringparam, 2009-12-04) introduced manpage-base-url.xsl because ancient versions of xmlto did not have --stringparam. However, that was more than ten years ago, no need for that complexity anymore, we can just use --stringparam. Signed-off-by: Felipe Contreras Acked-by: Todd Zullinger Signed-off-by: Junio C Hamano

doc: remove GNU troff workaround

2023-03-21T20:16:46Z

In 2007 the docbook project made the mistake of converting ' to \' for man pages [1]. It's a problem because groff interprets \' as acute accent which is rendered as ' in ASCII, but as ´ in utf-8. This started a cascade of bug reports in git [2], debian [3], Arch Linux [4], docbook itself [5], and probably many others. A solution was to use the correct groff character: \(aq, which is always rendered as ', but the problem is that such character doesn't work in other troff programs. A portable solution required the use of a conditional character that is \(aq in groff, but ' in all others: .ie \n(.g .ds Aq \(aq .el .ds Aq ' The proper solution took time to be implemented in docbook, but in 2010 they did it [6]. So the docbook man page stylesheets were broken from 1.73 to 1.76. Unfortunately by that point many workarounds already existed. In the case of git, GNU_ROFF was introduced, and in the case of Arch Linux a mapping from \' to ' was added to groff's man.local. Other distributions might have done the same, or similar workarounds. Since 2010 there is no need for this workaround, which is fixed elsewhere, not just in docbook, but other layers as well. Let's remove it. [1] https://github.com/docbook/xslt10-stylesheets/commit/ea2a0bac56c56eec1892ac3d9254dca89f7c5746 [2] https://lore.kernel.org/git/20091012102926.GA3937@debian.b2j/ [3] https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=507673#65 [4] https://bugs.archlinux.org/task/9643 [5] https://sourceforge.net/p/docbook/bugs/1022/ [6] https://github.com/docbook/xslt10-stylesheets/commit/fb553434265906ed81edc6d5f533d0b08d200046 Inspired-by: brian m. carlson Signed-off-by: Felipe Contreras Reviewed-by: Jeff King Signed-off-by: Junio C Hamano

Merge branch 'ps/gnumake-4.4-fix'

2022-11-30T01:57:19Z

* ps/gnumake-4.4-fix: Makefile: avoid multiple patterns when recipes generate one file

Makefile: avoid multiple patterns when recipes generate one file

2022-11-28T01:18:55Z

A GNU make pattern rule with multiple targets has always meant that a single invocation of the recipe will build all the targets. However in older versions of GNU make a recipe that did not really build all the targets would be tolerated. Starting with GNU make 4.4 this behavior is deprecated and pattern rules are expected to generate files to match all the patterns. If not all targets are created then GNU make will not consider any target up to date and will re-run the recipe when it is run again. Modify Documentation/Makefile to split the man page-creating pattern rule into a separate pattern rule for each pattern. Reported-by: Alexander Kanavin Signed-off-by: Paul Smith Signed-off-by: Junio C Hamano

Documentation: add lint-fsck-msgids

2022-10-25T22:44:19Z

During the initial development of the fsck-msgids.txt feature, it has become apparent that it is very much error prone to make sure the description in the documentation file are sorted and correctly match what is in the fsck.h header file. Add a quick-and-dirty Perl script and doc-lint target to sanity check that the fsck-msgids.txt is consistent with the error type list in the fsck.h header file. Signed-off-by: Junio C Hamano

Merge branch 'vd/doc-reviewing-guidelines'

2022-09-21T22:27:02Z

Just like we have coding guidelines, we now have guidelines for reviewers. * vd/doc-reviewing-guidelines: Documentation: add ReviewingGuidelines