git@vger.kernel.org list mirror (unofficial, one of many)
 help / color / mirror / code / Atom feed
* [PATCH 00/12] doc: cleanup old cruft and asciidoctor revamp
@ 2021-05-15 11:56 Felipe Contreras
  2021-05-15 11:56 ` [PATCH 01/12] doc: remove GNU troff workaround Felipe Contreras
                   ` (11 more replies)
  0 siblings, 12 replies; 13+ messages in thread
From: Felipe Contreras @ 2021-05-15 11:56 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Martin Ågren, brian m . carlson, Felipe Contreras

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


^ permalink raw reply	[flat|nested] 13+ messages in thread

* [PATCH 01/12] doc: remove GNU troff workaround
  2021-05-15 11:56 [PATCH 00/12] doc: cleanup old cruft and asciidoctor revamp Felipe Contreras
@ 2021-05-15 11:56 ` Felipe Contreras
  2021-05-15 11:56 ` [PATCH 02/12] doc: use --stringparam in xmlto Felipe Contreras
                   ` (10 subsequent siblings)
  11 siblings, 0 replies; 13+ messages in thread
From: Felipe Contreras @ 2021-05-15 11:56 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Martin Ågren, brian m . carlson, 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
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


^ permalink raw reply	[flat|nested] 13+ messages in thread

* [PATCH 02/12] doc: use --stringparam in xmlto
  2021-05-15 11:56 [PATCH 00/12] doc: cleanup old cruft and asciidoctor revamp Felipe Contreras
  2021-05-15 11:56 ` [PATCH 01/12] doc: remove GNU troff workaround Felipe Contreras
@ 2021-05-15 11:56 ` Felipe Contreras
  2021-05-15 11:56 ` [PATCH 03/12] doc: simplify version passing Felipe Contreras
                   ` (9 subsequent siblings)
  11 siblings, 0 replies; 13+ messages in thread
From: Felipe Contreras @ 2021-05-15 11:56 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Martin Ågren, brian m . carlson, 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
-- 
2.31.1


^ permalink raw reply	[flat|nested] 13+ messages in thread

* [PATCH 03/12] doc: simplify version passing
  2021-05-15 11:56 [PATCH 00/12] doc: cleanup old cruft and asciidoctor revamp Felipe Contreras
  2021-05-15 11:56 ` [PATCH 01/12] doc: remove GNU troff workaround Felipe Contreras
  2021-05-15 11:56 ` [PATCH 02/12] doc: use --stringparam in xmlto Felipe Contreras
@ 2021-05-15 11:56 ` Felipe Contreras
  2021-05-15 11:56 ` [PATCH 04/12] doc: asciidoc: remove unnecessary attribute Felipe Contreras
                   ` (8 subsequent siblings)
  11 siblings, 0 replies; 13+ messages in thread
From: Felipe Contreras @ 2021-05-15 11:56 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Martin Ågren, brian m . carlson, 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.31.1


^ permalink raw reply	[flat|nested] 13+ messages in thread

* [PATCH 04/12] doc: asciidoc: remove unnecessary attribute
  2021-05-15 11:56 [PATCH 00/12] doc: cleanup old cruft and asciidoctor revamp Felipe Contreras
                   ` (2 preceding siblings ...)
  2021-05-15 11:56 ` [PATCH 03/12] doc: simplify version passing Felipe Contreras
@ 2021-05-15 11:56 ` Felipe Contreras
  2021-05-15 11:56 ` [PATCH 05/12] doc: asciidoctor: remove unnecessary require Felipe Contreras
                   ` (7 subsequent siblings)
  11 siblings, 0 replies; 13+ messages in thread
From: Felipe Contreras @ 2021-05-15 11:56 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Martin Ågren, brian m . carlson, 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=&#42;
-plus=&#43;
 caret=&#94;
 startsb=&#91;
 endsb=&#93;
-- 
2.31.1


^ permalink raw reply	[flat|nested] 13+ messages in thread

* [PATCH 05/12] doc: asciidoctor: remove unnecessary require
  2021-05-15 11:56 [PATCH 00/12] doc: cleanup old cruft and asciidoctor revamp Felipe Contreras
                   ` (3 preceding siblings ...)
  2021-05-15 11:56 ` [PATCH 04/12] doc: asciidoc: remove unnecessary attribute Felipe Contreras
@ 2021-05-15 11:56 ` Felipe Contreras
  2021-05-15 11:56 ` [PATCH 06/12] doc: asciidoctor: remove cruft Felipe Contreras
                   ` (6 subsequent siblings)
  11 siblings, 0 replies; 13+ messages in thread
