This patch series gets rid of old unnecessary workarounds and convoluted solutions. Additionally it cleanups the asciidoctor-specific code so it ends up much more simpler. This goes on top of my other cleanup patches [1]. [1] 20210514115631.503276-1-felipe.contreras@gmail.com Felipe Contreras (12): doc: remove GNU troff workaround doc: use --stringparam in xmlto doc: simplify version passing doc: asciidoc: remove unnecessary attribute doc: asciidoctor: remove unnecessary require doc: asciidoctor: remove cruft doc: asciidoctor: reorganize extensions doc: asciidoctor: use html-prefix only for html doc: asciidoctor: refactor macro registration doc: asciidoctor: improve string handling doc: asciidoctor: split the format from the code doc: asciidoctor: specify name of our group Documentation/.gitignore | 1 - Documentation/Makefile | 19 ++------- Documentation/asciidoc.conf | 20 --------- Documentation/asciidoctor-extensions.rb | 56 ++++++++----------------- Documentation/manpage-base-url.xsl.in | 10 ----- Documentation/manpage-quote-apos.xsl | 16 ------- Makefile | 4 -- 7 files changed, 21 insertions(+), 105 deletions(-) delete mode 100644 Documentation/manpage-base-url.xsl.in delete mode 100644 Documentation/manpage-quote-apos.xsl -- 2.31.1
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 diff --git a/Makefile b/Makefile index 93664d6714..2a94cef62f 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.31.1
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 -- 2.31.1
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.31.1
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.31.1
This file is loaded by asciidoctor, the module is already loaded. In addition to being less redundant this fixes a problem while trying use a development version of asciidoctor when the gem is available: $GEM_HOME/gems/asciidoctor-2.0.15/lib/asciidoctor.rb:51: warning: already initialized constant Asciidoctor::RUBY_ENGINE $HOME/asciidoctor/lib/asciidoctor.rb:52: warning: previous definition of RUBY_ENGINE was here ... That's a bug in asciidoctor, but there's no need to trigger it. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> --- Documentation/asciidoctor-extensions.rb | 1 - 1 file changed, 1 deletion(-) diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb index 70a0956663..423450392d 100644 --- a/Documentation/asciidoctor-extensions.rb +++ b/Documentation/asciidoctor-extensions.rb @@ -1,4 +1,3 @@ -require 'asciidoctor' require 'asciidoctor/extensions' module Git -- 2.31.1
These were probably copy-pasted from other extensions. The name is already defined (:linkgit), and we are not using the DSL mode. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> --- Documentation/asciidoctor-extensions.rb | 4 ---- 1 file changed, 4 deletions(-) diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb index 423450392d..3dea106d00 100644 --- a/Documentation/asciidoctor-extensions.rb +++ b/Documentation/asciidoctor-extensions.rb @@ -3,10 +3,6 @@ require 'asciidoctor/extensions' module Git module Documentation class LinkGitProcessor < Asciidoctor::Extensions::InlineMacroProcessor - use_dsl - - named :chrome - def process(parent, target, attrs) prefix = parent.document.attr('git-relative-html-prefix') if parent.document.doctype == 'book' -- 2.31.1
There's no need to create verbose classes, we can do the same with a simple block. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> --- Documentation/asciidoctor-extensions.rb | 34 +++++++++++-------------- 1 file changed, 15 insertions(+), 19 deletions(-) diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb index 3dea106d00..f998a42249 100644 --- a/Documentation/asciidoctor-extensions.rb +++ b/Documentation/asciidoctor-extensions.rb @@ -1,26 +1,22 @@ require 'asciidoctor/extensions' -module Git - module Documentation - class LinkGitProcessor < Asciidoctor::Extensions::InlineMacroProcessor - def process(parent, target, attrs) - prefix = parent.document.attr('git-relative-html-prefix') - if parent.document.doctype == 'book' - "<ulink url=\"#{prefix}#{target}.html\">" \ - "#{target}(#{attrs[1]})</ulink>" - elsif parent.document.basebackend? 'html' - %(<a href="#{prefix}#{target}.html">#{target}(#{attrs[1]})</a>) - elsif parent.document.basebackend? 'docbook' - "<citerefentry>\n" \ - "<refentrytitle>#{target}</refentrytitle>" \ - "<manvolnum>#{attrs[1]}</manvolnum>\n" \ - "</citerefentry>" - end +Asciidoctor::Extensions.register do + + inline_macro :linkgit do + process do |parent, target, attrs| + prefix = parent.document.attr('git-relative-html-prefix') + if parent.document.doctype == 'book' + "<ulink url=\"#{prefix}#{target}.html\">" \ + "#{target}(#{attrs[1]})</ulink>" + elsif parent.document.basebackend? 'html' + %(<a href="#{prefix}#{target}.html">#{target}(#{attrs[1]})</a>) + elsif parent.document.basebackend? 'docbook' + "<citerefentry>\n" \ + "<refentrytitle>#{target}</refentrytitle>" \ + "<manvolnum>#{attrs[1]}</manvolnum>\n" \ + "</citerefentry>" end end end -end -Asciidoctor::Extensions.register do - inline_macro Git::Documentation::LinkGitProcessor, :linkgit end -- 2.31.1
This is what asciidoc.conf does. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> --- Documentation/asciidoctor-extensions.rb | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb index f998a42249..c77b6de350 100644 --- a/Documentation/asciidoctor-extensions.rb +++ b/Documentation/asciidoctor-extensions.rb @@ -4,11 +4,11 @@ Asciidoctor::Extensions.register do inline_macro :linkgit do process do |parent, target, attrs| - prefix = parent.document.attr('git-relative-html-prefix') if parent.document.doctype == 'book' - "<ulink url=\"#{prefix}#{target}.html\">" \ + "<ulink url=\"#{target}.html\">" \ "#{target}(#{attrs[1]})</ulink>" elsif parent.document.basebackend? 'html' + prefix = parent.document.attr('git-relative-html-prefix') %(<a href="#{prefix}#{target}.html">#{target}(#{attrs[1]})</a>) elsif parent.document.basebackend? 'docbook' "<citerefentry>\n" \ -- 2.31.1
There is no need to execute extra code every time the process block is called. In Ruby the lexical scope is shared, so we can define variables in the register block scope, and all the rest will inherit those variables. Based on the doctype and basebackend one of three blocks is selected for the inline_macro. However, the conditionals will be run only once. In the end Ruby will only run the code between `process do end`, nothing else. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> --- Documentation/asciidoctor-extensions.rb | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb index c77b6de350..a678704e17 100644 --- a/Documentation/asciidoctor-extensions.rb +++ b/Documentation/asciidoctor-extensions.rb @@ -2,15 +2,21 @@ require 'asciidoctor/extensions' Asciidoctor::Extensions.register do + doc = document + inline_macro :linkgit do - process do |parent, target, attrs| - if parent.document.doctype == 'book' + if doc.doctype == 'book' + process do |parent, target, attrs| "<ulink url=\"#{target}.html\">" \ "#{target}(#{attrs[1]})</ulink>" - elsif parent.document.basebackend? 'html' - prefix = parent.document.attr('git-relative-html-prefix') + end + elsif doc.basebackend? 'html' + prefix = doc.attr('git-relative-html-prefix') + process do |parent, target, attrs| %(<a href="#{prefix}#{target}.html">#{target}(#{attrs[1]})</a>) - elsif parent.document.basebackend? 'docbook' + end + elsif doc.basebackend? 'docbook' + process do |parent, target, attrs| "<citerefentry>\n" \ "<refentrytitle>#{target}</refentrytitle>" \ "<manvolnum>#{attrs[1]}</manvolnum>\n" \ -- 2.31.1
Using printf style formatting (more familiar to git developers), and also here document. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> --- Documentation/asciidoctor-extensions.rb | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb index a678704e17..eb2326d05a 100644 --- a/Documentation/asciidoctor-extensions.rb +++ b/Documentation/asciidoctor-extensions.rb @@ -7,20 +7,20 @@ Asciidoctor::Extensions.register do inline_macro :linkgit do if doc.doctype == 'book' process do |parent, target, attrs| - "<ulink url=\"#{target}.html\">" \ - "#{target}(#{attrs[1]})</ulink>" + '<ulink url="%1$s.html">%1$s(%2$s)</ulink>' % [target, attrs[1]] end elsif doc.basebackend? 'html' prefix = doc.attr('git-relative-html-prefix') process do |parent, target, attrs| - %(<a href="#{prefix}#{target}.html">#{target}(#{attrs[1]})</a>) + %(<a href="#{prefix}%1$s.html">%1$s(%2$s)</a>) % [target, attrs[1]] end elsif doc.basebackend? 'docbook' process do |parent, target, attrs| - "<citerefentry>\n" \ - "<refentrytitle>#{target}</refentrytitle>" \ - "<manvolnum>#{attrs[1]}</manvolnum>\n" \ - "</citerefentry>" + <<~EOF % [target, attrs[1]] + <citerefentry> + <refentrytitle>%s</refentrytitle><manvolnum>%s</manvolnum> + </citerefentry> + EOF end end end -- 2.31.1
This way we don't have to specify the block to execute on every conditional. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> --- Documentation/asciidoctor-extensions.rb | 26 ++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb index eb2326d05a..f7696f19f6 100644 --- a/Documentation/asciidoctor-extensions.rb +++ b/Documentation/asciidoctor-extensions.rb @@ -6,22 +6,22 @@ Asciidoctor::Extensions.register do inline_macro :linkgit do if doc.doctype == 'book' - process do |parent, target, attrs| - '<ulink url="%1$s.html">%1$s(%2$s)</ulink>' % [target, attrs[1]] - end + format = '<ulink url="%1$s.html">%1$s(%2$s)</ulink>' elsif doc.basebackend? 'html' prefix = doc.attr('git-relative-html-prefix') - process do |parent, target, attrs| - %(<a href="#{prefix}%1$s.html">%1$s(%2$s)</a>) % [target, attrs[1]] - end + format = %(<a href="#{prefix}%1$s.html">%1$s(%2$s)</a>) elsif doc.basebackend? 'docbook' - process do |parent, target, attrs| - <<~EOF % [target, attrs[1]] - <citerefentry> - <refentrytitle>%s</refentrytitle><manvolnum>%s</manvolnum> - </citerefentry> - EOF - end + format = <<~EOF + <citerefentry> + <refentrytitle>%s</refentrytitle><manvolnum>%s</manvolnum> + </citerefentry> + EOF + else + return + end + + process do |_, target, attrs| + format % [target, attrs[1]] end end -- 2.31.1
Doesn't do anything, but otherwise we get a random name. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> --- Documentation/asciidoctor-extensions.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb index f7696f19f6..7d1b94a266 100644 --- a/Documentation/asciidoctor-extensions.rb +++ b/Documentation/asciidoctor-extensions.rb @@ -1,6 +1,6 @@ require 'asciidoctor/extensions' -Asciidoctor::Extensions.register do +Asciidoctor::Extensions.register :git do doc = document -- 2.31.1