[PATCH v2 00/11] doc: asciidoctor: direct man page creation and fixes

[PATCH v2 00/11] doc: asciidoctor: direct man page creation and fixes

[Felipe Contreras]

This patch series enables direct man page creation with asciidoctor, but in addition tries to
minimize the difference with asciidoc+docbook.

I fixed as many issues as I could, and now the doc-diff looks very sensible. I could not find any
major issues, however, some minor ones still remain.

On the other hand the asciidoc method has issues as well, so it's not clear which method is superior
at this point; both have advantages and disadvantages.

At the very least the man pages with pure asciidoctor should be quite usable now.

This series builds on top of my previous cleanups [1].

[1] https://lore.kernel.org/git/20210521223701.526547-1-felipe.contreras@gmail.com/

Felipe Contreras (9):
  doc: doc-diff: set docdate manually
  doc: use asciidoctor to build man pages directly
  doc: asciidoctor: add linkgit macros in man pages
  doc: add man pages workaround for asciidoctor
  doc: asciidoctor: add hack for xrefs
  doc: asciidoctor: add hack to improve links
  doc: asciidoctor: add support for baseurl
  doc: asciidoctor: cleanup man page hack
  doc: asciidoctor: add hack for old versions

Jeff King (1):
  doc-diff: support asciidoctor man pages

Martin Ågren (1):
  doc-diff: drop --cut-footer switch

 Documentation/Makefile                  | 15 ++++++--
 Documentation/asciidoctor-extensions.rb | 51 +++++++++++++++++++++++++
 Documentation/doc-diff                  | 35 +++++++++--------
 3 files changed, 82 insertions(+), 19 deletions(-)

Range-diff against v1:
 1:  de0ecf9c0e <  -:  ---------- doc: allow the user to provide ASCIIDOC_EXTRA
 2:  22a35efa3f <  -:  ---------- doc: doc-diff: allow more than one flag
 3:  a8ad5c703a <  -:  ---------- doc: doc-diff: set docdate manually
 4:  4d0266a3a1 <  -:  ---------- doc: use asciidoctor to build man pages directly
 5:  5efb19348b <  -:  ---------- doc: asciidoctor: add linkgit macros in man pages
 6:  d5d006298e <  -:  ---------- doc: join mansource and manversion
 7:  7c8b502df9 <  -:  ---------- doc: add man pages workaround for asciidoctor
 -:  ---------- >  1:  a2f85f4b05 doc: doc-diff: set docdate manually
 -:  ---------- >  2:  13085a13b6 doc-diff: drop --cut-footer switch
 -:  ---------- >  3:  f0b3576d77 doc: use asciidoctor to build man pages directly
 -:  ---------- >  4:  8b3bb9e9f4 doc-diff: support asciidoctor man pages
 -:  ---------- >  5:  3f9859b223 doc: asciidoctor: add linkgit macros in man pages
 -:  ---------- >  6:  df27fcb9a2 doc: add man pages workaround for asciidoctor
 8:  5d5e9d99ac !  7:  5f0ae41e3e doc: asciidoctor: add hack for xrefs
    @@ Commit message
     
      ## Documentation/asciidoctor-extensions.rb ##
     @@
    - require 'asciidoctor'
      require 'asciidoctor/extensions'
     +require 'asciidoctor/converter/manpage'
     +
    @@ Documentation/asciidoctor-extensions.rb
     +        orig_convert_inline_anchor(node)
     +      end
     +    end
    ++    alias inline_anchor convert_inline_anchor # For old versions of asciidoctor
     +  end
     +end
      
    - module Git
    -   module Documentation
    + Asciidoctor::Extensions.register :git do
    + 
 9:  f4a4f1394e =  8:  a8fb29d893 doc: asciidoctor: add hack to improve links
