Re: [PATCH v2 04/24] Documentation: build 'technical/bitmap-format' by default

From: Jeff King <peff@peff.net>
Date: Jul 21, 2021, 10:08 UTC
Message-ID: <YPfyEiXw7szt5mjl@coredump.intra.peff.net>
In-Reply-To: <YPfv0YoLtpYp9866@coredump.intra.peff.net>

On Wed, Jul 21, 2021 at 05:58:41AM -0400, Jeff King wrote:

Show 15 quoted lines

> 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