* [PATCH v5 1/4] doc: remove GNU troff workaround
2021-06-18 21:52 [PATCH v5 0/4] doc: cleanup old cruft Felipe Contreras
@ 2021-06-18 21:52 ` Felipe Contreras
2021-06-18 21:52 ` [PATCH v5 2/4] doc: use --stringparam in xmlto Felipe Contreras
` (2 subsequent siblings)
3 siblings, 0 replies; 5+ messages in thread
From: Felipe Contreras @ 2021-06-18 21:52 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Martin Ågren, brian m . carlson,
Bagas Sanjaya, Jeff King, Felipe Contreras
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 mappig from \' to ' was added to groff's man.local. Other
distributions might have done the same, or similar workarounds.
Since 2010 there is not need for this workaround, which is fixed
elsewhere not just in docbook, but other layers as well.
Let's remove it.
Also, it's GNU troff, not GNU roff.
[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 <sandals@crustytoothpaste.net>
Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
Documentation/Makefile | 8 --------
Documentation/manpage-quote-apos.xsl | 16 ----------------
Makefile | 4 ----
3 files changed, 28 deletions(-)
delete mode 100644 Documentation/manpage-quote-apos.xsl
diff --git a/Documentation/Makefile b/Documentation/Makefile
index f5605b7767..bf1f66b3eb 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -178,14 +178,6 @@ MAN_BASE_URL = file://$(htmldir)/
endif
XMLTO_EXTRA += -m manpage-base-url.xsl
-# If your target system uses GNU groff, it may try to render
-# apostrophes as a "pretty" apostrophe using unicode. This breaks
-# cut&paste, so you should set GNU_ROFF to force them to be ASCII
-# apostrophes. Unfortunately does not work with non-GNU roff.
-ifdef GNU_ROFF
-XMLTO_EXTRA += -m manpage-quote-apos.xsl
-endif
-
ifdef USE_ASCIIDOCTOR
ASCIIDOC = asciidoctor
ASCIIDOC_CONF =
diff --git a/Documentation/manpage-quote-apos.xsl b/Documentation/manpage-quote-apos.xsl
deleted file mode 100644
index aeb8839f33..0000000000
--- a/Documentation/manpage-quote-apos.xsl
+++ /dev/null
@@ -1,16 +0,0 @@
-<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 c3565fc0f8..7588c43f05 100644
--- a/Makefile
+++ b/Makefile
@@ -278,10 +278,6 @@ all::
# Define NO_ST_BLOCKS_IN_STRUCT_STAT if your platform does not have st_blocks
# field that counts the on-disk footprint in 512-byte blocks.
#
-# Define GNU_ROFF if your target system uses GNU groff. This forces
-# apostrophes to be ASCII so that cut&pasting examples to the shell
-# will work.
-#
# Define USE_ASCIIDOCTOR to use Asciidoctor instead of AsciiDoc to build the
# documentation.
#
--
2.32.0
^ permalink raw reply related [flat|nested] 5+ messages in thread* [PATCH v5 2/4] doc: use --stringparam in xmlto
2021-06-18 21:52 [PATCH v5 0/4] doc: cleanup old cruft Felipe Contreras
2021-06-18 21:52 ` [PATCH v5 1/4] doc: remove GNU troff workaround Felipe Contreras
@ 2021-06-18 21:52 ` Felipe Contreras
2021-06-18 21:52 ` [PATCH v5 3/4] doc: simplify version passing Felipe Contreras
2021-06-18 21:52 ` [PATCH v5 4/4] doc: asciidoc: remove unnecessary attribute Felipe Contreras
3 siblings, 0 replies; 5+ messages in thread
From: Felipe Contreras @ 2021-06-18 21:52 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Martin Ågren, brian m . carlson,
Bagas Sanjaya, Jeff King, Felipe Contreras
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.
Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
Documentation/.gitignore | 1 -
Documentation/Makefile | 8 ++------
Documentation/manpage-base-url.xsl.in | 10 ----------
3 files changed, 2 insertions(+), 17 deletions(-)
delete mode 100644 Documentation/manpage-base-url.xsl.in
diff --git a/Documentation/.gitignore b/Documentation/.gitignore
index 9022d48355..e9f8d693b1 100644
--- a/Documentation/.gitignore
+++ b/Documentation/.gitignore
@@ -10,7 +10,6 @@ howto-index.txt
doc.dep
cmds-*.txt
mergetools-*.txt
-manpage-base-url.xsl
SubmittingPatches.txt
tmp-doc-diff/
GIT-ASCIIDOCFLAGS
diff --git a/Documentation/Makefile b/Documentation/Makefile
index bf1f66b3eb..84643a34e9 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -176,7 +176,7 @@ endif
ifndef MAN_BASE_URL
MAN_BASE_URL = file://$(htmldir)/
endif
-XMLTO_EXTRA += -m manpage-base-url.xsl
+XMLTO_EXTRA += --stringparam man.base.url.for.relative.links='$(MAN_BASE_URL)'
ifdef USE_ASCIIDOCTOR
ASCIIDOC = asciidoctor
@@ -342,7 +342,6 @@ clean:
$(RM) technical/*.html technical/api-index.txt
$(RM) SubmittingPatches.txt
$(RM) $(cmds_txt) $(mergetools_txt) *.made
- $(RM) manpage-base-url.xsl
$(RM) GIT-ASCIIDOCFLAGS
$(MAN_HTML): %.html : %.txt $(ASCIIDOC_DEPS)
@@ -351,10 +350,7 @@ $(MAN_HTML): %.html : %.txt $(ASCIIDOC_DEPS)
$(OBSOLETE_HTML): %.html : %.txto $(ASCIIDOC_DEPS)
$(QUIET_ASCIIDOC)$(TXT_TO_HTML) -o $@ $<
-manpage-base-url.xsl: manpage-base-url.xsl.in
- $(QUIET_GEN)sed "s|@@MAN_BASE_URL@@|$(MAN_BASE_URL)|" $< > $@
-
-%.1 %.5 %.7 : %.xml manpage-base-url.xsl $(wildcard manpage*.xsl)
+%.1 %.5 %.7 : %.xml $(wildcard manpage*.xsl)
$(QUIET_XMLTO)$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<
%.xml : %.txt $(ASCIIDOC_DEPS)
diff --git a/Documentation/manpage-base-url.xsl.in b/Documentation/manpage-base-url.xsl.in
deleted file mode 100644
index e800904df3..0000000000
--- a/Documentation/manpage-base-url.xsl.in
+++ /dev/null
@@ -1,10 +0,0 @@
-<!-- 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>
--
2.32.0
^ permalink raw reply related [flat|nested] 5+ messages in thread
* [PATCH v5 3/4] doc: simplify version passing
2021-06-18 21:52 [PATCH v5 0/4] doc: cleanup old cruft Felipe Contreras
2021-06-18 21:52 ` [PATCH v5 1/4] doc: remove GNU troff workaround Felipe Contreras
2021-06-18 21:52 ` [PATCH v5 2/4] doc: use --stringparam in xmlto Felipe Contreras
@ 2021-06-18 21:52 ` Felipe Contreras
2021-06-18 21:52 ` [PATCH v5 4/4] doc: asciidoc: remove unnecessary attribute Felipe Contreras
3 siblings, 0 replies; 5+ messages in thread
From: Felipe Contreras @ 2021-06-18 21:52 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Martin Ågren, brian m . carlson,
Bagas Sanjaya, Jeff King, Felipe Contreras
The code to pass the version of the man page comes from 2007:
7ef195ba3e (Documentation: Add version information to man pages,
2007-03-25). However, both asciidoc and asciidoctor already do this by
default.
Asciidoctor doesn't read manversion, but there's no need since both
tools just join mansource and manversion.
Let's do that ourselves and get rid of a bunch of code.
Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
Documentation/Makefile | 3 +--
Documentation/asciidoc.conf | 19 -------------------
Documentation/asciidoctor-extensions.rb | 17 -----------------
3 files changed, 1 insertion(+), 38 deletions(-)
diff --git a/Documentation/Makefile b/Documentation/Makefile
index 84643a34e9..47053c78f8 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -137,8 +137,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)
diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf
index 3e4c13971b..60f76f43ed 100644
--- a/Documentation/asciidoc.conf
+++ b/Documentation/asciidoc.conf
@@ -51,25 +51,6 @@ ifdef::doctype-manpage[]
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=
diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb
index d906a00803..70a0956663 100644
--- a/Documentation/asciidoctor-extensions.rb
+++ b/Documentation/asciidoctor-extensions.rb
@@ -23,26 +23,9 @@ module Git
end
end
end
-
- class DocumentPostProcessor < Asciidoctor::Extensions::Postprocessor
- def process document, output
- if document.basebackend? 'docbook'
- mansource = document.attributes['mansource']
- manversion = document.attributes['manversion']
- manmanual = document.attributes['manmanual']
- new_tags = "" \
- "<refmiscinfo class=\"source\">#{mansource}</refmiscinfo>\n" \
- "<refmiscinfo class=\"version\">#{manversion}</refmiscinfo>\n" \
- "<refmiscinfo class=\"manual\">#{manmanual}</refmiscinfo>\n"
- output = output.sub(/<\/refmeta>/, new_tags + "</refmeta>")
- end
- output
- end
- end
end
end
Asciidoctor::Extensions.register do
inline_macro Git::Documentation::LinkGitProcessor, :linkgit
- postprocessor Git::Documentation::DocumentPostProcessor
end
--
2.32.0
^ permalink raw reply related [flat|nested] 5+ messages in thread* [PATCH v5 4/4] doc: asciidoc: remove unnecessary attribute
2021-06-18 21:52 [PATCH v5 0/4] doc: cleanup old cruft Felipe Contreras
` (2 preceding siblings ...)
2021-06-18 21:52 ` [PATCH v5 3/4] doc: simplify version passing Felipe Contreras
@ 2021-06-18 21:52 ` Felipe Contreras
3 siblings, 0 replies; 5+ messages in thread
From: Felipe Contreras @ 2021-06-18 21:52 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Martin Ågren, brian m . carlson,
Bagas Sanjaya, Jeff King, Felipe Contreras
It's part of asciidoc global configuration since 2012.
Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
Documentation/asciidoc.conf | 1 -
1 file changed, 1 deletion(-)
diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf
index 60f76f43ed..f7908f9dea 100644
--- a/Documentation/asciidoc.conf
+++ b/Documentation/asciidoc.conf
@@ -12,7 +12,6 @@
[attributes]
asterisk=*
-plus=+
caret=^
startsb=[
endsb=]
--
2.32.0
^ permalink raw reply related [flat|nested] 5+ messages in thread