[libvirt PATCH 1/4] docs: Use consistent style in pci-addresses.rst

Andrea Bolognani abologna at redhat.com
Thu Apr 16 11:35:57 UTC 2020

On Thu, 2020-04-16 at 12:58 +0200, Ján Tomko wrote:
> On a Wednesday in 2020, Andrea Bolognani wrote:
> > Indent all code snippets by the same number of spaces, and don't
> > embed the :: marker in the line preceding a code block.
> But why? It's so ugly.

I disagree, and find it much easier on the eye than the alternative.

That's a matter of personal preference, of course, but the fact that
all existing reStructuredText files in the repository follow this
convention could indicate that I'm not the only one holding this
opinion. This change was made for consistency's sake, not to appease
my sense of aestethic - althought in this case the two overlap :)

More objectively, the fact that the indicator is on its own line
makes it stand out more and make it obvious at a glance that what
you're looking at is a code block rather than a block quote: this is
more important when looking at diffs than when working in the editor,
but even with syntax highlighting turned on that small splash of
color at the end of a line is easier to miss than when it forms a
line of its own.

Additionally, the fact that

  Here's some code::


  Here's some code ::

render differently makes this form more error-prone.

Andrea Bolognani / Red Hat / Virtualization

More information about the libvir-list mailing list