10:  894802bfbb !  9:  272e6e8551 doc: asciidoctor: add support for baseurl
    @@ Commit message
     
      ## Documentation/Makefile ##
     @@ Documentation/Makefile: ASCIIDOC_DOCBOOK = docbook5
    - override ASCIIDOC_EXTRA += -acompat-mode -atabsize=8
    - override ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions
    - override ASCIIDOC_EXTRA += -alitdd='&\#x2d;&\#x2d;'
    -+override ASCIIDOC_EXTRA += -abaseurl='$(MAN_BASE_URL)'
    + ASCIIDOC_EXTRA += -acompat-mode -atabsize=8
    + ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions
    + ASCIIDOC_EXTRA += -alitdd='&\#x2d;&\#x2d;'
    ++ASCIIDOC_EXTRA += -abaseurl='$(MAN_BASE_URL)'
      ASCIIDOC_DEPS = asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS
      DBLATEX_COMMON =
      XMLTO_EXTRA += --skip-validation
11:  d3b6899ed8 ! 10:  928a632038 doc: asciidoctor: cleanup man page hack
    @@ Documentation/asciidoctor-extensions.rb: module Asciidoctor
     +        nil
            end
          end
    -   end
    +     alias inline_anchor convert_inline_anchor # For old versions of asciidoctor
 -:  ---------- > 11:  758e5be3b7 doc: asciidoctor: add hack for old versions
-- 
2.32.0.rc0

[PATCH v2 01/11] doc: doc-diff: set docdate manually

[Felipe Contreras]

In order to minimize the differences in the footer.

Asciidoc automatically generates a date with format '%Y-%m-%d', while
asciidoctor '%F'.

I personally prefer the latter, so only modify it for diff purposes.

Fixes tons of these:

-Git omitted                       01/01/1970                        GIT-ADD(1)
+Git omitted                       1970-01-01                        GIT-ADD(1)

Note that we have to add quotes when passing around $makemanflags, as it
now may contain whitespace due to multiple arguments (but the
dereference inside render_tree must remain unquoted, because it wants to perform
whitespace splitting to get the individual arguments back).

Comments-by: Jeff King <peff@peff.net>
Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/Makefile | 2 +-
 Documentation/doc-diff | 6 +++---
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 47053c78f8..b68ab57239 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -136,7 +136,7 @@ ASCIIDOC_EXTRA =
 ASCIIDOC_HTML = xhtml11
 ASCIIDOC_DOCBOOK = docbook
 ASCIIDOC_CONF = -f asciidoc.conf
-ASCIIDOC_COMMON = $(ASCIIDOC) $(ASCIIDOC_EXTRA) $(ASCIIDOC_CONF) \
+ASCIIDOC_COMMON = $(ASCIIDOC) $(ASCIIDOC_EXTRA) $(ASCIIDOC_FLAGS) $(ASCIIDOC_CONF) \
 		-amanmanual='Git Manual' -amansource='Git $(GIT_VERSION)'
 ASCIIDOC_DEPS = asciidoc.conf GIT-ASCIIDOCFLAGS
 TXT_TO_HTML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_HTML)
diff --git a/Documentation/doc-diff b/Documentation/doc-diff
index 1694300e50..c11b90a6ef 100755
--- a/Documentation/doc-diff
+++ b/Documentation/doc-diff
@@ -111,7 +111,7 @@ construct_makemanflags () {
 		echo USE_ASCIIDOCTOR=
 	elif test "$1" = "-asciidoctor"
 	then
-		echo USE_ASCIIDOCTOR=YesPlease
+		echo USE_ASCIIDOCTOR=YesPlease ASCIIDOC_FLAGS='-adocdate="01/01/1970"'
 	fi
 }
 
@@ -181,6 +181,6 @@ render_tree () {
 	fi
 }
 
-render_tree $from_oid $from_dir $from_makemanflags &&
-render_tree $to_oid $to_dir $to_makemanflags &&
+render_tree $from_oid $from_dir "$from_makemanflags" &&
+render_tree $to_oid $to_dir "$to_makemanflags" &&
 git -C $tmp/rendered diff --no-index "$@" $from_dir $to_dir
-- 
2.32.0.rc0

Re: [PATCH v2 01/11] doc: doc-diff: set docdate manually

[Bagas Sanjaya]

On 22/05/21 05.44, Felipe Contreras wrote:
> In order to minimize the differences in the footer.
> 
> Asciidoc automatically generates a date with format '%Y-%m-%d', while
> asciidoctor '%F'.
> 

%F is short yyyy-mm-dd date. AFAIK, it is the same effect as `%Y-%m-%d`.

