From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on dcvr.yhbt.net X-Spam-Level: X-Spam-ASN: AS31976 209.132.180.0/23 X-Spam-Status: No, score=-3.9 required=3.0 tests=AWL,BAYES_00, HEADER_FROM_DIFFERENT_DOMAINS,MAILING_LIST_MULTI,RCVD_IN_DNSWL_HI, SPF_HELO_NONE,SPF_NONE shortcircuit=no autolearn=ham autolearn_force=no version=3.4.2 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by dcvr.yhbt.net (Postfix) with ESMTP id C063E1F461 for ; Wed, 4 Sep 2019 03:26:12 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1728023AbfIDD0L (ORCPT ); Tue, 3 Sep 2019 23:26:11 -0400 Received: from cloud.peff.net ([104.130.231.41]:38634 "HELO cloud.peff.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with SMTP id S1727065AbfIDD0L (ORCPT ); Tue, 3 Sep 2019 23:26:11 -0400 Received: (qmail 9813 invoked by uid 109); 4 Sep 2019 03:26:11 -0000 Received: from Unknown (HELO peff.net) (10.0.1.2) by cloud.peff.net (qpsmtpd/0.94) with SMTP; Wed, 04 Sep 2019 03:26:11 +0000 Authentication-Results: cloud.peff.net; auth=none Received: (qmail 11098 invoked by uid 111); 4 Sep 2019 03:27:51 -0000 Received: from sigill.intra.peff.net (HELO sigill.intra.peff.net) (10.0.0.7) by peff.net (qpsmtpd/0.94) with (TLS_AES_256_GCM_SHA384 encrypted) ESMTPS; Tue, 03 Sep 2019 23:27:51 -0400 Authentication-Results: peff.net; auth=none Date: Tue, 3 Sep 2019 23:26:10 -0400 From: Jeff King To: Martin =?utf-8?B?w4VncmVu?= Cc: git@vger.kernel.org, Todd Zullinger , SZEDER =?utf-8?B?R8OhYm9y?= , "brian m. carlson" , Junio C Hamano Subject: Re: [PATCH v2 0/2] asciidoctor-extensions: provide `` Message-ID: <20190904032609.GD28836@sigill.intra.peff.net> References: MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Disposition: inline Content-Transfer-Encoding: 8bit In-Reply-To: Sender: git-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org 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