git@vger.kernel.org mailing list mirror (one of many)
 help / color / mirror / code / Atom feed
From: "Martin Ågren" <martin.agren@gmail.com>
To: git@vger.kernel.org
Cc: "Todd Zullinger" <tmz@pobox.com>, "Jeff King" <peff@peff.net>,
	"SZEDER Gábor" <szeder.dev@gmail.com>,
	"brian m. carlson" <sandals@crustytoothpaste.net>,
	"Junio C Hamano" <gitster@pobox.com>
Subject: [PATCH v2 1/2] asciidoctor-extensions: provide `<refmiscinfo/>`
Date: Tue,  3 Sep 2019 20:51:20 +0200	[thread overview]
Message-ID: <7545b16bd845580548dee380a54891ed1f75290f.1567534373.git.martin.agren@gmail.com> (raw)
In-Reply-To: <cover.1567534373.git.martin.agren@gmail.com>

When we build with AsciiDoc, asciidoc.conf ensures that each xml-file we
generate contains some meta-information which `xmlto` can act on, based
on the following template:

  <refmeta>
  <refentrytitle>{mantitle}</refentrytitle>
  <manvolnum>{manvolnum}</manvolnum>
  <refmiscinfo class="source">Git</refmiscinfo>
  <refmiscinfo class="version">{git_version}</refmiscinfo>
  <refmiscinfo class="manual">Git Manual</refmiscinfo>
  </refmeta>

When we build with Asciidoctor, it does not honor this configuration file
and we end up with only this (for a hypothetical git-foo.xml):

  <refmeta>
  <refentrytitle>git-foo</refentrytitle>
  <manvolnum>1</manvolnum>
  </refmeta>

That is, we miss out on the `<refmiscinfo/>` tags. As a result, the
header of each man page doesn't say "Git Manual", but "git-foo(1)"
instead. Worse, the footers don't give the Git version number and
instead provide the fairly ugly "[FIXME: source]".

That Asciidoctor ignores asciidoc.conf is nothing new. This is why we
implement the `linkgit:` macro in asciidoc.conf *and* in
asciidoctor-extensions.rb. Follow suit and provide these tags in
asciidoctor-extensions.rb, using a "postprocessor" extension where we
just search and replace in the XML, treated as text.

We may consider a few alternatives:

  * Provide the `mansource` attribute to Asciidoctor. This attribute
    is only respected (i.e., turned into those <refmiscinfo/> tags) with
    1) the "manpage" doctype and/or converter [1], which we currently do
    not use, or 2) using Asciidoctor 1.5.7 or newer [2].

  * We could inject these lines into the xml-files from the *Makefile*,
    e.g., using `sed`. That would reduce repetition, but it feels wrong
    to impose another step and another risk on the AsciiDoc-processing
    only to benefit the Asciidoctor-one.

  * I tried providing a "docinfo processor" to inject these tags, but
    could not figure out how to "merge" the two <refmeta/> sections that
    resulted. To avoid xmlto barfing on the result, I needed need to use
    `xmlto --skip-validation ...`, which seems unfortunate.

Let's instead inject the missing tags using a postprocessor. We'll make
it fairly obvious that we aim to inject the exact same three lines of
`<refmiscinfo/>` that asciidoc.conf provides. We inject them in
*post*-processing so we need to do the variable expansion ourselves. We
do introduce the bug that asciidoc.conf already has in that we won't do
any escaping, e.g., of funky versions like "some v <2.25, >2.20".

The postprocessor we add here works on the XML as raw text and doesn't
really use the full potential of XML to do a more structured injection.
This is actually precisely what the Asciidoctor User Manual does in its
postprocessor example [3]. I looked into two other approaches:

  1. The nokogiri library is apparently the "modern" way of doing XML
     in ruby. I got it working fairly easily:
        require 'nokogiri'
        doc = Nokogiri::XML(output)
        doc.search("refmeta").each { |n| n.add_child(new_tags) }
        output = doc.to_xml
     However, this adds another dependency (e.g., the "ruby-nokogiri"
     package on Ubuntu). Using Asciidoctor is not our default, but it
     will probably need to become so soon (AsciiDoc relies on Python 2,
     which is going away). Let's avoid adding a dependency just so that
     we can say "search...add_child" rather than "sub(regex...)".

  2. The older REXML is apparently always(?) bundled with ruby, but I
     couldn't even parse the original document:
        require 'rexml/document'
        doc = REXML::Document.new(output)
        ...
     The error was "no implicit conversion of nil into String" and I
     stopped there.

Having never dabbled with ruby outside of this very file, I might be
missing something obvious, but I don't think it's unlikely that doing a
plain old search-and-replace will work just as fine or better compared
to parsing XML and worrying about libraries and library versions.

[1] https://asciidoctor.org/docs/user-manual/#builtin-attributes
[2] https://public-inbox.org/git/20190319074321.GA2189@sigill.intra.peff.net/
[3] https://asciidoctor.org/docs/user-manual/#postprocessor-example

Signed-off-by: Martin Ågren <martin.agren@gmail.com>
---
 Documentation/asciidoctor-extensions.rb | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb
index 0089e0cfb8..4ae130d2c6 100644
--- a/Documentation/asciidoctor-extensions.rb
+++ b/Documentation/asciidoctor-extensions.rb
@@ -20,9 +20,24 @@ module Git
         end
       end
     end
