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

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:

quoted

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