From: Felipe Contreras @ 2021-05-15 11:56 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Martin Ågren, brian m . carlson, Felipe Contreras

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


^ permalink raw reply	[flat|nested] 13+ messages in thread

* [PATCH 06/12] doc: asciidoctor: remove cruft
  2021-05-15 11:56 [PATCH 00/12] doc: cleanup old cruft and asciidoctor revamp Felipe Contreras
                   ` (4 preceding siblings ...)
  2021-05-15 11:56 ` [PATCH 05/12] doc: asciidoctor: remove unnecessary require Felipe Contreras
@ 2021-05-15 11:56 ` Felipe Contreras
  2021-05-15 11:56 ` [PATCH 07/12] doc: asciidoctor: reorganize extensions Felipe Contreras
                   ` (5 subsequent siblings)
  11 siblings, 0 replies; 13+ messages in thread
From: Felipe Contreras @ 2021-05-15 11:56 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Martin Ågren, brian m . carlson, Felipe Contreras

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


^ permalink raw reply	[flat|nested] 13+ messages in thread

* [PATCH 07/12] doc: asciidoctor: reorganize extensions
  2021-05-15 11:56 [PATCH 00/12] doc: cleanup old cruft and asciidoctor revamp Felipe Contreras
                   ` (5 preceding siblings ...)
  2021-05-15 11:56 ` [PATCH 06/12] doc: asciidoctor: remove cruft Felipe Contreras
@ 2021-05-15 11:56 ` Felipe Contreras
  2021-05-15 11:56 ` [PATCH 08/12] doc: asciidoctor: use html-prefix only for html Felipe Contreras
                   ` (4 subsequent siblings)
  11 siblings, 0 replies; 13+ messages in thread
From: Felipe Contreras @ 2021-05-15 11:56 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Martin Ågren, brian m . carlson, Felipe Contreras

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


^ permalink raw reply	[flat|nested] 13+ messages in thread

* [PATCH 08/12] doc: asciidoctor: use html-prefix only for html
  2021-05-15 11:56 [PATCH 00/12] doc: cleanup old cruft and asciidoctor revamp Felipe Contreras
                   ` (6 preceding siblings ...)
  2021-05-15 11:56 ` [PATCH 07/12] doc: asciidoctor: reorganize extensions Felipe Contreras
@ 2021-05-15 11:56 ` Felipe Contreras
  2021-05-15 11:56 ` [PATCH 09/12] doc: asciidoctor: refactor macro registration Felipe Contreras
                   ` (3 subsequent siblings)
  11 siblings, 0 replies; 13+ messages in thread
From: Felipe Contreras @ 2021-05-15 11:56 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Martin Ågren, brian m . carlson, Felipe Contreras

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


^ permalink raw reply	[flat|nested] 13+ messages in thread

* [PATCH 09/12] doc: asciidoctor: refactor macro registration
  2021-05-15 11:56 [PATCH 00/12] doc: cleanup old cruft and asciidoctor revamp Felipe Contreras
                   ` (7 preceding siblings ...)
  2021-05-15 11:56 ` [PATCH 08/12] doc: asciidoctor: use html-prefix only for html Felipe Contreras
@ 2021-05-15 11:56 ` Felipe Contreras
  2021-05-15 11:56 ` [PATCH 10/12] doc: asciidoctor: improve string handling Felipe Contreras
                   ` (2 subsequent siblings)
  11 siblings, 0 replies; 13+ messages in thread
From: Felipe Contreras @ 2021-05-15 11:56 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Martin Ågren, brian m . carlson, Felipe Contreras

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


^ permalink raw reply	[flat|nested] 13+ messages in thread

