[PATCH v2 0/7] Macros for Asciidoctor support

STALE3475d

20 messages, 5 authors, 2017-01-26 · open the first message on its own page

[PATCH v2 0/7] Macros for Asciidoctor support

From: brian m. carlson <hidden>
Date: 2017-01-22 02:42:17

There are two major processors of AsciiDoc: AsciiDoc itself, and Asciidoctor.
Both have advantages and disadvantages, but traditionally the documentation has
been built with AsciiDoc, leading to some surprising breakage when building with
Asciidoctor.  Partially, this is due to the need to specify a significant number
of macros on the command line when building with Asciidoctor.

This series cleans up some issues building the documentation with Asciidoctor
and provides two knobs, USE_ASCIIDOCTOR, which controls building with
Asciidoctor, and ASCIIDOCTOR_EXTENSIONS_LAB, which controls the location of the
Asciidoctor Extensions Lab, which is necessary to expand the linkgit macro.

The need for the extensions could be replaced with a small amount of Ruby code,
if that's considered desirable.  Previous opinions on doing so were negative,
however.

In the process, I found several issues with cat-texi.perl, which have been
fixed.  It has also been modernized to use strict, warnings, and lexical file
handles.  I also made an attempt to produce more diffable texi files; I may
follow up with additional series along this line to make the documentation build
reproducibly.

Changes from v1:
* Fix a brown-paper-bag bug.

brian m. carlson (7):
  Documentation: fix warning in cat-texi.perl
  Documentation: modernize cat-texi.perl
  Documentation: remove unneeded argument in cat-texi.perl
  Documentation: sort sources for gitman.texi
  Documentation: add XSLT to fix DocBook for Texinfo
  Documentation: move dblatex arguments into variable
  Makefile: add a knob to enable the use of Asciidoctor

 Documentation/Makefile      | 22 ++++++++++++++++++----
 Documentation/cat-texi.perl | 21 ++++++++++++---------
 Documentation/texi.xsl      | 26 ++++++++++++++++++++++++++
 Makefile                    |  6 ++++++
 4 files changed, 62 insertions(+), 13 deletions(-)
 create mode 100644 Documentation/texi.xsl

[PATCH v2 1/7] Documentation: fix warning in cat-texi.perl

From: brian m. carlson <hidden>
Date: 2017-01-22 02:42:13

Newer versions of Perl produce the warning "Unescaped left brace in
regex is deprecated, passed through in regex" when an unescaped left
brace occurs in a regex.  Escape the brace to avoid this warning.

Signed-off-by: brian m. carlson <redacted>
---
 Documentation/cat-texi.perl | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/cat-texi.perl b/Documentation/cat-texi.perl
index 87437f8a9..b1fe52e8b 100755
--- a/Documentation/cat-texi.perl
+++ b/Documentation/cat-texi.perl

@@ -11,7 +11,7 @@ while (<STDIN>) {
 	if (s/^\@top (.*)/\@node $1,,,Top/) {
 		push @menu, $1;
 	}
-	s/\(\@pxref{\[(URLS|REMOTES)\]}\)//;
+	s/\(\@pxref\{\[(URLS|REMOTES)\]}\)//;
 	s/\@anchor\{[^{}]*\}//g;
 	print TMP;
 }

[PATCH v2 4/7] Documentation: sort sources for gitman.texi

From: brian m. carlson <hidden>
Date: 2017-01-22 02:42:20

Sorting the sources makes it easier to compare the output using diff.
In addition, it aids groups creating reproducible builds, as the order
of the files is no longer dependent on the file system or other
irrelevant factors.

Signed-off-by: brian m. carlson <redacted>
---
 Documentation/Makefile | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index a9fb497b8..6e6c82409 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile

@@ -373,7 +373,7 @@ user-manual.pdf: user-manual.xml
 
 gitman.texi: $(MAN_XML) cat-texi.perl
 	$(QUIET_DB2TEXI)$(RM) $@+ $@ && \
