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: AS53758 23.128.96.0/24 X-Spam-Status: No, score=-3.9 required=3.0 tests=AWL,BAYES_00, HEADER_FROM_DIFFERENT_DOMAINS,MAILING_LIST_MULTI,RCVD_IN_DNSWL_MED, SPF_HELO_PASS,SPF_PASS shortcircuit=no autolearn=ham autolearn_force=no version=3.4.2 Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by dcvr.yhbt.net (Postfix) with ESMTP id D2DB41F5AE for ; Fri, 7 May 2021 22:19:07 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229742AbhEGWUF (ORCPT ); Fri, 7 May 2021 18:20:05 -0400 Received: from cloud.peff.net ([104.130.231.41]:47692 "EHLO cloud.peff.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229470AbhEGWUF (ORCPT ); Fri, 7 May 2021 18:20:05 -0400 Received: (qmail 3516 invoked by uid 109); 7 May 2021 22:19:04 -0000 Received: from Unknown (HELO peff.net) (10.0.1.2) by cloud.peff.net (qpsmtpd/0.94) with ESMTP; Fri, 07 May 2021 22:19:04 +0000 Authentication-Results: cloud.peff.net; auth=none Received: (qmail 4373 invoked by uid 111); 7 May 2021 22:19:05 -0000 Received: from coredump.intra.peff.net (HELO sigill.intra.peff.net) (10.0.0.2) by peff.net (qpsmtpd/0.94) with (TLS_AES_256_GCM_SHA384 encrypted) ESMTPS; Fri, 07 May 2021 18:19:05 -0400 Authentication-Results: peff.net; auth=none Date: Fri, 7 May 2021 18:19:03 -0400 From: Jeff King To: "brian m. carlson" Cc: Bagas Sanjaya , Git Users Subject: Re: [RFC suggestion] Generate manpage directly with Asciidoctor Message-ID: References: <3461c7b0-594d-989e-3048-2fc6583084ad@gmail.com> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Disposition: inline In-Reply-To: Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org On Fri, May 07, 2021 at 08:25:36PM +0000, brian m. carlson wrote: > > So completely migrating to Asciidoctor can eliminate xmlto requirement > > for generating manpage. > > > > What do you think about above? > > I didn't do this because it makes things very complicated in the > Makefile and my goal was to minimize the needed changes and divergence. > I'm not opposed to someone else doing it, but I expect it will be a > bunch of work. Yeah. In the period where we support both asciidoc and asciidoctor, using the same flow for both (even if it's suboptimal for asciidoctor) kept the complexity down. I _thought_ the original asciidoc was marked as deprecated / unmaintained at some point. But it does seem to have gotten a few releases in the last year (it looks like maybe the python 2 version was EOL, but somebody decided to make the effort to port it to python 3?). But I wouldn't be at all sad to just standardize on asciidoctor. I think we're at parity in terms of the output (thanks to lots of work from you and Martin over the past couple of years), and I've generally found it nicer to work with. The only downside is that it may be available in fewer places (though I'd think that python vs ruby is not so different). IMHO it's OK to be aggressive about the doc toolchain requirements, because the fallback is always grabbing the preformatted roff or HTML pages that were generated on a different system. -Peff