From 7c66e1d4a8076f5b0cc29e5c05637ba1363a6bd7 Mon Sep 17 00:00:00 2001
Message-Id: <7c66e1d4a8076f5b0cc29e5c05637ba1363a6bd7.1685797909.git.dev@jpoiret.xyz>
From: Josselin Poiret <dev@jpoiret.xyz>
Date: Sat, 3 Jun 2023 13:07:07 +0200
Subject: [PATCH] Add documentation generation.

From: Josselin Poiret <dev@jpoiret.xyz>

This uses the manpage XSL and asciidoc config files from git 2.40.1.
---
 .gitignore                             |  1 +
 Documentation/Makefile                 | 38 +++++++++++++
 Documentation/asciidoc.conf            | 78 ++++++++++++++++++++++++++
 Documentation/manpage-base-url.xsl.in  | 10 ++++
 Documentation/manpage-bold-literal.xsl | 16 ++++++
 Documentation/manpage-normal.xsl       | 26 +++++++++
 Documentation/manpage-quote-apos.xsl   | 16 ++++++
 Makefile                               | 17 +-----
 8 files changed, 188 insertions(+), 14 deletions(-)
 create mode 100644 Documentation/Makefile
 create mode 100644 Documentation/asciidoc.conf
 create mode 100644 Documentation/manpage-base-url.xsl.in
 create mode 100644 Documentation/manpage-bold-literal.xsl
 create mode 100644 Documentation/manpage-normal.xsl
 create mode 100644 Documentation/manpage-quote-apos.xsl

diff --git a/.gitignore b/.gitignore
index cd5ded4..e167ef7 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,5 +1,6 @@
 /Documentation/html/
 /Documentation/man1/
+/Documentation/manpage-base-url.xsl
 /t/test-results
 /t/trash directory*
 /__pycache__/
