Re: [libvirt PATCH 1/4] docs: Use consistent style in pci-addresses.rst
On Thu, 2020-04-16 at 12:38 +0100, Daniel P. Berrangé wrote: > On Thu, Apr 16, 2020 at 01:35:57PM +0200, Andrea Bolognani wrote: > > 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 :) > > BTW, we could update styleguide.rst to mention this preference. https://www.redhat.com/archives/libvir-list/2020-April/msg00822.html -- Andrea Bolognani / Red Hat / Virtualization
Re: [libvirt PATCH 1/4] docs: Use consistent style in pci-addresses.rst
On Thu, Apr 16, 2020 at 01:35:57PM +0200, Andrea Bolognani wrote: > 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 :) BTW, we could update styleguide.rst to mention this preference. Regards, Daniel -- |: https://berrange.com -o-https://www.flickr.com/photos/dberrange :| |: https://libvirt.org -o-https://fstop138.berrange.com :| |: https://entangle-photo.org-o-https://www.instagram.com/dberrange :|
Re: [libvirt PATCH 1/4] docs: Use consistent style in pci-addresses.rst
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:: and Here's some code :: render differently makes this form more error-prone. -- Andrea Bolognani / Red Hat / Virtualization
Re: [libvirt PATCH 1/4] docs: Use consistent style in pci-addresses.rst
On Thu, Apr 16, 2020 at 12:58:43PM +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. That aligns with the style we've used in all other rst docs we've done so far. Ideally we wouldn't use a bare "::" anyway - we really ought to be using ".. code-block:: $LANGUAGE" to instruct the renderer how to highlight the code snippets. Our current website generator doesn't use this, but hopefully we will in future Regards, Daniel -- |: https://berrange.com -o-https://www.flickr.com/photos/dberrange :| |: https://libvirt.org -o-https://fstop138.berrange.com :| |: https://entangle-photo.org-o-https://www.instagram.com/dberrange :|
Re: [libvirt PATCH 1/4] docs: Use consistent style in pci-addresses.rst
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. Jano This commit is best viewed with 'git show -w'. Signed-off-by: Andrea Bolognani --- docs/pci-addresses.rst | 60 ++ 1 file changed, 32 insertions(+), 28 deletions(-) signature.asc Description: PGP signature
Re: [libvirt PATCH 1/4] docs: Use consistent style in pci-addresses.rst
On Wed, 15 Apr 2020 19:31:33 +0200 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. > > This commit is best viewed with 'git show -w'. > > Signed-off-by: Andrea Bolognani > --- > docs/pci-addresses.rst | 60 ++ > 1 file changed, 32 insertions(+), 28 deletions(-) Reviewed-by: Cornelia Huck