* [PATCH 10/12] doc: asciidoctor: improve string handling
  2021-05-15 11:56 [PATCH 00/12] doc: cleanup old cruft and asciidoctor revamp Felipe Contreras
                   ` (8 preceding siblings ...)
  2021-05-15 11:56 ` [PATCH 09/12] doc: asciidoctor: refactor macro registration Felipe Contreras
@ 2021-05-15 11:56 ` Felipe Contreras
  2021-05-15 11:56 ` [PATCH 11/12] doc: asciidoctor: split the format from the code Felipe Contreras
  2021-05-15 11:56 ` [PATCH 12/12] doc: asciidoctor: specify name of our group Felipe Contreras
  11 siblings, 0 replies; 13+ messages in thread
From: Felipe Contreras @ 2021-05-15 11:56 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Martin Ågren, brian m . carlson, Felipe Contreras

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


^ permalink raw reply	[flat|nested] 13+ messages in thread

* [PATCH 11/12] doc: asciidoctor: split the format from the code
  2021-05-15 11:56 [PATCH 00/12] doc: cleanup old cruft and asciidoctor revamp Felipe Contreras
                   ` (9 preceding siblings ...)
  2021-05-15 11:56 ` [PATCH 10/12] doc: asciidoctor: improve string handling Felipe Contreras
@ 2021-05-15 11:56 ` Felipe Contreras
  2021-05-15 11:56 ` [PATCH 12/12] doc: asciidoctor: specify name of our group Felipe Contreras
  11 siblings, 0 replies; 13+ messages in thread
From: Felipe Contreras @ 2021-05-15 11:56 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Martin Ågren, brian m . carlson, Felipe Contreras

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


^ permalink raw reply	[flat|nested] 13+ messages in thread

* [PATCH 12/12] doc: asciidoctor: specify name of our group
  2021-05-15 11:56 [PATCH 00/12] doc: cleanup old cruft and asciidoctor revamp Felipe Contreras
                   ` (10 preceding siblings ...)
  2021-05-15 11:56 ` [PATCH 11/12] doc: asciidoctor: split the format from the code Felipe Contreras
@ 2021-05-15 11:56 ` Felipe Contreras
  11 siblings, 0 replies; 13+ messages in thread
From: Felipe Contreras @ 2021-05-15 11:56 UTC (permalink / raw)
  To: git
  Cc: Junio C Hamano, Martin Ågren, brian m . carlson, Felipe Contreras

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


^ permalink raw reply	[flat|nested] 13+ messages in thread

end of thread, other threads:[~2021-05-15 11:57 UTC | newest]

Thread overview: 13+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-05-15 11:56 [PATCH 00/12] doc: cleanup old cruft and asciidoctor revamp Felipe Contreras
2021-05-15 11:56 ` [PATCH 01/12] doc: remove GNU troff workaround Felipe Contreras
2021-05-15 11:56 ` [PATCH 02/12] doc: use --stringparam in xmlto Felipe Contreras
2021-05-15 11:56 ` [PATCH 03/12] doc: simplify version passing Felipe Contreras
2021-05-15 11:56 ` [PATCH 04/12] doc: asciidoc: remove unnecessary attribute Felipe Contreras
2021-05-15 11:56 ` [PATCH 05/12] doc: asciidoctor: remove unnecessary require Felipe Contreras
2021-05-15 11:56 ` [PATCH 06/12] doc: asciidoctor: remove cruft Felipe Contreras
2021-05-15 11:56 ` [PATCH 07/12] doc: asciidoctor: reorganize extensions Felipe Contreras
2021-05-15 11:56 ` [PATCH 08/12] doc: asciidoctor: use html-prefix only for html Felipe Contreras
2021-05-15 11:56 ` [PATCH 09/12] doc: asciidoctor: refactor macro registration Felipe Contreras
2021-05-15 11:56 ` [PATCH 10/12] doc: asciidoctor: improve string handling Felipe Contreras
2021-05-15 11:56 ` [PATCH 11/12] doc: asciidoctor: split the format from the code Felipe Contreras
2021-05-15 11:56 ` [PATCH 12/12] doc: asciidoctor: specify name of our group Felipe Contreras

Code repositories for project(s) associated with this inbox:

	https://80x24.org/mirrors/git.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).