-	($(foreach xml,$(MAN_XML),$(DOCBOOK2X_TEXI) --encoding=UTF-8 \
+	($(foreach xml,$(sort $(MAN_XML)),$(DOCBOOK2X_TEXI) --encoding=UTF-8 \
 		--to-stdout $(xml) &&) true) > $@++ && \
 	$(PERL_PATH) cat-texi.perl $@ <$@++ >$@+ && \
 	rm $@++ && \

[PATCH v2 3/7] Documentation: remove unneeded argument in cat-texi.perl

From: brian m. carlson <hidden>
Date: 2017-01-22 02:42:25

The newly-added use of the warnings pragma exposes that the $menu[0]
argument to printf has long been silently ignored, since there is no
format specifier for it.  It doesn't appear that the argument is
actually needed, either: there is no reason to insert the name of one
particular documentation page anywhere in the header that's being
generated.

Remove the unused argument, and since the format specification
functionality is no longer needed, convert the printf to a simple print.

Signed-off-by: brian m. carlson <redacted>
---
 Documentation/cat-texi.perl | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/cat-texi.perl b/Documentation/cat-texi.perl
index 1bc84d3c7..14d2f8341 100755
--- a/Documentation/cat-texi.perl
+++ b/Documentation/cat-texi.perl

@@ -20,7 +20,7 @@ while (<STDIN>) {
 }
 close $tmp;
 
-printf '\input texinfo
+print '\input texinfo
 @setfilename gitman.info
 @documentencoding UTF-8
 @dircategory Development

@@ -31,7 +31,7 @@ printf '\input texinfo
 @top Git Manual Pages
 @documentlanguage en
 @menu
-', $menu[0];
+';
 
 for (@menu) {
 	print "* ${_}::\n";

[PATCH v2 2/7] Documentation: modernize cat-texi.perl

From: brian m. carlson <hidden>
Date: 2017-01-22 02:42:26

Good style for Perl includes using the strict and warnings pragmas, and
preferring lexical file handles over bareword file handles.  Using
lexical file handles necessitates being explicit when $_ is printed, so
that Perl does not get confused and instead print the glob ref.

The benefit of this modernization is that a formerly obscured bug is now
visible, which will be fixed in a followup patch.

Signed-off-by: brian m. carlson <redacted>
---
 Documentation/cat-texi.perl | 15 +++++++++------
 1 file changed, 9 insertions(+), 6 deletions(-)

diff --git a/Documentation/cat-texi.perl b/Documentation/cat-texi.perl
index b1fe52e8b..1bc84d3c7 100755
--- a/Documentation/cat-texi.perl
+++ b/Documentation/cat-texi.perl

@@ -1,9 +1,12 @@
 #!/usr/bin/perl -w
 
+use strict;
+use warnings;
+
 my @menu = ();
 my $output = $ARGV[0];
 
-open TMP, '>', "$output.tmp";
+open my $tmp, '>', "$output.tmp";
 
 while (<STDIN>) {
 	next if (/^\\input texinfo/../\@node Top/);

@@ -13,9 +16,9 @@ while (<STDIN>) {
 	}
 	s/\(\@pxref\{\[(URLS|REMOTES)\]}\)//;
 	s/\@anchor\{[^{}]*\}//g;
-	print TMP;
+	print $tmp $_;
 }
-close TMP;
+close $tmp;
 
 printf '\input texinfo
 @setfilename gitman.info

@@ -34,10 +37,10 @@ for (@menu) {
 	print "* ${_}::\n";
 }
 print "\@end menu\n";
-open TMP, '<', "$output.tmp";
-while (<TMP>) {
+open $tmp, '<', "$output.tmp";
+while (<$tmp>) {
 	print;
 }
-close TMP;
+close $tmp;
 print "\@bye\n";
 unlink "$output.tmp";

[PATCH v2 6/7] Documentation: move dblatex arguments into variable

From: brian m. carlson <hidden>
Date: 2017-01-22 02:42:29

Our dblatex invocation uses several style components from the AsciiDoc
distribution, but those components are not available when building with
Asciidoctor.  Move the command line arguments into a variable so it can
be overridden by the user or makefile configuration options.

Signed-off-by: brian m. carlson <redacted>
---
 Documentation/Makefile | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 76be7017c..d95002e62 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile

@@ -120,6 +120,7 @@ INSTALL_INFO = install-info
 DOCBOOK2X_TEXI = docbook2x-texi
 DBLATEX = dblatex
 ASCIIDOC_DBLATEX_DIR = /etc/asciidoc/dblatex
+DBLATEX_COMMON = -p $(ASCIIDOC_DBLATEX_DIR)/asciidoc-dblatex.xsl -s $(ASCIIDOC_DBLATEX_DIR)/asciidoc-dblatex.sty
 ifndef PERL_PATH
 	PERL_PATH = /usr/bin/perl
 endif

@@ -368,7 +369,7 @@ user-manual.texi: user-manual.xml
 
 user-manual.pdf: user-manual.xml
 	$(QUIET_DBLATEX)$(RM) $@+ $@ && \
-	$(DBLATEX) -o $@+ -p $(ASCIIDOC_DBLATEX_DIR)/asciidoc-dblatex.xsl -s $(ASCIIDOC_DBLATEX_DIR)/asciidoc-dblatex.sty $< && \
+	$(DBLATEX) -o $@+ $(DBLATEX_COMMON) $< && \
 	mv $@+ $@
 
 gitman.texi: $(MAN_XML) cat-texi.perl texi.xsl

[PATCH v2 7/7] Makefile: add a knob to enable the use of Asciidoctor

From: brian m. carlson <hidden>
Date: 2017-01-22 02:42:30

While Git has traditionally built its documentation using AsciiDoc, some
people wish to use Asciidoctor for speed or other reasons.  Add a
Makefile knob, USE_ASCIIDOCTOR, that sets various options in order to
produce acceptable output.  For HTML output, XHTML5 was chosen, since
the AsciiDoc options also produce XHTML, albeit XHTML 1.1.

Asciidoctor does not have built-in support for the linkgit macro, but it
is available using the Asciidoctor Extensions Lab.  Add a macro to
enable the use of this extension if it is available.  Without it, the
linkgit macros are emitted into the output.

Signed-off-by: brian m. carlson <redacted>
---
 Documentation/Makefile | 12 ++++++++++++
 Makefile               |  6 ++++++
 2 files changed, 18 insertions(+)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index d95002e62..19c42eb60 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile

@@ -174,6 +174,18 @@ ifdef GNU_ROFF
 XMLTO_EXTRA += -m manpage-quote-apos.xsl
 endif
 
+ifdef USE_ASCIIDOCTOR
+ASCIIDOC = asciidoctor
+ASCIIDOC_CONF =
+ASCIIDOC_HTML = xhtml5
+ASCIIDOC_DOCBOOK = docbook45
+ifdef ASCIIDOCTOR_EXTENSIONS_LAB
+ASCIIDOC_EXTRA = -I$(ASCIIDOCTOR_EXTENSIONS_LAB) -rasciidoctor/extensions -rman-inline-macro
+endif
+ASCIIDOC_EXTRA += -alitdd='&\#x2d;&\#x2d;'
+DBLATEX_COMMON =
+endif
+
 SHELL_PATH ?= $(SHELL)
 # Shell quote;
 SHELL_PATH_SQ = $(subst ','\'',$(SHELL_PATH))

diff --git a/Makefile b/Makefile
index 27afd0f37..7ed9d4d4b 100644
--- a/Makefile
+++ b/Makefile

@@ -250,6 +250,12 @@ all::
 # 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.
+#
+# Define ASCIIDOCTOR_EXTENSIONS_LAB to point to the location of the Asciidoctor
+# Extensions Lab if you have it available.
+#
 # Define PERL_PATH to the path of your Perl binary (usually /usr/bin/perl).
 #
 # Define NO_PERL_MAKEMAKER if you cannot use Makefiles generated by perl's

Re: [PATCH v2 7/7] Makefile: add a knob to enable the use of Asciidoctor

From: Øyvind A. Holm <hidden>
Date: 2017-01-23 02:57:20

On 2017-01-22 02:41:56, brian m. carlson wrote:

While Git has traditionally built its documentation using AsciiDoc, some
people wish to use Asciidoctor for speed or other reasons.  Add a
Makefile knob, USE_ASCIIDOCTOR, that sets various options in order to
produce acceptable output.  For HTML output, XHTML5 was chosen, since
the AsciiDoc options also produce XHTML, albeit XHTML 1.1.

I applied and tested the patches on the current master, commit 
787f75f0567a ("Sixth batch for 2.12"), and "make doc" with 
USE_ASCIIDOCTOR fails:

  $ git clean -fxd && make doc USE_ASCIIDOCTOR=1
  Removing Documentation/cmd-list.made
  Removing Documentation/cmds-ancillaryinterrogators.txt
  Removing Documentation/cmds-ancillarymanipulators.txt
  Removing Documentation/cmds-foreignscminterface.txt
  Removing Documentation/cmds-mainporcelain.txt
  Removing Documentation/cmds-plumbinginterrogators.txt
  Removing Documentation/cmds-plumbingmanipulators.txt
  Removing Documentation/cmds-purehelpers.txt
  Removing Documentation/cmds-synchelpers.txt
  Removing Documentation/cmds-synchingrepositories.txt
  Removing Documentation/doc.dep
  Removing Documentation/mergetools-diff.txt
  Removing Documentation/mergetools-list.made
  Removing Documentation/mergetools-merge.txt
  Removing GIT-VERSION-FILE
  GIT_VERSION = 2.11.0.460.g218feb5a0e89
  make -C Documentation all
  make[1]: Entering directory '/home/sunny/src/git/src-other/devel/git/git/Documentation'
      GEN mergetools-list.made
      GEN cmd-list.made
      GEN doc.dep
  make[2]: Entering directory '/home/sunny/src/git/src-other/devel/git/git'
  make[2]: 'GIT-VERSION-FILE' is up to date.
  make[2]: Leaving directory '/home/sunny/src/git/src-other/devel/git/git'
  make[2]: Entering directory '/home/sunny/src/git/src-other/devel/git/git'
  make[2]: 'GIT-VERSION-FILE' is up to date.
  make[2]: Leaving directory '/home/sunny/src/git/src-other/devel/git/git'
      ASCIIDOC git-init-db.html
  Couldn't find a view in @views for document
    Use --trace for backtrace
  Makefile:330: recipe for target 'git-init-db.html' failed
  make[1]: *** [git-init-db.html] Error 1
  make[1]: Leaving directory '/home/sunny/src/git/src-other/devel/git/git/Documentation'
  Makefile:2091: recipe for target 'doc' failed
  make: *** [doc] Error 2
  2017-01-23 03:50:05 sunny@sunbase:~/src/git/src-other/devel/git/git (tp-bmc-asciidoctor)

  $ lsb_release -d
  Description:    Debian GNU/Linux 8.7 (jessie)

  $ asciidoctor --version
  Asciidoctor 0.1.4 [http://asciidoctor.org]

I installed Asciidoctor with a standard "apt-get install asciidoctor", 
do I need to install more packages?

The build is broken by patch #7 ("Makefile: add a knob to enable the use 
of Asciidoctor"), the other commits seems to work, though I haven't 
tested them all individually yet. Standard "make doc" works.

Regards,
Øyvind

+-| Øyvind A. Holm [off-list ref] - N 60.37604° E 5.33339° |-+
| OpenPGP: 0xFB0CBEE894A506E5 - http://www.sunbase.org/pubkey.asc |
| Fingerprint: A006 05D6 E676 B319 55E2  E77E FB0C BEE8 94A5 06E5 |
+------------| 60bceb4e-e116-11e6-8fac-db5caa6d21d3 |-------------+

Re: [PATCH v2 7/7] Makefile: add a knob to enable the use of Asciidoctor

From: brian m. carlson <hidden>
Date: 2017-01-23 04:09:30

On Mon, Jan 23, 2017 at 03:57:13AM +0100, Øyvind A. Holm wrote:

On 2017-01-22 02:41:56, brian m. carlson wrote:

quoted

While Git has traditionally built its documentation using AsciiDoc, some
people wish to use Asciidoctor for speed or other reasons.  Add a
Makefile knob, USE_ASCIIDOCTOR, that sets various options in order to
produce acceptable output.  For HTML output, XHTML5 was chosen, since
the AsciiDoc options also produce XHTML, albeit XHTML 1.1.

I applied and tested the patches on the current master, commit 
787f75f0567a ("Sixth batch for 2.12"), and "make doc" with 
USE_ASCIIDOCTOR fails:

  $ git clean -fxd && make doc USE_ASCIIDOCTOR=1
  Removing Documentation/cmd-list.made
  Removing Documentation/cmds-ancillaryinterrogators.txt
  Removing Documentation/cmds-ancillarymanipulators.txt
  Removing Documentation/cmds-foreignscminterface.txt
  Removing Documentation/cmds-mainporcelain.txt
  Removing Documentation/cmds-plumbinginterrogators.txt
  Removing Documentation/cmds-plumbingmanipulators.txt
  Removing Documentation/cmds-purehelpers.txt
  Removing Documentation/cmds-synchelpers.txt
  Removing Documentation/cmds-synchingrepositories.txt
  Removing Documentation/doc.dep
  Removing Documentation/mergetools-diff.txt
  Removing Documentation/mergetools-list.made
  Removing Documentation/mergetools-merge.txt
  Removing GIT-VERSION-FILE
  GIT_VERSION = 2.11.0.460.g218feb5a0e89
  make -C Documentation all
  make[1]: Entering directory '/home/sunny/src/git/src-other/devel/git/git/Documentation'
      GEN mergetools-list.made
      GEN cmd-list.made
      GEN doc.dep
  make[2]: Entering directory '/home/sunny/src/git/src-other/devel/git/git'
  make[2]: 'GIT-VERSION-FILE' is up to date.
  make[2]: Leaving directory '/home/sunny/src/git/src-other/devel/git/git'
  make[2]: Entering directory '/home/sunny/src/git/src-other/devel/git/git'
  make[2]: 'GIT-VERSION-FILE' is up to date.
  make[2]: Leaving directory '/home/sunny/src/git/src-other/devel/git/git'
      ASCIIDOC git-init-db.html
  Couldn't find a view in @views for document
    Use --trace for backtrace
  Makefile:330: recipe for target 'git-init-db.html' failed
  make[1]: *** [git-init-db.html] Error 1
  make[1]: Leaving directory '/home/sunny/src/git/src-other/devel/git/git/Documentation'
  Makefile:2091: recipe for target 'doc' failed
  make: *** [doc] Error 2
  2017-01-23 03:50:05 sunny@sunbase:~/src/git/src-other/devel/git/git (tp-bmc-asciidoctor)

  $ lsb_release -d
  Description:    Debian GNU/Linux 8.7 (jessie)

  $ asciidoctor --version
  Asciidoctor 0.1.4 [http://asciidoctor.org]

I installed Asciidoctor with a standard "apt-get install asciidoctor", 
do I need to install more packages?

The build is broken by patch #7 ("Makefile: add a knob to enable the use 
of Asciidoctor"), the other commits seems to work, though I haven't 
tested them all individually yet. Standard "make doc" works.

I think you need a newer version of Asciidoctor.  I fixed one or two
issues upstream in 1.5.2, I think, that made it work properly.

You could try to do the build with the "html5" target instead of
"xhtml5" and see if that works.  If so, we could switch to that instead
if we want to support older Asciidoctor versions.
-- 
brian m. carlson / brian with sandals: Houston, Texas, US
+1 832 623 2791 | https://www.crustytoothpaste.net/~bmc | My opinion only
OpenPGP: https://keybase.io/bk2204

Re: [PATCH v2 7/7] Makefile: add a knob to enable the use of Asciidoctor

From: Øyvind A. Holm <hidden>
Date: 2017-01-25 02:26:40

On 2017-01-23 04:09:17, brian m. carlson wrote:

On Mon, Jan 23, 2017 at 03:57:13AM +0100, Øyvind A. Holm wrote:

quoted

On 2017-01-22 02:41:56, brian m. carlson wrote:

quoted

While Git has traditionally built its documentation using 
AsciiDoc, some people wish to use Asciidoctor for speed or other 
reasons.  Add a Makefile knob, USE_ASCIIDOCTOR, that sets various 
options in order to produce acceptable output.  For HTML output, 
XHTML5 was chosen, since the AsciiDoc options also produce XHTML, 
albeit XHTML 1.1.

I applied and tested the patches on the current master, commit 
787f75f0567a ("Sixth batch for 2.12"), and "make doc" with 
USE_ASCIIDOCTOR fails:

[...]

  $ asciidoctor --version
  Asciidoctor 0.1.4 [http://asciidoctor.org]

I think you need a newer version of Asciidoctor.  I fixed one or two 
issues upstream in 1.5.2, I think, that made it work properly.

I've tried on Linux Mint 18 with Asciidoctor 1.5.4 now, and it works 
there, so the version is probably too old, yes.

You could try to do the build with the "html5" target instead of 
"xhtml5" and see if that works.  If so, we could switch to that 
instead if we want to support older Asciidoctor versions.

It went a little better, but after a while it died with

  $ make doc USE_ASCIIDOCTOR=1
  [Cut 249 lines]
      GEN technical/api-index.txt
      ASCIIDOC technical/api-index.html
      ASCIIDOC git-init-db.xml
  sed "s|@@MAN_BASE_URL@@|file:///home/sunny/share/doc/git-doc/|" manpage-base-url.xsl.in > manpage-base-url.xsl
      XMLTO git-init-db.1
  xmlto: /home/sunny/src/git/src-other/devel/git/git/Documentation/git-init-db.xml does not validate (status 3)
  xmlto: Fix document syntax or use --skip-validation option
  /home/sunny/src/git/src-other/devel/git/git/Documentation/git-init-db.xml:5: element article: validity error : root and DTD name do not match 'article' and 'manpage'
  Document /home/sunny/src/git/src-other/devel/git/git/Documentation/git-init-db.xml does not validate
  Makefile:343: recipe for target 'git-init-db.1' failed
  make[1]: *** [git-init-db.1] Error 13
  make[1]: Leaving directory '/home/sunny/src/git/src-other/devel/git/git/Documentation'
  Makefile:2091: recipe for target 'doc' failed
  make: *** [doc] Error 2
  $

and that's fair enough, since the generated html isn't well-formed. 
Adding --skip-validation to XMLTO_EXTRA gave a slightly different 
result:

      GEN technical/api-index.txt
      ASCIIDOC technical/api-index.html
      ASCIIDOC git-init-db.xml
  sed "s|@@MAN_BASE_URL@@|file:///home/sunny/share/doc/git-doc/|" manpage-base-url.xsl.in > manpage-base-url.xsl
      XMLTO git-init-db.1
  Note: namesp. cut : stripped namespace before processing           git-init-db(1)
  Note: namesp. cut : processing stripped document                   git-init-db(1)
  Erro:  no refentry: No refentry elements found in "git-init-db(1)  git-init-db(1)
  Makefile:343: recipe for target 'git-init-db.1' failed
  make[1]: *** [git-init-db.1] Error 1
  make[1]: Leaving directory '/home/sunny/src/git/src-other/devel/git/git/Documentation'
  Makefile:2091: recipe for target 'doc' failed
  make: *** [doc] Error 2
  $

But frankly, this probably isn't a showstopper. Even though this is the 
newest stable version of Debian, Asciidoctor 0.1.4 was released 
2013-09-05, 3y5m ago. USE_ASCIIDOCTOR isn't the default, so people can 
build the docs with asciidoc, and that works in Debian 8.7.

Regards,
Øyvind

+-| Øyvind A. Holm [off-list ref] - N 60.37604° E 5.33339° |-+
| OpenPGP: 0xFB0CBEE894A506E5 - http://www.sunbase.org/pubkey.asc |
| Fingerprint: A006 05D6 E676 B319 55E2  E77E FB0C BEE8 94A5 06E5 |
+------------| 1698e7f6-e257-11e6-bfa0-db5caa6d21d3 |-------------+

[PATCH v2 5/7] Documentation: add XSLT to fix DocBook for Texinfo

From: brian m. carlson <hidden>
Date: 2017-01-22 02:42:33

There are two ways to create a section in a reference document (i.e.,
manpage) in DocBook 4: refsection elements and refsect, refsect2, and
refsect3 elements.  Either form is acceptable as of DocBook 4.2, but
they cannot be mixed.  Prior to DocBook 4.2, only the numbered forms
were acceptable.

docbook2texi only accepts the numbered forms, and this has not generally
been a problem, since AsciiDoc produces the numbered forms.
Asciidoctor, on the other hand, uses a shared backend for DocBook 4 and
5, and uses the unnumbered refsection elements instead.

If we don't convert the unnumbered form to the numbered form,
docbook2texi omits section headings, which is undesirable.  Add an XSLT
stylesheet to transform the unnumbered forms to the numbered forms
automatically, and preprocess the DocBook XML as part of the
transformation to Texinfo format.

Note that this transformation is only necessary for Texinfo, since
docbook2texi provides its own stylesheets.  The DocBook stylesheets,
which we use for other formats, provide the full range of DocBook 4 and
5 compatibility, and don't have this issue.

Signed-off-by: brian m. carlson <redacted>
---
 Documentation/Makefile |  7 ++++---
 Documentation/texi.xsl | 26 ++++++++++++++++++++++++++
 2 files changed, 30 insertions(+), 3 deletions(-)
 create mode 100644 Documentation/texi.xsl

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 6e6c82409..76be7017c 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile

@@ -371,10 +371,11 @@ user-manual.pdf: user-manual.xml
 	$(DBLATEX) -o $@+ -p $(ASCIIDOC_DBLATEX_DIR)/asciidoc-dblatex.xsl -s $(ASCIIDOC_DBLATEX_DIR)/asciidoc-dblatex.sty $< && \
 	mv $@+ $@
 
-gitman.texi: $(MAN_XML) cat-texi.perl
+gitman.texi: $(MAN_XML) cat-texi.perl texi.xsl
 	$(QUIET_DB2TEXI)$(RM) $@+ $@ && \
-	($(foreach xml,$(sort $(MAN_XML)),$(DOCBOOK2X_TEXI) --encoding=UTF-8 \
-		--to-stdout $(xml) &&) true) > $@++ && \
+	($(foreach xml,$(sort $(MAN_XML)),xsltproc -o $(xml)+ texi.xsl $(xml) && \
+		$(DOCBOOK2X_TEXI) --encoding=UTF-8 --to-stdout $(xml)+ && \
+		rm $(xml)+ &&) true) > $@++ && \
 	$(PERL_PATH) cat-texi.perl $@ <$@++ >$@+ && \
 	rm $@++ && \
 	mv $@+ $@

diff --git a/Documentation/texi.xsl b/Documentation/texi.xsl
new file mode 100644
index 000000000..0f8ff07ec
--- /dev/null
+++ b/Documentation/texi.xsl

@@ -0,0 +1,26 @@
+<!-- texi.xsl:
+     convert refsection elements into refsect elements that docbook2texi can
+     understand -->
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+		version="1.0">
+
+<xsl:output method="xml"
+	    encoding="UTF-8"
+	    doctype-public="-//OASIS//DTD DocBook XML V4.5//EN"
+	    doctype-system="http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" />
+
+<xsl:template match="//refsection">
+	<xsl:variable name="element">refsect<xsl:value-of select="count(ancestor-or-self::refsection)" /></xsl:variable>
+	<xsl:element name="{$element}">
+		<xsl:apply-templates select="@*|node()" />
+	</xsl:element>
+</xsl:template>
+
+<!-- Copy all other nodes through. -->
+<xsl:template match="node()|@*">
+	<xsl:copy>
+		<xsl:apply-templates select="@*|node()" />
+	</xsl:copy>
+</xsl:template>
+
+</xsl:stylesheet>

Re: [PATCH v2 0/7] Macros for Asciidoctor support

From: Johannes Schindelin <hidden>
Date: 2017-01-25 13:29:34

Hi Brian,

On Sun, 22 Jan 2017, brian m. carlson wrote:

There are two major processors of AsciiDoc: AsciiDoc itself, and
Asciidoctor.  Both have advantages and disadvantages, but traditionally
the documentation has been built with AsciiDoc, leading to some
surprising breakage when building with Asciidoctor.  Partially, this is
due to the need to specify a significant number of macros on the command
line when building with Asciidoctor.

This series cleans up some issues building the documentation with
Asciidoctor and provides two knobs, USE_ASCIIDOCTOR, which controls
building with Asciidoctor, and ASCIIDOCTOR_EXTENSIONS_LAB, which
controls the location of the Asciidoctor Extensions Lab, which is
necessary to expand the linkgit macro.

I like it.

I reviewed all the patches and think they are good (except the XSLT patch,
which made me just feel incompetent because I do not know enough to have
an opinion about it).

The need for the extensions could be replaced with a small amount of
Ruby code, if that's considered desirable.  Previous opinions on doing
so were negative, however.

Quite frankly, it is annoying to be forced to install the extensions. I
would much rather have the small amount of Ruby code in Git's repository.

Thanks,
Johannes

Re: [PATCH v2 0/7] Macros for Asciidoctor support

From: Jeff King <hidden>
Date: 2017-01-25 21:35:54

On Wed, Jan 25, 2017 at 02:28:55PM +0100, Johannes Schindelin wrote:

quoted

The need for the extensions could be replaced with a small amount of
Ruby code, if that's considered desirable.  Previous opinions on doing
so were negative, however.

Quite frankly, it is annoying to be forced to install the extensions. I
would much rather have the small amount of Ruby code in Git's repository.

Me too. Dependencies can be a big annoyance. I'd reserve judgement until
I saw the actual Ruby code, though. :)

-Peff

Re: [PATCH v2 0/7] Macros for Asciidoctor support

From: brian m. carlson <hidden>
Date: 2017-01-25 23:19:37

On Wed, Jan 25, 2017 at 04:35:44PM -0500, Jeff King wrote:

On Wed, Jan 25, 2017 at 02:28:55PM +0100, Johannes Schindelin wrote:

quoted

The need for the extensions could be replaced with a small amount of
Ruby code, if that's considered desirable.  Previous opinions on doing
so were negative, however.

Quite frankly, it is annoying to be forced to install the extensions. I
would much rather have the small amount of Ruby code in Git's repository.

Me too. Dependencies can be a big annoyance. I'd reserve judgement until
I saw the actual Ruby code, though. :)

I've sent the patch before, but I can send it again.  It's relatively
small and self-contained.  I'm also happy to be responsible for
maintaining it.
-- 
brian m. carlson / brian with sandals: Houston, Texas, US
+1 832 623 2791 | https://www.crustytoothpaste.net/~bmc | My opinion only
OpenPGP: https://keybase.io/bk2204

Re: [PATCH v2 0/7] Macros for Asciidoctor support

From: Jeff King <hidden>
Date: 2017-01-25 23:30:11

On Wed, Jan 25, 2017 at 11:19:26PM +0000, brian m. carlson wrote:

On Wed, Jan 25, 2017 at 04:35:44PM -0500, Jeff King wrote:

quoted

On Wed, Jan 25, 2017 at 02:28:55PM +0100, Johannes Schindelin wrote:

quoted

The need for the extensions could be replaced with a small amount of
Ruby code, if that's considered desirable.  Previous opinions on doing
so were negative, however.

Quite frankly, it is annoying to be forced to install the extensions. I
would much rather have the small amount of Ruby code in Git's repository.

Me too. Dependencies can be a big annoyance. I'd reserve judgement until
I saw the actual Ruby code, though. :)

I've sent the patch before, but I can send it again.  It's relatively
small and self-contained.  I'm also happy to be responsible for
maintaining it.

Ah, it's:

  http://public-inbox.org/git/1413070656-241955-5-git-send-email-sandals@crustytoothpaste.net/

(and note there is some surrounding discussion there).

The code is not _too_ bad. The main thing is that it would have to be
kept up to date with changes to asciidoc.conf's version of the linkgit
macro. But it's not like that changes frequently.

-Peff

Re: [PATCH v2 0/7] Macros for Asciidoctor support

From: brian m. carlson <hidden>
Date: 2017-01-25 23:41:10

On Wed, Jan 25, 2017 at 06:30:00PM -0500, Jeff King wrote:

On Wed, Jan 25, 2017 at 11:19:26PM +0000, brian m. carlson wrote:

quoted

On Wed, Jan 25, 2017 at 04:35:44PM -0500, Jeff King wrote:

quoted

On Wed, Jan 25, 2017 at 02:28:55PM +0100, Johannes Schindelin wrote:

quoted

The need for the extensions could be replaced with a small amount of
Ruby code, if that's considered desirable.  Previous opinions on doing
so were negative, however.

Quite frankly, it is annoying to be forced to install the extensions. I
would much rather have the small amount of Ruby code in Git's repository.

Me too. Dependencies can be a big annoyance. I'd reserve judgement until
I saw the actual Ruby code, though. :)

I've sent the patch before, but I can send it again.  It's relatively
small and self-contained.  I'm also happy to be responsible for
maintaining it.

Ah, it's:

  http://public-inbox.org/git/1413070656-241955-5-git-send-email-sandals@crustytoothpaste.net/

(and note there is some surrounding discussion there).

The code is not _too_ bad. The main thing is that it would have to be
kept up to date with changes to asciidoc.conf's version of the linkgit
macro. But it's not like that changes frequently.

Yes.  I think I can actually simplify it some more, since we always seem
to use the argument to linkgit, so I'll send out a simplified patch in a
few minutes.
-- 
brian m. carlson / brian with sandals: Houston, Texas, US
+1 832 623 2791 | https://www.crustytoothpaste.net/~bmc | My opinion only
OpenPGP: https://keybase.io/bk2204

[PATCH] Documentation: implement linkgit macro for Asciidoctor

From: brian m. carlson <hidden>
Date: 2017-01-26 00:13:57

AsciiDoc uses a configuration file to implement macros like linkgit,
while Asciidoctor uses Ruby extensions.  Implement a Ruby extension that
implements the linkgit macro for Asciidoctor in the same way that
asciidoc.conf does for AsciiDoc.  Adjust the Makefile to use it by
default.

Signed-off-by: brian m. carlson <redacted>
---
 Documentation/Makefile                  |  5 +----
 Documentation/asciidoctor-extensions.rb | 28 ++++++++++++++++++++++++++++
 2 files changed, 29 insertions(+), 4 deletions(-)
 create mode 100644 Documentation/asciidoctor-extensions.rb

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 19c42eb60..d1b7a6865 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile

@@ -179,10 +179,7 @@ ASCIIDOC = asciidoctor
 ASCIIDOC_CONF =
 ASCIIDOC_HTML = xhtml5
 ASCIIDOC_DOCBOOK = docbook45
-ifdef ASCIIDOCTOR_EXTENSIONS_LAB
-ASCIIDOC_EXTRA = -I$(ASCIIDOCTOR_EXTENSIONS_LAB) -rasciidoctor/extensions -rman-inline-macro
-endif
-ASCIIDOC_EXTRA += -alitdd='&\#x2d;&\#x2d;'
+ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions -alitdd='&\#x2d;&\#x2d;'
 DBLATEX_COMMON =
 endif

diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb
new file mode 100644
index 000000000..09f7088ee
--- /dev/null
+++ b/Documentation/asciidoctor-extensions.rb

@@ -0,0 +1,28 @@
+require 'asciidoctor'
+require 'asciidoctor/extensions'
+
+module Git
+  module Documentation
+    class LinkGitProcessor < Asciidoctor::Extensions::InlineMacroProcessor
+      use_dsl
+
+      named :chrome
+
+      def process(parent, target, attrs)
+        if parent.document.basebackend? 'html'
+          prefix = parent.document.attr('git-relative-html-prefix')
+          %(<a href="#{prefix}#{target}.html">#{target}(#{attrs[1]})</a>\n)
+        elsif parent.document.basebackend? 'docbook'
+          %(<citerefentry>
+<refentrytitle>#{target}</refentrytitle><manvolnum>#{attrs[1]}</manvolnum>
+</citerefentry>
+)
+        end
+      end
+    end
+  end
+end
+
+Asciidoctor::Extensions.register do
+  inline_macro Git::Documentation::LinkGitProcessor, :linkgit
+end

-- 
2.11.0

Re: [PATCH] Documentation: implement linkgit macro for Asciidoctor

From: Jeff King <hidden>
Date: 2017-01-26 03:47:03

On Thu, Jan 26, 2017 at 12:13:44AM +0000, brian m. carlson wrote:

quoted hunk

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 19c42eb60..d1b7a6865 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile

@@ -179,10 +179,7 @@ ASCIIDOC = asciidoctor
 ASCIIDOC_CONF =
 ASCIIDOC_HTML = xhtml5
 ASCIIDOC_DOCBOOK = docbook45
-ifdef ASCIIDOCTOR_EXTENSIONS_LAB
-ASCIIDOC_EXTRA = -I$(ASCIIDOCTOR_EXTENSIONS_LAB) -rasciidoctor/extensions -rman-inline-macro
-endif
-ASCIIDOC_EXTRA += -alitdd='&\#x2d;&\#x2d;'
+ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions -alitdd='&\#x2d;&\#x2d;'

Might be more readable to just leave the litdd part on its own line.

quoted hunk

diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb
new file mode 100644
index 000000000..09f7088ee
--- /dev/null
+++ b/Documentation/asciidoctor-extensions.rb

@@ -0,0 +1,28 @@
+require 'asciidoctor'
+require 'asciidoctor/extensions'
+
+module Git
+  module Documentation
+    class LinkGitProcessor < Asciidoctor::Extensions::InlineMacroProcessor
+      use_dsl
+
+      named :chrome
+
+      def process(parent, target, attrs)
+        if parent.document.basebackend? 'html'
+          prefix = parent.document.attr('git-relative-html-prefix')
+          %(<a href="#{prefix}#{target}.html">#{target}(#{attrs[1]})</a>\n)
+        elsif parent.document.basebackend? 'docbook'
+          %(<citerefentry>
+<refentrytitle>#{target}</refentrytitle><manvolnum>#{attrs[1]}</manvolnum>
+</citerefentry>
+)
+        end
+      end
+    end
+  end
+end

I think this looks reasonable. There's some boilerplate, but even as
somebody not familiar with asciidoctor, it's all quite obvious.

The multi-line string is kind of ugly because of the indentation.
Apparently Ruby has here-docs that will eat leading whitespace, but the
syntax was not introduce until Ruby 2.3, which is probably more recent
than we should count on.

I think you could write:

          %(<citerefentry>
            <refentrytitle>#{target}</refentrytitle><manvolnum>#{attrs[1]}</manvolnum>
            </citerefentry>
	  ).gsub(/^\s*/, "")

I don't know if that's too clever or not.

But either way, I like this better than introducing an extra dependency.

-Peff

Re: [PATCH] Documentation: implement linkgit macro for Asciidoctor

From: Eric Wong <hidden>
Date: 2017-01-26 07:43:10

Jeff King [off-list ref] wrote:

On Thu, Jan 26, 2017 at 12:13:44AM +0000, brian m. carlson wrote:

quoted

+
+      def process(parent, target, attrs)
+        if parent.document.basebackend? 'html'
+          prefix = parent.document.attr('git-relative-html-prefix')
+          %(<a href="#{prefix}#{target}.html">#{target}(#{attrs[1]})</a>\n)
+        elsif parent.document.basebackend? 'docbook'
+          %(<citerefentry>
+<refentrytitle>#{target}</refentrytitle><manvolnum>#{attrs[1]}</manvolnum>
+</citerefentry>
+)

<snip>

The multi-line string is kind of ugly because of the indentation.
Apparently Ruby has here-docs that will eat leading whitespace, but the
syntax was not introduce until Ruby 2.3, which is probably more recent
than we should count on.

You can use '\' to continue long lines with any Ruby version:

    "<citerefentry>" \
      "<refentrytitle>#{target}</refentrytitle>" \
      "<manvolnum>#{attrs[1]}</manvolnum>" \
    "</citerefentry>"

The above happens during the parse phase, so there's no garbage
or method call overhead compared to the more-frequently seen '+'
or '<<' method calls to combine strings.

I think you could write:

          %(<citerefentry>
            <refentrytitle>#{target}</refentrytitle><manvolnum>#{attrs[1]}</manvolnum>
            </citerefentry>
	  ).gsub(/^\s*/, "")

I don't know if that's too clever or not.

Ick...

But either way, I like this better than introducing an extra dependency.

Agreed.

Re: [PATCH] Documentation: implement linkgit macro for Asciidoctor

From: Johannes Schindelin <hidden>
Date: 2017-01-26 11:50:34

Hi Brian,

On Thu, 26 Jan 2017, brian m. carlson wrote:

AsciiDoc uses a configuration file to implement macros like linkgit,
while Asciidoctor uses Ruby extensions.  Implement a Ruby extension that
implements the linkgit macro for Asciidoctor in the same way that
asciidoc.conf does for AsciiDoc.  Adjust the Makefile to use it by
default.

I like it.

Thank you,
Johannes

`h`	back out one level
`j`	next message in thread
`k`	previous message in thread
`l`	drill in
`Esc`	close help / fold thread tree
`?`	toggle this help