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

2017-01-24 Thread Øyvind A . Holm 
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:
> > 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:
> >
> > [...]
> >
> >   $ 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  - N 60.37604° E 5.9° |-+
| OpenPGP: 0xFB0CBEE894A506E5 - http://www.sunbase.org/pubkey.asc |
| Fingerprint: A006 05D6 E676 B319 55E2  E77E FB0C BEE8 94A5 06E5 |
+| 1698e7f6-e257-11e6-bfa0-db5caa6d21d3 |-+


signature.asc
Description: PGP signature

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

2017-01-22 Thread brian m. carlson 
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:
> > 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


signature.asc
Description: PGP signature

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

2017-01-22 Thread Øyvind A . Holm 
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  - N 60.37604° E 5.9° |-+
| OpenPGP: 0xFB0CBEE894A506E5 - http://www.sunbase.org/pubkey.asc |
| Fingerprint: A006 05D6 E676 B319 55E2  E77E FB0C BEE8 94A5 06E5 |
+| 60bceb4e-e116-11e6-8fac-db5caa6d21d3 |-+


signature.asc
Description: PGP signature

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

2017-01-21 Thread brian m. carlson 
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 
---
 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 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