> I personally prefer the latter, so only modify it for diff purposes.
> 
> Fixes tons of these:
> 
> -Git omitted                       01/01/1970                        GIT-ADD(1)
> +Git omitted                       1970-01-01                        GIT-ADD(1)
>
  
So, the asciidoctor generated date was the bottom one, while the asciidoc
counterpart was the above one, right?

The above one, however, was actually %m/%d/%Y.

-- 
An old man doll... just what I always wanted! - Clara

Re: [PATCH v2 01/11] doc: doc-diff: set docdate manually

[Felipe Contreras]

Bagas Sanjaya wrote:
> On 22/05/21 05.44, Felipe Contreras wrote:
> > In order to minimize the differences in the footer.
> > 
> > Asciidoc automatically generates a date with format '%Y-%m-%d', while
> > asciidoctor '%F'.
> > 
> 
> %F is short yyyy-mm-dd date. AFAIK, it is the same effect as `%Y-%m-%d`.

Right, I noticed I was wrong when trying to use -adocdate in
asciidoctor. It's actually ignored.

The date format probably comes from docbook. The commit message needs to
be updated.

> > I personally prefer the latter, so only modify it for diff purposes.
> > 
> > Fixes tons of these:
> > 
> > -Git omitted                       01/01/1970                        GIT-ADD(1)
> > +Git omitted                       1970-01-01                        GIT-ADD(1)
> >
>   
> So, the asciidoctor generated date was the bottom one, while the asciidoc
> counterpart was the above one, right?

Yeap.

> The above one, however, was actually %m/%d/%Y.

Indeed, the commit message is inaccurate.

-- 
Felipe Contreras

[PATCH v2 02/11] doc-diff: drop --cut-footer switch

[Felipe Contreras]

From: Martin Ågren <martin.agren@gmail.com>

Now that our doc-diff convinces Asciidoctor to insert the exact same
formatted dummy date as AsciiDoc, we can drop the --cut-footer switch.
It has been useful to ignore this difference between the two tools, but
it's effectively a no-op now. Similar to when we repurposed this from
--cut-header-footer in 83b0b8953e ("doc-diff: replace
--cut-header-footer with --cut-footer", 2019-09-16), just drop it
without worrying about any kind of backwards compatibility or user-base.

Signed-off-by: Martin Ågren <martin.agren@gmail.com>
Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/doc-diff | 18 ++----------------
 1 file changed, 2 insertions(+), 16 deletions(-)

diff --git a/Documentation/doc-diff b/Documentation/doc-diff
index c11b90a6ef..6b6bb444ac 100755
--- a/Documentation/doc-diff
+++ b/Documentation/doc-diff
@@ -21,7 +21,6 @@ asciidoc		use asciidoc with both commits
 to-asciidoc		use asciidoc with the 'to'-commit
 to-asciidoctor		use asciidoctor with the 'to'-commit
 asciidoctor		use asciidoctor with both commits
-cut-footer		cut away footer
 "
 SUBDIRECTORY_OK=1
 . "$(git --exec-path)/git-sh-setup"
@@ -31,7 +30,6 @@ force=
 clean=
 from_program=
 to_program=
-cut_footer=
 while test $# -gt 0
 do
 	case "$1" in
@@ -55,8 +53,6 @@ do
 	--asciidoc)
 		from_program=-asciidoc
 		to_program=-asciidoc ;;
-	--cut-footer)
-		cut_footer=-cut-footer ;;
 	--)
 		shift; break ;;
 	*)
