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_HI, 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 256841F5AE for ; Wed, 21 Jul 2021 11:37:06 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S237238AbhGUKni (ORCPT ); Wed, 21 Jul 2021 06:43:38 -0400 Received: from cloud.peff.net ([104.130.231.41]:52982 "EHLO cloud.peff.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S238592AbhGUJ2A (ORCPT ); Wed, 21 Jul 2021 05:28:00 -0400 Received: (qmail 1860 invoked by uid 109); 21 Jul 2021 10:08:00 -0000 Received: from Unknown (HELO peff.net) (10.0.1.2) by cloud.peff.net (qpsmtpd/0.94) with ESMTP; Wed, 21 Jul 2021 10:08:00 +0000 Authentication-Results: cloud.peff.net; auth=none Received: (qmail 2832 invoked by uid 111); 21 Jul 2021 10:08:20 -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; Wed, 21 Jul 2021 06:08:20 -0400 Authentication-Results: peff.net; auth=none Date: Wed, 21 Jul 2021 06:08:18 -0400 From: Jeff King To: Taylor Blau Cc: git@vger.kernel.org, dstolee@microsoft.com, gitster@pobox.com, jonathantanmy@google.com Subject: Re: [PATCH v2 04/24] Documentation: build 'technical/bitmap-format' by default Message-ID: References: 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 Wed, Jul 21, 2021 at 05:58:41AM -0400, Jeff King wrote: > On Mon, Jun 21, 2021 at 06:25:07PM -0400, Taylor Blau wrote: > > > Even though the 'TECH_DOCS' variable was introduced all the way back in > > 5e00439f0a (Documentation: build html for all files in technical and > > howto, 2012-10-23), the 'bitmap-format' document was never added to that > > list when it was created. > > > > Prepare for changes to this file by including it in the list of > > technical documentation that 'make doc' will build by default. > > OK. I don't care that much about being able to format this as html, but > I agree it's good to be consistent with the other stuff in technical/. > > The big question is whether it looks OK rendered by asciidoc, and the > answer seems to be "yes" (from a cursory look I gave it). Actually, I take it back. After looking more carefully, it renders quite poorly. There's a lot of structural indentation that ends up being confused as code blocks. I don't know if it's better to have a poorly-formatted HTML file, or none at all. :) Personally, I would just read the source. And I have a slight concern that if we start "cleaning it up" to render as asciidoc, the source might end up a lot less readable (though I'd reserve judgement until actually seeing it). -Peff