On Tue, 19 Mar 2019 at 04:55, Junio C Hamano <gitster@xxxxxxxxx> wrote: > > Jeff King <peff@xxxxxxxx> writes: > > > So in my mind, the endgame is that we eventually drop asciidoc in favor > > of asciidoctor. The repo at: > > > > https://github.com/asciidoc/asciidoc > > > > says: > > > > NOTE: This implementation is written in Python 2, which EOLs in Jan > > 2020. AsciiDoc development is being continued under @asciidoctor. > > ;-) > > > I'm not sure when is the right time to switch. If we can get the output > > at parity, I don't think asciidoctor is too onerous to install (and we > > don't have to worry about ancient platforms, as they can use > > pre-formatted manpages). > > One minor thing that bothers me abit is the continuity of the > pre-formatted pages when I switch to asciidoctor to update them. > > I do not mind having to see a huge diff in the "git log -p" output > run in pre-formatted manpages and htmldocs repositories at the > boundary due to e.g. the differences how lines are broken or folded > between the formatters, but by the time we have to transition, the > efforts by you, Martin and friends to allow us compare the formatted > docs would have made the real differences to empty (or at least > negligible). Knock knock... This might be a good spot to provide a bit of current status on this. The patch under discussion here and 185f9a0ea0 ("asciidoctor-extensions: fix spurious space after linkgit", 2019-02-27), reduce the diff between asciidoc and asciidoctor considerably. Let's assume for the moment that these patches or something like them enter master... There's one larger difference in git-checkout.txt which I'm staying away from at the moment, since Duy is doing a lot of work there at the time. (He's not making that asciidoc/tor issue any worse, and he's not spreading it to say git-switch.txt, so I'd rather just not rush to it.) Let's assume I get around to this soonish... Let's also assume that `./doc-diff --cut-header-footer --from-asciidoc --to-asciidoctor HEAD HEAD` enters master [1]. Then what remains is a fairly small and understandable diff where most issues are "yeah, I guess that looks nicer" or even "they're just as fine", rather than "oh wow, that's ugly". (IMHO.) Martin [1] You could already now run it to diff "master master", but you'd trip on the Makefile thinking there's nothing to do. That'd be fixed by 9a71722b4d ("Doc: auto-detect changed build flags", 2019-03-17).