diff --git a/Documentation/Makefile b/Documentation/Makefile
new file mode 100644
index 0000000..d4cd939
--- /dev/null
+++ b/Documentation/Makefile
@@ -0,0 +1,38 @@
+MAN_BASE_URL := /usr/share/doc/git-doc/
+VERSION := $(git log --pretty="%H" -n 1)
+
+ASCIIDOC := asciidoc
+ASCIIDOC_EXTRA :=
+ASCIIDOC_HTML := xhtml11
+ASCIIDOC_DOCBOOK := docbook
+ASCIIDOC_CONF := -f asciidoc.conf
+ASCIIDOC_COMMON := $(ASCIIDOC) $(ASCIIDOC_EXTRA) $(ASCIIDOC_CONF) \
+		-amanversion='$(VERSION)' \
+		-amanmanual='git-filter-repo Manual' -amansource='git-filter-repo'
+ASCIIDOC_DEPS := asciidoc.conf
+TXT_TO_HTML := $(ASCIIDOC_COMMON) -b $(ASCIIDOC_HTML)
+TXT_TO_XML := $(ASCIIDOC_COMMON) -b $(ASCIIDOC_DOCBOOK)
+MANPAGE_XSL := manpage-normal.xsl
+XMLTO := xmlto
+XMLTO_EXTRA := -m manpage-bold-literal.xsl -m manpage-base-url.xsl -m manpage-quote-apos.xsl
+XMLTO_DEPS := manpage-bold-literal.xsl manpage-base-url.xsl manpage-quote-apos.xsl
+
+manpage-deps := $(XMLTO_DEPS)
+manpage-cmd := $(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man
+
+manpage-base-url.xsl: manpage-base-url.xsl.in
+	sed "s|@@MAN_BASE_URL@@|$(MAN_BASE_URL)|" $< > $@
+
+%.xml : %.txt $(ASCIIDOC_DEPS)
+	$(QUIET_ASCIIDOC)$(TXT_TO_XML) -d manpage -o $@ $<
+
+man1/%.1 : %.xml $(manpage-deps)
+	mkdir -p man1
+	$(manpage-cmd) -o man1 $<
+
+html/%.html : %.txt $(ASCIIDOC_DEPS)
+	mkdir -p html
+	$(TXT_TO_HTML) -d manpage -o $@ $<
+
+man: man1/git-filter-repo.1
+html: html/git-filter-repo.html
diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf
new file mode 100644
index 0000000..3e4c139
--- /dev/null
+++ b/Documentation/asciidoc.conf
@@ -0,0 +1,78 @@
+## linkgit: macro
+#
+# Usage: linkgit:command[manpage-section]
+#
+# Note, {0} is the manpage section, while {target} is the command.
+#
+# Show Git link as: <command>(<section>); if section is defined, else just show
+# the command.
+
+[macros]
+(?su)[\\]?(?P<name>linkgit):(?P<target>\S*?)\[(?P<attrlist>.*?)\]=
+
+[attributes]
+asterisk=&#42;
+plus=&#43;
+caret=&#94;
+startsb=&#91;
+endsb=&#93;
+backslash=&#92;
+tilde=&#126;
+apostrophe=&#39;
+backtick=&#96;
+litdd=&#45;&#45;
+
+ifdef::backend-docbook[]
+[linkgit-inlinemacro]
+{0%{target}}
+{0#<citerefentry>}
+{0#<refentrytitle>{target}</refentrytitle><manvolnum>{0}</manvolnum>}
+{0#</citerefentry>}
+endif::backend-docbook[]
+
+ifdef::backend-docbook[]
+ifdef::doctype-manpage[]
+# The following two small workarounds insert a simple paragraph after screen
+[listingblock]
+<example><title>{title}</title>
+<literallayout class="monospaced">
+|
+</literallayout><simpara></simpara>
+{title#}</example>
+
+[verseblock]
+<formalpara{id? id="{id}"}><title>{title}</title><para>
+{title%}<literallayout{id? id="{id}"}>
+{title#}<literallayout>
+|
+</literallayout>
+{title#}</para></formalpara>
+{title%}<simpara></simpara>
+endif::doctype-manpage[]
+endif::backend-docbook[]
+
+ifdef::doctype-manpage[]
+ifdef::backend-docbook[]
+[header]
+template::[header-declarations]
+<refentry>
+<refmeta>
+<refentrytitle>{mantitle}</refentrytitle>
+<manvolnum>{manvolnum}</manvolnum>
+<refmiscinfo class="source">{mansource}</refmiscinfo>
+<refmiscinfo class="version">{manversion}</refmiscinfo>
+<refmiscinfo class="manual">{manmanual}</refmiscinfo>
+</refmeta>
+<refnamediv>
+  <refname>{manname}</refname>
+  <refpurpose>{manpurpose}</refpurpose>
+</refnamediv>
+endif::backend-docbook[]
+endif::doctype-manpage[]
+
+ifdef::backend-xhtml11[]
+[attributes]
+git-relative-html-prefix=
+[linkgit-inlinemacro]
+<a href="{git-relative-html-prefix}{target}.html">{target}{0?({0})}</a>
+endif::backend-xhtml11[]
diff --git a/Documentation/manpage-base-url.xsl.in b/Documentation/manpage-base-url.xsl.in
new file mode 100644
index 0000000..e800904
--- /dev/null
+++ b/Documentation/manpage-base-url.xsl.in
@@ -0,0 +1,10 @@
+<!-- manpage-base-url.xsl:
+     special settings for manpages rendered from newer docbook -->
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+		version="1.0">
+
+<!-- set a base URL for relative links -->
+<xsl:param name="man.base.url.for.relative.links"
+	>@@MAN_BASE_URL@@</xsl:param>
+
+</xsl:stylesheet>
diff --git a/Documentation/manpage-bold-literal.xsl b/Documentation/manpage-bold-literal.xsl
new file mode 100644
index 0000000..e13db85
--- /dev/null
+++ b/Documentation/manpage-bold-literal.xsl
@@ -0,0 +1,16 @@
+<!-- manpage-bold-literal.xsl:
+     special formatting for manpages rendered from asciidoc+docbook -->
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+		xmlns:d="http://docbook.org/ns/docbook"
+		version="1.0">
+
+<!-- render literal text as bold (instead of plain or monospace);
+     this makes literal text easier to distinguish in manpages
+     viewed on a tty -->
+<xsl:template match="literal|d:literal">
+	<xsl:text>\fB</xsl:text>
+	<xsl:apply-templates/>
+	<xsl:text>\fR</xsl:text>
+</xsl:template>
+
+</xsl:stylesheet>
diff --git a/Documentation/manpage-normal.xsl b/Documentation/manpage-normal.xsl
new file mode 100644
index 0000000..a9c7ec6
--- /dev/null
+++ b/Documentation/manpage-normal.xsl
@@ -0,0 +1,26 @@
+<!-- manpage-normal.xsl:
+     special settings for manpages rendered from asciidoc+docbook -->
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+		version="1.0">
+
+
+<!-- these params silence some output from xmlto -->
+<xsl:param name="man.output.quietly" select="1"/>
+<xsl:param name="refentry.meta.get.quietly" select="1"/>
+
+<!-- convert asciidoc callouts to man page format -->
+<xsl:template match="co">
+	<xsl:value-of select="concat('\fB(',substring-after(@id,'-'),')\fR')"/>
+</xsl:template>
+<xsl:template match="calloutlist">
+	<xsl:text>.sp&#10;</xsl:text>
+	<xsl:apply-templates/>
+	<xsl:text>&#10;</xsl:text>
+</xsl:template>
+<xsl:template match="callout">
+	<xsl:value-of select="concat('\fB',substring-after(@arearefs,'-'),'. \fR')"/>
+	<xsl:apply-templates/>
+	<xsl:text>.br&#10;</xsl:text>
+</xsl:template>
+
+</xsl:stylesheet>
diff --git a/Documentation/manpage-quote-apos.xsl b/Documentation/manpage-quote-apos.xsl
new file mode 100644
index 0000000..aeb8839
--- /dev/null
+++ b/Documentation/manpage-quote-apos.xsl
@@ -0,0 +1,16 @@
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+		version="1.0">
+
+<!-- work around newer groff/man setups using a prettier apostrophe
+     that unfortunately does not quote anything when cut&pasting
+     examples to the shell -->
+<xsl:template name="escape.apostrophe">
+  <xsl:param name="content"/>
+  <xsl:call-template name="string.subst">
+    <xsl:with-param name="string" select="$content"/>
+    <xsl:with-param name="target">'</xsl:with-param>
+    <xsl:with-param name="replacement">\(aq</xsl:with-param>
+  </xsl:call-template>
+</xsl:template>
+
+</xsl:stylesheet>
diff --git a/Makefile b/Makefile
index a443450..d965ae5 100644
--- a/Makefile
+++ b/Makefile
@@ -20,21 +20,10 @@ test:
 fixup_locale:
 	sed -ie s%@@LOCALEDIR@@%$(localedir)% git-filter-repo
 
-# People installing from tarball will already have man1/git-filter-repo.1 and
-# html/git-filter-repo.html.  But let's support people installing from a git
-# clone too; for them, just cheat and snag a copy of the built docs that I
-# record in a different branch.
-snag_docs: Documentation/man1/git-filter-repo.1 Documentation/html/git-filter-repo.html
+doc:
+	$(MAKE) -C Documentation man html
 
-Documentation/man1/git-filter-repo.1:
-	mkdir -p Documentation/man1
-	git show origin/docs:man1/git-filter-repo.1 >Documentation/man1/git-filter-repo.1
-
-Documentation/html/git-filter-repo.html:
-	mkdir -p Documentation/html
-	git show origin/docs:html/git-filter-repo.html >Documentation/html/git-filter-repo.html
-
-install: snag_docs #fixup_locale
+install: doc #fixup_locale
 	install -Dm0755 git-filter-repo "$(DESTDIR)/$(bindir)/git-filter-repo"
 	install -dm0755 "$(DESTDIR)/$(pythondir)"
 	ln -sf "$(bindir)/git-filter-repo" "$(DESTDIR)/$(pythondir)/git_filter_repo.py"
-- 
2.40.1