| Message ID | cover.1567534373.git.martin.agren@gmail.com (mailing list archive) |
|---|---|
| Headers | show |
| Series | asciidoctor-extensions: provide `<refmiscinfo/>` | expand |
On 2019-09-03 at 18:51:19, Martin Ågren wrote: > Almost half a year ago, I wrote: > > To be clear. *This* patch has a sufficiently incorrect commit message > > that it really needs a makeover. You can expect a v2. > > Finally, here's that v2. I should probably refresh memories: The goal of > the main patch here is to make the headers and footers of our manpages > built by Asciidoctor look a lot more like those generated by AsciiDoc. > In particular, this gets rid of the ugly "[FIXME: source]". > > I spent a little bit of time trying to work on the XML as XML, and > quite a lot of time procrastinating on that. In the end, I decided that > the outcome of my attempts wouldn't get better and that there is some > value to the stupid approach from v1 of doing a simple search-and-replace > in the text. I've preserved my attempts in the commit message. > > When I posted v1, it turned into quite a thread [1] on AsciiDoc vs > Asciidoctor vs Asciidoctor 2.0 and differences in rendering. (I am on > Asciidoctor 1.5.5.) > > Among other things, the v1-thread discussed switching the rendering > toolchain entirely to avoid the detour over xmlto. Doing that would > render this patch obsolete. While I agree that such a switch is the > correct long-term goal and that we can be fairly aggressive about it, I > do also think it makes sense to first make the "softer" switch to > Asciidoctor-by-default and get that particular hurdle behind us. Then, > once we're ok with dropping AsciiDoc entirely, we can do the switch to > an Asciidoctor-only toolchain. Yeah, this seems like a good approach. xmlto is a neat tool, but it's essentially unmaintained and is designed for DocBook 4. Avoiding it where possible seems like the right choice. I looked at this series and it seems sane. I agree that adding a dependency on nokogiri isn't really desirable. It is an extremely common Ruby package, but it has native extensions, which causes problems for some people if their distro doesn't support it.
On Tue, Sep 03, 2019 at 08:51:19PM +0200, Martin Ågren wrote: > Almost half a year ago, I wrote: > > To be clear. *This* patch has a sufficiently incorrect commit message > > that it really needs a makeover. You can expect a v2. > > Finally, here's that v2. I should probably refresh memories: The goal of > the main patch here is to make the headers and footers of our manpages > built by Asciidoctor look a lot more like those generated by AsciiDoc. > In particular, this gets rid of the ugly "[FIXME: source]". Thanks for resuming this work. The patches both look good to me. > I spent a little bit of time trying to work on the XML as XML, and > quite a lot of time procrastinating on that. In the end, I decided that > the outcome of my attempts wouldn't get better and that there is some > value to the stupid approach from v1 of doing a simple search-and-replace > in the text. I've preserved my attempts in the commit message. I think your hack is better than introducing yet another dependency. And because it's isolated and you've documented it well, it will be easy to undo later if we choose. The doc-diff tool should tell us if we catch any false positives inside the text (though it seems quite unlikely to me). > When I posted v1, it turned into quite a thread [1] on AsciiDoc vs > Asciidoctor vs Asciidoctor 2.0 and differences in rendering. (I am on > Asciidoctor 1.5.5.) Yes, sadly I still can't format the docs at all with 2.0.10 (which is what ships in Debian unstable). > Among other things, the v1-thread discussed switching the rendering > toolchain entirely to avoid the detour over xmlto. Doing that would > render this patch obsolete. While I agree that such a switch is the > correct long-term goal and that we can be fairly aggressive about it, I > do also think it makes sense to first make the "softer" switch to > Asciidoctor-by-default and get that particular hurdle behind us. Then, > once we're ok with dropping AsciiDoc entirely, we can do the switch to > an Asciidoctor-only toolchain. Yeah, I do still like that as an endgame, but I like what you have here as an intermediate step in the right direction. > (I'm preparing a second, independent series of patches that should halve > the difference (sans headers/footers) between these two engines -- at > least the versions of them that I'm using. The remaining differences are > then mainly, but not exclusively, in favor of Asciidoctor. That series > should appear on the list within the next couple of days. After that, > there's user-manual.html/pdf that needs looking into...) Yay. :) -Peff
On Wed, 4 Sep 2019 at 01:16, brian m. carlson <sandals@crustytoothpaste.net> wrote: > > I looked at this series and it seems sane. I agree that adding a > dependency on nokogiri isn't really desirable. It is an extremely > common Ruby package, but it has native extensions, which causes problems > for some people if their distro doesn't support it. Ok, nice to know I wasn't too far off with avoiding the added dependency. I saw statements like "oh, it's available everywhere", but also more nuanced ones like "not necessarily...". I'm glad I have a trustworthy source now. ;-) Martin
On Wed, 4 Sep 2019 at 05:26, Jeff King <peff@peff.net> wrote: > > On Tue, Sep 03, 2019 at 08:51:19PM +0200, Martin Ågren wrote: > > > When I posted v1, it turned into quite a thread [1] on AsciiDoc vs > > Asciidoctor vs Asciidoctor 2.0 and differences in rendering. (I am on > > Asciidoctor 1.5.5.) > > Yes, sadly I still can't format the docs at all with 2.0.10 (which is > what ships in Debian unstable). > > > do also think it makes sense to first make the "softer" switch to > > Asciidoctor-by-default and get that particular hurdle behind us. Then, > > once we're ok with dropping AsciiDoc entirely, we can do the switch to > > an Asciidoctor-only toolchain. > > Yeah, I do still like that as an endgame, but I like what you have here > as an intermediate step in the right direction. Hmm, so this sounds like once I am happy with replacing AsciiDoc with Asciidoctor 1(.5.5), I should rather not propose a series "let's default to Asciidoctor!!!" but instead a slightly more careful "go with Asciidoctor, but document that we work badly with v2 and that the 2nd choice after Asciidoctor 1 should be AsciiDoc". Or do you see it differently? (I wonder which Asciidoctor-version Junio would be on..) Martin
On 2019-09-04 at 03:26:10, Jeff King wrote: > On Tue, Sep 03, 2019 at 08:51:19PM +0200, Martin Ågren wrote: > > When I posted v1, it turned into quite a thread [1] on AsciiDoc vs > > Asciidoctor vs Asciidoctor 2.0 and differences in rendering. (I am on > > Asciidoctor 1.5.5.) > > Yes, sadly I still can't format the docs at all with 2.0.10 (which is > what ships in Debian unstable). I'll look into this. I requested the upgrade in sid. If it's the lack of DocBook 4.5 support, then I'll probably need to patch xmlto for that. DocBook 5 has been around for a decade now, so it's time for xmlto to support it properly.
On Fri, Sep 06, 2019 at 11:29:47PM +0000, brian m. carlson wrote: > On 2019-09-04 at 03:26:10, Jeff King wrote: > > On Tue, Sep 03, 2019 at 08:51:19PM +0200, Martin Ågren wrote: > > > When I posted v1, it turned into quite a thread [1] on AsciiDoc vs > > > Asciidoctor vs Asciidoctor 2.0 and differences in rendering. (I am on > > > Asciidoctor 1.5.5.) > > > > Yes, sadly I still can't format the docs at all with 2.0.10 (which is > > what ships in Debian unstable). > > I'll look into this. I requested the upgrade in sid. > > If it's the lack of DocBook 4.5 support, then I'll probably need to > patch xmlto for that. DocBook 5 has been around for a decade now, so > it's time for xmlto to support it properly. Yes, it's the docbook45 thing. Switching to docbook5 lets asciidoc run, but then xmlto chokes. -Peff
On Thu, Sep 05, 2019 at 09:35:10PM +0200, Martin Ågren wrote: > > > do also think it makes sense to first make the "softer" switch to > > > Asciidoctor-by-default and get that particular hurdle behind us. Then, > > > once we're ok with dropping AsciiDoc entirely, we can do the switch to > > > an Asciidoctor-only toolchain. > > > > Yeah, I do still like that as an endgame, but I like what you have here > > as an intermediate step in the right direction. > > Hmm, so this sounds like once I am happy with replacing AsciiDoc with > Asciidoctor 1(.5.5), I should rather not propose a series "let's default > to Asciidoctor!!!" but instead a slightly more careful "go with > Asciidoctor, but document that we work badly with v2 and that the 2nd > choice after Asciidoctor 1 should be AsciiDoc". Or do you see it > differently? (I wonder which Asciidoctor-version Junio would be on..) Yeah, that seems reasonable. TBH, if making things in the middle step work turns out to be too hard, I'm not entirely opposed to a hard switch. The "does not work with 2.0" thing has to be a temporary step, though, I think, since using the older versions will get harder and harder as time goes on. I think it's OK to take such a temporary step as long as we understand where it leads (and presumably its to directly generating the roff with asciidoctor). The middle step of having asciidoctor+xmlto helps us understand and isolate which changes are responsible for which parts of the output. -Peff
On Sat, 7 Sep 2019 at 08:45, Jeff King <peff@peff.net> wrote: > > On Thu, Sep 05, 2019 at 09:35:10PM +0200, Martin Ågren wrote: > > > > Yeah, I do still like that as an endgame, but I like what you have here > > > as an intermediate step in the right direction. > > > > Hmm, so this sounds like once I am happy with replacing AsciiDoc with > > Asciidoctor 1(.5.5), I should rather not propose a series "let's default > > to Asciidoctor!!!" but instead a slightly more careful "go with > > Asciidoctor, but document that we work badly with v2 and that the 2nd > > choice after Asciidoctor 1 should be AsciiDoc". Or do you see it > > differently? (I wonder which Asciidoctor-version Junio would be on..) > > Yeah, that seems reasonable. > > TBH, if making things in the middle step work turns out to be too hard, > I'm not entirely opposed to a hard switch. > > The "does not work with 2.0" thing has to be a temporary step, though, I > think, since using the older versions will get harder and harder as time > goes on. I think it's OK to take such a temporary step as long as we > understand where it leads (and presumably its to directly generating the > roff with asciidoctor). The middle step of having asciidoctor+xmlto > helps us understand and isolate which changes are responsible for which > parts of the output. So of these steps: 0. Get Asciidoctor (v1) in shape. 1. Switch the default to Asciidoctor (v1). 2. Drop AsciiDoc to have faster Asciidoctor-processing, avoid xmlto and support Asciidoctor 2. And to avoid the Python 2 EOL, too. Step 0 is not far away, so step 1 could be done fairly soon IMHO. Step 2 would "hopefully" happen soon after -- maybe even in the same release cycle as step 1, and if not the same then the one just after. But I might be the wrong person to trust on that one. I currently don't even try to build with Asciidoctor 2. I might perhaps look into installing it, but it could also be that I'll only start using it when it happens to arrive through my distro. So as long as I'm not looking into Asciidoctor 2, maybe I shouldn't be the one to impose "default to asciidoctor" on the world. Dunno. In any case, I should be able to bring the asciidoc/tor1 differences to a state where we trust asciidoctor 1 to be in a good shape, so that "someone else" could pick up the ball and work on asciidoctor 2 vs 1, knowing that it's ok if they regress AsciiDoc support or even drop it entirely in the process. Martin
On 2019-09-07 at 04:40:22, Jeff King wrote: > On Fri, Sep 06, 2019 at 11:29:47PM +0000, brian m. carlson wrote: > > I'll look into this. I requested the upgrade in sid. > > > > If it's the lack of DocBook 4.5 support, then I'll probably need to > > patch xmlto for that. DocBook 5 has been around for a decade now, so > > it's time for xmlto to support it properly. > > Yes, it's the docbook45 thing. Switching to docbook5 lets asciidoc run, > but then xmlto chokes. I already have a patch for Git to fix this. I'll send it out this weekend.
On Sat, Sep 07, 2019 at 04:06:48PM +0200, Martin Ågren wrote: > So of these steps: > > 0. Get Asciidoctor (v1) in shape. > > 1. Switch the default to Asciidoctor (v1). > > 2. Drop AsciiDoc to have faster Asciidoctor-processing, avoid xmlto > and support Asciidoctor 2. And to avoid the Python 2 EOL, too. > > Step 0 is not far away, so step 1 could be done fairly soon IMHO. Step 2 > would "hopefully" happen soon after -- maybe even in the same release > cycle as step 1, and if not the same then the one just after. But I > might be the wrong person to trust on that one. I currently don't even > try to build with Asciidoctor 2. I might perhaps look into installing > it, but it could also be that I'll only start using it when it happens > to arrive through my distro. > > So as long as I'm not looking into Asciidoctor 2, maybe I shouldn't be > the one to impose "default to asciidoctor" on the world. Dunno. In any > case, I should be able to bring the asciidoc/tor1 differences to a state > where we trust asciidoctor 1 to be in a good shape, so that "someone > else" could pick up the ball and work on asciidoctor 2 vs 1, knowing > that it's ok if they regress AsciiDoc support or even drop it entirely > in the process. We could also drop xmlto for the asciidoctor codepaths, without making it the default. That requires a little bit more Makefile massaging, but here's a hacky way to do it (this is on top of brian's asciidoctor 2 patch, which I've been experimenting with, but obviously we could skip that entirely, too): --- diff --git a/Documentation/Makefile b/Documentation/Makefile index 485f365cbf..c3ebca6e36 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -197,12 +197,12 @@ ifdef USE_ASCIIDOCTOR ASCIIDOC = asciidoctor ASCIIDOC_CONF = ASCIIDOC_HTML = xhtml5 -ASCIIDOC_DOCBOOK = docbook5 +ASCIIDOC_DOCBOOK = manpage ASCIIDOC_EXTRA += -acompat-mode -atabsize=8 ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions ASCIIDOC_EXTRA += -alitdd='&\#x2d;&\#x2d;' DBLATEX_COMMON = -XMLTO_EXTRA += --skip-validation +XMLTO = ./fake-xmlto endif SHELL_PATH ?= $(SHELL) diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb index 4ae130d2c6..aae891e8ff 100644 --- a/Documentation/asciidoctor-extensions.rb +++ b/Documentation/asciidoctor-extensions.rb @@ -17,6 +17,8 @@ module Git "<refentrytitle>#{target}</refentrytitle>" \ "<manvolnum>#{attrs[1]}</manvolnum>\n" \ "</citerefentry>" + elsif parent.document.basebackend? 'manpage' + "#{target}(#{attrs[1]})" end end end diff --git a/Documentation/fake-xmlto b/Documentation/fake-xmlto new file mode 100755 index 0000000000..eca7ba289d --- /dev/null +++ b/Documentation/fake-xmlto @@ -0,0 +1,9 @@ +#!/bin/sh + +# pick last arg as file +for file in "$@"; do + : nothing +done + +nr=$(perl -lne '/^\.TH ".*?" "(\d)"/ and print $1' $file) +cp $file ${file%.xml}.$nr