On Wed, Jul 21, 2021 at 06:08:18AM -0400, Jeff King wrote: > 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). Yeah, the actual source is pretty readable (and it's what I had been looking at, although it is sometimes convenient to have a version I can read in my web browser). But it's definitely not good Asciidoc. I briefly considered cleaning it up, but decided against it. Usually I would opt to clean it up, but this series is already so large that I figured it would make a negative impact on the reviewer experience to read a clean-up patch here. I wouldn't be opposed to coming back to it in the future, once the dust settles. I guess we can consider this #leftoverbits until then. Thanks, Taylor