@@ -118,8 +114,8 @@ construct_makemanflags () {
 from_makemanflags=$(construct_makemanflags "$from_program") &&
 to_makemanflags=$(construct_makemanflags "$to_program") &&
 
-from_dir=$from_oid$from_program$cut_footer &&
-to_dir=$to_oid$to_program$cut_footer &&
+from_dir=$from_oid$from_program &&
+to_dir=$to_oid$to_program &&
 
 # generate_render_makefile <srcdir> <dstdir>
 generate_render_makefile () {
@@ -168,16 +164,6 @@ render_tree () {
 			"$tmp/rendered/$dname+" |
 		make -j$parallel -f - &&
 		mv "$tmp/rendered/$dname+" "$tmp/rendered/$dname"
-
-		if test "$cut_footer" = "-cut-footer"
-		then
-			for f in $(find "$tmp/rendered/$dname" -type f)
-			do
-				head -n -2 "$f" | sed -e '${/^$/d}' >"$f+" &&
-				mv "$f+" "$f" ||
-				return 1
-			done
-		fi
 	fi
 }
 
-- 
2.32.0.rc0

[PATCH v2 03/11] doc: use asciidoctor to build man pages directly

[Felipe Contreras]

There's no need to use xmlto to build the man pages when modern
asciidoctor can do it by itself.

This new mode will be active only when both USE_ASCIIDOCTOR and
USE_ASCIIDOCTOR_MANPAGE are set.

Suggested-by: Bagas Sanjaya <bagasdotme@gmail.com>
Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/Makefile | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index b68ab57239..0c654f4ec9 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -189,6 +189,9 @@ ASCIIDOC_DEPS = asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS
 DBLATEX_COMMON =
 XMLTO_EXTRA += --skip-validation
 XMLTO_EXTRA += -x manpage.xsl
+ifdef USE_ASCIIDOCTOR_MANPAGE
+TXT_TO_MAN = $(ASCIIDOC_COMMON) -b manpage
+endif
 endif
 
 SHELL_PATH ?= $(SHELL)
@@ -324,7 +327,7 @@ mergetools-list.made: ../git-mergetool--lib.sh $(wildcard ../mergetools/*)
 		show_tool_names can_merge "* " || :' >mergetools-merge.txt && \
 	date >$@
 
-TRACK_ASCIIDOCFLAGS = $(subst ','\'',$(ASCIIDOC_COMMON):$(ASCIIDOC_HTML):$(ASCIIDOC_DOCBOOK))
+TRACK_ASCIIDOCFLAGS = $(subst ','\'',$(ASCIIDOC_COMMON):$(ASCIIDOC_HTML):$(ASCIIDOC_DOCBOOK):$(USE_ASCIIDOCTOR_MANPAGE))
 
 GIT-ASCIIDOCFLAGS: FORCE
 	@FLAGS='$(TRACK_ASCIIDOCFLAGS)'; \
@@ -349,8 +352,13 @@ $(MAN_HTML): %.html : %.txt $(ASCIIDOC_DEPS)
 $(OBSOLETE_HTML): %.html : %.txto $(ASCIIDOC_DEPS)
 	$(QUIET_ASCIIDOC)$(TXT_TO_HTML) -o $@ $<
 
-%.1 %.5 %.7 : %.xml $(wildcard manpage*.xsl)
+ifdef TXT_TO_MAN
+%.1 %.5 %.7 : %.txt $(ASCIIDOC_DEPS)
+	$(QUIET_ASCIIDOC)$(TXT_TO_MAN) -o $@ $<
+else
+%.1 %.5 %.7 : %.xml manpage-base-url.xsl $(wildcard manpage*.xsl)
 	$(QUIET_XMLTO)$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<
+endif
 
 %.xml : %.txt $(ASCIIDOC_DEPS)
 	$(QUIET_ASCIIDOC)$(TXT_TO_XML) -d manpage -o $@ $<
-- 
2.32.0.rc0

RE: [PATCH v2 03/11] doc: use asciidoctor to build man pages directly

[Felipe Contreras]

Felipe Contreras wrote:
> --- a/Documentation/Makefile
> +++ b/Documentation/Makefile

> @@ -349,8 +352,13 @@ $(MAN_HTML): %.html : %.txt $(ASCIIDOC_DEPS)
>  $(OBSOLETE_HTML): %.html : %.txto $(ASCIIDOC_DEPS)
>  	$(QUIET_ASCIIDOC)$(TXT_TO_HTML) -o $@ $<
>  
> -%.1 %.5 %.7 : %.xml $(wildcard manpage*.xsl)
> +ifdef TXT_TO_MAN
> +%.1 %.5 %.7 : %.txt $(ASCIIDOC_DEPS)
> +	$(QUIET_ASCIIDOC)$(TXT_TO_MAN) -o $@ $<
> +else
> +%.1 %.5 %.7 : %.xml manpage-base-url.xsl $(wildcard manpage*.xsl)
>  	$(QUIET_XMLTO)$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<
> +endif

This was a conflict mistake, the manpage-base-url.xsl file is not
present any more, should be:

+%.1 %.5 %.7 : %.xml $(wildcard manpage*.xsl)

I fixed in my local branch.

-- 
Felipe Contreras

[PATCH v2 04/11] doc-diff: support asciidoctor man pages

[Felipe Contreras]

From: Jeff King <peff@peff.net>

The new option enables both asciidoctor as well as its direct-to-manpage
mode that skips xmlto. This lets you view the rendered difference
between the two pipelines with something like:

  ./doc-diff --from-asciidoctor --to-asciidoctor-direct HEAD HEAD

Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/doc-diff | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/Documentation/doc-diff b/Documentation/doc-diff
index 6b6bb444ac..52cf639f4d 100755
--- a/Documentation/doc-diff
+++ b/Documentation/doc-diff
@@ -17,10 +17,14 @@ f			force rebuild; do not rely on cached results
 c,clean			cleanup temporary working files
 from-asciidoc		use asciidoc with the 'from'-commit
 from-asciidoctor	use asciidoctor with the 'from'-commit
+from-asciidoctor-direct use asciidoctor without xmlto for 'from'-commit
 asciidoc		use asciidoc with both commits
 to-asciidoc		use asciidoc with the 'to'-commit
 to-asciidoctor		use asciidoctor with the 'to'-commit
+to-asciidoctor-direct   use asciidoctor without xmlto for 'to'-commit
 asciidoctor		use asciidoctor with both commits
+asciidoctor-direct      use asciidoctor without xml for both commits
+cut-footer		cut away footer
 "
 SUBDIRECTORY_OK=1
 . "$(git --exec-path)/git-sh-setup"
@@ -53,6 +57,15 @@ do
 	--asciidoc)
 		from_program=-asciidoc
 		to_program=-asciidoc ;;
+	--cut-footer)
+		cut_footer=-cut-footer ;;
+	--from-asciidoctor-direct)
+		from_program=-asciidoctor-direct ;;
+	--to-asciidoctor-direct)
+		to_program=-asciidoctor-direct ;;
+	--asciidoctor-direct)
+		from_program=-asciidoctor-direct
+		to_program=-asciidoctor-direct ;;
 	--)
 		shift; break ;;
 	*)
@@ -108,6 +121,10 @@ construct_makemanflags () {
 	elif test "$1" = "-asciidoctor"
 	then
 		echo USE_ASCIIDOCTOR=YesPlease ASCIIDOC_FLAGS='-adocdate="01/01/1970"'
+	elif test "$1" = "-asciidoctor-direct"
+	then
+		echo USE_ASCIIDOCTOR=YesPlease ASCIIDOC_FLAGS='-adocdate="01/01/1970"'
+		echo USE_ASCIIDOCTOR_MANPAGE=YesPlease
 	fi
 }
 
-- 
2.32.0.rc0

RE: [PATCH v2 04/11] doc-diff: support asciidoctor man pages

[Felipe Contreras]

Felipe Contreras wrote:
> From: Jeff King <peff@peff.net>
> diff --git a/Documentation/doc-diff b/Documentation/doc-diff
> index 6b6bb444ac..52cf639f4d 100755
> --- a/Documentation/doc-diff
> +++ b/Documentation/doc-diff
> @@ -17,10 +17,14 @@ f			force rebuild; do not rely on cached results
>  c,clean			cleanup temporary working files
>  from-asciidoc		use asciidoc with the 'from'-commit
>  from-asciidoctor	use asciidoctor with the 'from'-commit
> +from-asciidoctor-direct use asciidoctor without xmlto for 'from'-commit
>  asciidoc		use asciidoc with both commits
>  to-asciidoc		use asciidoc with the 'to'-commit
>  to-asciidoctor		use asciidoctor with the 'to'-commit
> +to-asciidoctor-direct   use asciidoctor without xmlto for 'to'-commit
>  asciidoctor		use asciidoctor with both commits
> +asciidoctor-direct      use asciidoctor without xml for both commits

> +cut-footer		cut away footer

Oops. This obviously sneaked by; doesn't belong here.

-- 
Felipe Contreras

[PATCH v2 05/11] doc: asciidoctor: add linkgit macros in man pages

[Felipe Contreras]

Fixes the doc-diff:

-       Please see git-commit(1) for alternative ways to add content to a
-       commit.
+       Please see  for alternative ways to add content to a commit.

Comments-by: brian m. carlson <sandals@crustytoothpaste.net>
Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/asciidoctor-extensions.rb | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb
index b36317e4d2..6c4153f628 100644
--- a/Documentation/asciidoctor-extensions.rb
+++ b/Documentation/asciidoctor-extensions.rb
@@ -10,6 +10,8 @@ Asciidoctor::Extensions.register :git do
     elsif doc.basebackend? 'html'
       prefix = doc.attr('git-relative-html-prefix')
       format = %(<a href="#{prefix}%1$s.html">%1$s(%2$s)</a>)
+    elsif doc.basebackend? 'manpage'
+      format = "\e\\fB%s\e\\fP(%s)"
     elsif doc.basebackend? 'docbook'
       format = <<~EOF.chomp
       <citerefentry>
-- 
2.32.0.rc0

[PATCH v2 06/11] doc: add man pages workaround for asciidoctor

[Felipe Contreras]

Currently asciidoctor doesn't convert number character references
(&#xx;) correctly for man pages.

This hack fixes the issue with minimum changes elsewhere so it's easy to
remove when fixed.

Fixes doc-diffs like:

            so line count cannot be shown) and there is no difference between
            indexed copy and the working tree version (if the working tree
            version were also different, binary would have been shown in place
-           of nothing). The other file, git-add--interactive.perl, has 403
-           lines added and 35 lines deleted if you commit what is in the
-           index, but working tree file has further modifications (one
+           of nothing). The other file, git-add--interactive.perl,
+           has 403 lines added and 35 lines deleted if you commit what is in
+           the index, but working tree file has further modifications (one
            addition and one deletion).

https://github.com/asciidoctor/asciidoctor/issues/4059

Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/asciidoctor-extensions.rb | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb
index 6c4153f628..954acb3e7d 100644
--- a/Documentation/asciidoctor-extensions.rb
+++ b/Documentation/asciidoctor-extensions.rb
@@ -4,6 +4,12 @@ Asciidoctor::Extensions.register :git do
 
   doc = document
 
+  # Override attributes for man pages.
+  # https://github.com/asciidoctor/asciidoctor/issues/4059
+  if doc.backend == 'manpage'
+    doc.attributes.merge!({ 'litdd' => '\--', 'plus' => '+' })
+  end
+
   inline_macro :linkgit do
     if doc.doctype == 'book'
       format = '<ulink url="%1$s.html">%1$s(%2$s)</ulink>'
-- 
2.32.0.rc0

[PATCH v2 07/11] doc: asciidoctor: add hack for xrefs

[Felipe Contreras]

The docbook manpage stylesheets convert cross-references with format the
'section called “%t”'. I personally prefer the asciidoctor version, but
for now add a hack to minimize the diff.

Thanks to the extensibility of Ruby we can override corresponding method
in the man page converter.

This fixes doc-diffs like:

          --worktree-attributes
              Look for attributes in .gitattributes files in the working tree as
  -           well (see the section called “ATTRIBUTES”).
  +           well (see ATTRIBUTES).

This can easily be removed later once we are confortable with the
asciidoctor version.

Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/asciidoctor-extensions.rb | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb
index 954acb3e7d..7561973df6 100644
--- a/Documentation/asciidoctor-extensions.rb
+++ b/Documentation/asciidoctor-extensions.rb
@@ -1,4 +1,22 @@
 require 'asciidoctor/extensions'
+require 'asciidoctor/converter/manpage'
+
+module Asciidoctor
+  class Converter::ManPageConverter
+    alias orig_convert_inline_anchor convert_inline_anchor
+    def convert_inline_anchor(node)
+      case node.type
+      when :xref
+        return node.text if node.text
+        refid = node.attributes['refid']
+        'the section called &#8220;%s&#8221;' % refid.gsub('_', ' ')
+      else
+        orig_convert_inline_anchor(node)
+      end
+    end
+    alias inline_anchor convert_inline_anchor # For old versions of asciidoctor
+  end
+end
 
 Asciidoctor::Extensions.register :git do
 
-- 
2.32.0.rc0

[PATCH v2 08/11] doc: asciidoctor: add hack to improve links

[Felipe Contreras]

The way asciidoctor handles links is very primitive compared to docbook.
Links are simply presented in the format "#{text} <#{target}>", which
may not be all that bad for the future, but pollutes the doc-diff.

By adding another modification to convert_inline_anchor() we can present
links in a form very similar to docbook, diminishing the doc-diff.

This significantly reduces the doc-diff:

From:

        abysmal performance). These safety and performance issues cannot be
        backward compatibly fixed and as such, its use is not recommended.
        Please use an alternative history filtering tool such as git
-       filter-repo[1]. If you still need to use git filter-branch, please
-       carefully read the section called “SAFETY” (and the section called
-       “PERFORMANCE”) to learn about the land mines of filter-branch, and then
-       vigilantly avoid as many of the hazards listed there as reasonably
-       possible.
+       <https://github.com/newren/git-filter-repo/> filter-repo" . If you
+       still need to use git filter-branch, please carefully read the section
+       called “SAFETY” (and the section called “PERFORMANCE”) to learn about
+       the land mines of filter-branch, and then vigilantly avoid as many of
+       the hazards listed there as reasonably possible.

-NOTES
-        1. git filter-repo
-           https://github.com/newren/git-filter-repo/
-
-        2. filter-lamely
-           https://github.com/newren/git-filter-repo/blob/master/contrib/filter-repo-demos/filter-lamely
-

To:

 NOTES
-        1. git filter-repo
+       [1]    git filter-repo
               https://github.com/newren/git-filter-repo/

Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/asciidoctor-extensions.rb | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb
index 7561973df6..914e6f64c8 100644
--- a/Documentation/asciidoctor-extensions.rb
+++ b/Documentation/asciidoctor-extensions.rb
@@ -10,6 +10,19 @@ module Asciidoctor
         return node.text if node.text
         refid = node.attributes['refid']
         'the section called &#8220;%s&#8221;' % refid.gsub('_', ' ')
+      when :link
+        return node.target if node.text == node.target
+        doc = node.document
+
+        footnote = doc.footnotes.find { |e| e.id == node.target }
+        if !footnote
+          footnote_text = "%s\n\e.RS\n\e\\%%%s\n\e.RE" % [node.text, node.target]
+          index = doc.counter('footnote-number')
+          footnote = Document::Footnote.new(index, node.target, footnote_text)
+          doc.register(:footnotes, footnote)
+        end
+
+        "\e\\fB%s\e\\fR[%d]" % [node.text, footnote.index]
       else
         orig_convert_inline_anchor(node)
       end
-- 
2.32.0.rc0

[PATCH v2 09/11] doc: asciidoctor: add support for baseurl

[Felipe Contreras]

So that we can present relative links correctly.

Reduces the doc-diff:

   NOTES
  -        1. “Understanding history: What is a branch?”
  -           file:///$HOME/share/doc/git-doc/user-manual.html#what-is-a-branch
  +       [1]    “Understanding history: What is a branch?”
  +              user-manual.html#what-is-a-branch

   NOTES
  -        1. “Understanding history: What is a branch?”
  +       [1]    “Understanding history: What is a branch?”
                 file:///$HOME/share/doc/git-doc/user-manual.html#what-is-a-branch

Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/Makefile                  | 1 +
 Documentation/asciidoctor-extensions.rb | 4 +++-
 2 files changed, 4 insertions(+), 1 deletion(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 0c654f4ec9..c28c49dd7a 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -185,6 +185,7 @@ ASCIIDOC_DOCBOOK = docbook5
 ASCIIDOC_EXTRA += -acompat-mode -atabsize=8
 ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions
 ASCIIDOC_EXTRA += -alitdd='&\#x2d;&\#x2d;'
+ASCIIDOC_EXTRA += -abaseurl='$(MAN_BASE_URL)'
 ASCIIDOC_DEPS = asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS
 DBLATEX_COMMON =
 XMLTO_EXTRA += --skip-validation
diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb
index 914e6f64c8..8856f2febd 100644
--- a/Documentation/asciidoctor-extensions.rb
+++ b/Documentation/asciidoctor-extensions.rb
@@ -16,7 +16,9 @@ module Asciidoctor
 
         footnote = doc.footnotes.find { |e| e.id == node.target }
         if !footnote
-          footnote_text = "%s\n\e.RS\n\e\\%%%s\n\e.RE" % [node.text, node.target]
+          target = node.target
+          target = doc.attributes['baseurl'] + target unless target.include? ':'
+          footnote_text = "%s\n\e.RS\n\e\\%%%s\n\e.RE" % [node.text, target]
           index = doc.counter('footnote-number')
           footnote = Document::Footnote.new(index, node.target, footnote_text)
           doc.register(:footnotes, footnote)
-- 
2.32.0.rc0

[PATCH v2 10/11] doc: asciidoctor: cleanup man page hack

[Felipe Contreras]

There's basically nothing we need from the original
orig_convert_inline_anchor(), so let's remove calls to it.

Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/asciidoctor-extensions.rb | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb
index 8856f2febd..e48a381b8f 100644
--- a/Documentation/asciidoctor-extensions.rb
+++ b/Documentation/asciidoctor-extensions.rb
@@ -3,7 +3,6 @@ require 'asciidoctor/converter/manpage'
 
 module Asciidoctor
   class Converter::ManPageConverter
-    alias orig_convert_inline_anchor convert_inline_anchor
     def convert_inline_anchor(node)
       case node.type
       when :xref
@@ -25,8 +24,10 @@ module Asciidoctor
         end
 
         "\e\\fB%s\e\\fR[%d]" % [node.text, footnote.index]
+      when :ref, :bibref
+        ''
       else
-        orig_convert_inline_anchor(node)
+        nil
       end
     end
     alias inline_anchor convert_inline_anchor # For old versions of asciidoctor
-- 
2.32.0.rc0

[PATCH v2 11/11] doc: asciidoctor: add hack for old versions

[Felipe Contreras]

\\ gets converted erroneously.

[1] https://github.com/asciidoctor/asciidoctor/issues/3456

Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/asciidoctor-extensions.rb | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)

diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb
index e48a381b8f..3ab669dad8 100644
--- a/Documentation/asciidoctor-extensions.rb
+++ b/Documentation/asciidoctor-extensions.rb
@@ -38,10 +38,19 @@ Asciidoctor::Extensions.register :git do
 
   doc = document
 
-  # Override attributes for man pages.
-  # https://github.com/asciidoctor/asciidoctor/issues/4059
   if doc.backend == 'manpage'
+    # Override attributes for man pages.
+    # https://github.com/asciidoctor/asciidoctor/issues/4059
     doc.attributes.merge!({ 'litdd' => '\--', 'plus' => '+' })
+
+    # Fix bug with \\
+    if Asciidoctor::VERSION < '2.0.11'
+      postprocessor do
+        process do |_, output|
+          output.gsub("\\(rs\\\\", "\\(rs\\(rs\\")
+        end
+      end
+    end
   end
 
   inline_macro :linkgit do
-- 
2.32.0.rc0

RE: [PATCH v2 00/11] doc: asciidoctor: direct man page creation and fixes

[Felipe Contreras]

Felipe Contreras wrote:
> This patch series enables direct man page creation with asciidoctor, but in addition tries to
> minimize the difference with asciidoc+docbook.
> 
> I fixed as many issues as I could, and now the doc-diff looks very sensible. I could not find any
> major issues, however, some minor ones still remain.
> 
> On the other hand the asciidoc method has issues as well, so it's not clear which method is superior
> at this point; both have advantages and disadvantages.
> 
> At the very least the man pages with pure asciidoctor should be quite usable now.
> 
> This series builds on top of my previous cleanups [1].

I forgot to mention what changed since v1:

 * The option USE_ASCIIDOCTOR_MANPAGE was added
 * Jeff's patch for *asciidoctor-direct optiosn to doc-diff was added
 * Martin Ågren's patch to remove -cut-footer was added
 * The format of linkgit was updated to be closer to brian's version
   (though not quite the same)
 * A few tiny cleanups

-- 
Felipe Contreras