git/list[1] front-page[2] threads[3] people[4] search[5] about
 

[PATCH] doc: simplify man version

From
Felipe Contreras <felipe.contreras@gmail.com>
Date
Apr 8, 2023, 00:18 UTC
Message-ID
<20230408001829.11031-1-felipe.contreras@gmail.com>

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 <felipe.contreras@gmail.com>
---
 Documentation/Makefile | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)
diff --git a/Documentation/Makefile b/Documentation/Makefile
index a6ba5bd460..4721b000c1 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -150,8 +150,7 @@ ASCIIDOC_HTML = xhtml11
 ASCIIDOC_DOCBOOK = docbook
 ASCIIDOC_CONF = -f asciidoc.conf
 ASCIIDOC_COMMON = $(ASCIIDOC) $(ASCIIDOC_EXTRA) $(ASCIIDOC_CONF) \
-		-amanversion=$(GIT_VERSION) \
-		-amanmanual='Git Manual' -amansource='Git'
+		-amanmanual='Git Manual' -amansource='Git $(GIT_VERSION)'
 ASCIIDOC_DEPS = asciidoc.conf GIT-ASCIIDOCFLAGS
 TXT_TO_HTML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_HTML)
 TXT_TO_XML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_DOCBOOK)
-- 
2.40.0+fc1
Next: Junio C Hamano
Message 1 of 8 in “doc: simplify man version”
  1. doc: simplify man versionFelipe Contreras, Apr 8, 2023
  2. Junio C HamanoApr 8, 2023
  3. Jeff KingApr 9, 2023
  4. Felipe ContrerasApr 10, 2023
  5. Junio C HamanoApr 10, 2023
  6. Felipe ContrerasApr 10, 2023
  7. Junio C HamanoApr 11, 2023
  8. Felipe ContrerasApr 16, 2023

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.