On 2019-09-08 at 21:21:22, Jeff King wrote: > But it's not clear from that whether asciidoc's docbook5 backend inserts > an extra newline, or if it's part of the xml translation. Looking at the > actual XML, I see: > > <listitem> > <simpara>hand resolve the conflict in the working directory, and update > the index file to bring it into a state that the patch should > have produced. Then run the command with the <literal>--continue</literal> option.</simpara> > </listitem> > > which looks OK. I wondered if there should not be a break between > <listitem> and <simpara>, but it's there in the asciidoc version, too. > So I'm inclined to blame xmlto/docbook5 here. Trying again, I'm able to reproduce this. I found the cause, which is in the stylesheets. XSLT stylesheets have the ability to specify elements from which whitespace should be stripped (using the xsl:strip-space directive). In the DocBook stylesheets, listitem is specified as such an element, so the whitespace there should be stripped. However, in DocBook 5, our elements are in a namespace. Therefore, the unnamespaced stylesheets specify only "listitem", not "d:listitem", like the namespaced stylesheets do. Because this happens right after the tree has been constructed "but before it is otherwise processed by XSLT" and isn't affected by the EXSLT extension that allows re-parsing the modified tree, then we end up with the whitespace that we don't want. There are a couple ways around this. 1. We can force xmlto to use the DocBook 5 stylesheets with the "-x" flag, but we have to know where they are. Debian and Fedora have them in different places, so we'd need a knob to figure out where they are. 2. We can force xmlto to use a custom stylesheet with "-x" that merely imports the DocBook 5 stylesheets using a URL. If the user has the DocBook 5 stylesheets installed and XML catalogs configured (the default on Linux distributions), then everything will just work and the system will resolve it to the local copy. If, however, things are not properly configured, this will result in multiple network downloads for each manual page. 3. We can give up on xmlto and do things ourselves. This has the same problem as option 1, since we need to learn how to find the stylesheets. 4. We can send a patch to xmlto to make it use the proper stylesheets for DocBook 5 and hope upstream does a release and everyone upgrades shortly. Since xmlto is not at all active upstream, this seems like it may be an imprudent choice. 5. We can send a patch to the DocBook stylesheets and have them include both the namespaced and unnamespaced versions of the element names in both sets of stylesheets and hope everyone upgrades. My personal preference is #2; I think that seems like the best choice forward. XML catalogs are well understood and well configured on Linux distributions. Homebrew supports them adequately, but you have to add an environment variable to your shell configuration to enable them. Of course, if you're doing _anything_ with XML, you'll have them enabled. -- brian m. carlson: Houston, Texas, US OpenPGP: https://keybase.io/bk2204
Attachment:
signature.asc
Description: PGP signature