+
+    class DocumentPostProcessor < Asciidoctor::Extensions::Postprocessor
+      def process document, output
+        if document.basebackend? 'docbook'
+          git_version = document.attributes['git_version']
+          new_tags = "" \
+            "<refmiscinfo class=\"source\">Git</refmiscinfo>\n" \
+            "<refmiscinfo class=\"version\">#{git_version}</refmiscinfo>\n" \
+            "<refmiscinfo class=\"manual\">Git Manual</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.23.0


  reply	other threads:[~2019-09-03 18:51 UTC|newest]

Thread overview: 71+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2019-03-17 14:47 [PATCH] asciidoctor-extensions: provide `<refmiscinfo/>` Martin Ågren
2019-03-17 19:44 ` Todd Zullinger
2019-03-17 20:03   ` Martin Ågren
2019-03-19  7:02   ` Martin Ågren
2019-03-20 18:17     ` Todd Zullinger
2019-03-22 21:01       ` Martin Ågren
2019-03-23 19:27         ` Todd Zullinger
2019-03-24 12:16           ` Jeff King
2019-03-24 16:21             ` Todd Zullinger
2019-03-25 15:06               ` Jeff King
2019-03-25 19:00                 ` Todd Zullinger
2019-03-27  1:06                   ` Todd Zullinger
2019-03-27 10:05                     ` SZEDER Gábor
2019-03-28  0:06                     ` brian m. carlson
2019-03-30 18:00                       ` Todd Zullinger
2019-03-30 21:04                         ` brian m. carlson
2019-04-05  2:17                           ` Todd Zullinger
2019-04-05 18:46                             ` Jeff King
2019-03-28  2:54                     ` Jeff King
2019-03-28  3:33                       ` Jeff King
2019-03-19  2:46 ` Jeff King
2019-03-19  2:59   ` Jeff King
2019-03-19  3:55     ` Junio C Hamano
2019-03-19  7:33       ` Martin Ågren
2019-03-19  7:36         ` Martin Ågren
2019-09-03 18:51           ` [PATCH v2 0/2] " Martin Ågren
2019-09-03 18:51             ` Martin Ågren [this message]
2019-09-03 18:51             ` [PATCH v2 2/2] doc-diff: replace --cut-header-footer with --cut-footer Martin Ågren
2019-09-03 23:16             ` [PATCH v2 0/2] asciidoctor-extensions: provide `<refmiscinfo/>` brian m. carlson
2019-09-05 19:28               ` Martin Ågren
2019-09-04  3:26             ` Jeff King
2019-09-05 19:35               ` Martin Ågren
2019-09-07  6:45                 ` Jeff King
2019-09-07 14:06                   ` Martin Ågren
2019-09-08 21:30                     ` Jeff King
2019-09-06 23:29               ` brian m. carlson
2019-09-07  4:40                 ` Jeff King
2019-09-07 16:53                   ` brian m. carlson
2019-09-07 17:07                 ` [PATCH] Documentation: fix build with Asciidoctor 2 brian m. carlson
2019-09-08 10:48                   ` Jeff King
2019-09-08 17:18                     ` brian m. carlson
2019-09-08 21:21                       ` Jeff King
2019-09-08 22:24                         ` brian m. carlson
2019-09-09 17:37                           ` Junio C Hamano
2019-09-10 18:44                           ` Jeff King
2019-09-11 23:19                             ` brian m. carlson
2019-09-08 14:13                   ` SZEDER Gábor
2019-09-08 21:32                     ` Jeff King
2019-09-13  1:52                 ` [PATCH v2] " brian m. carlson
2019-09-13  5:06                   ` Jeff King
2019-09-13 17:06                     ` Junio C Hamano
2019-09-16 10:47                     ` Martin Ågren
2019-09-16 17:43                       ` Junio C Hamano
2019-09-14  7:53                   ` SZEDER Gábor
2019-09-14 19:44                     ` brian m. carlson
2019-09-14 19:49                 ` [PATCH v3] " brian m. carlson
2019-09-15  9:59                   ` SZEDER Gábor
2019-09-15 21:26                     ` brian m. carlson
2019-09-15 22:05                       ` SZEDER Gábor
2019-09-15 22:14                         ` brian m. carlson
2019-09-16 10:51                       ` Martin Ågren
2019-09-15 22:43                 ` [PATCH v4] " brian m. carlson
2019-09-16 19:00             ` [PATCH v3 0/3] asciidoctor-extensions: provide `<refmiscinfo/>` Martin Ågren
2019-09-16 19:00               ` [PATCH v3 1/3] Doc/Makefile: give mansource/-version/-manual attributes Martin Ågren
2019-09-16 19:00               ` [PATCH v3 2/3] asciidoctor-extensions: provide `<refmiscinfo/>` Martin Ågren
2019-09-16 19:00               ` [PATCH v3 3/3] doc-diff: replace --cut-header-footer with --cut-footer Martin Ågren
2019-03-19  3:30   ` [PATCH] asciidoctor-extensions: provide `<refmiscinfo/>` Jeff King
2019-03-19  7:12     ` Martin Ågren
2019-03-19  7:43       ` Jeff King
2019-03-20 18:32         ` Todd Zullinger
2019-03-19  7:10   ` Martin Ågren

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: http://vger.kernel.org/majordomo-info.html

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=7545b16bd845580548dee380a54891ed1f75290f.1567534373.git.martin.agren@gmail.com \
    --to=martin.agren@gmail.com \
    --cc=git@vger.kernel.org \
    --cc=gitster@pobox.com \
    --cc=peff@peff.net \
    --cc=sandals@crustytoothpaste.net \
    --cc=szeder.dev@gmail.com \
    --cc=tmz@pobox.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public 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).