On Tue, 22 Sep 2020 at 08:27, Markus Armbruster <arm...@redhat.com> wrote: > How does > > @foo: bar > baz > @frob: gnu > gnat > > behave?
The rST fragments would be: bar baz gnu gnat So you get what rST does with that. We do actually have examples of this in the existing QAPI doc comments. It ends up treating it as a definition list where the term is 'bar' and the definition is 'baz' (which I don't entirely understand, I was expecting a block-quote). That renders sufficiently close to correct that I hadn't noticed it. It would be a fairly small change to determine the indent level by looking for the first non-ws character on line 1 after the colon. Since we have a fair amount of this style in the code and it's as you say a natural-seeming thing to write that seems the best thing. (If you really wanted to start the option documentation with some rST that required an initial indent, probably because you're writing a literal-text Examples section, then you'd need to use the "nothing after the : on line 1, rST fragment begins on line 2 in column 0" style. Which would be the most natural way to write that literal text anyway.) I guess at this point I'll potentially create work for myself by drawing your attention to the rST syntax for field lists and option lists: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#field-lists which are kind of similar to what we're doing with @foo: stuff markup, and which handle indentation like this: :Hello: This field has a short field name, so aligning the field body with the first line is feasible. :Number-of-African-swallows-required-to-carry-a-coconut: It would be very difficult to align the field body with the left edge of the first line. It may even be preferable not to begin the body on the same line as the marker. The differences to what I have implemented in this series are: * indent of lines 2+ is determined by the indent of line 2, not 1 * lines 2+ must be indented, so anything that currently uses "no indent, start in column 0" would need indenting. (This would be a lot of change to our current docs text.) * it doesn't say in the spec, but I guess that spaces between the colon and start of line 1 text are not significant. The advantage would be a bit more consistency with rST syntax otherwise; the disadvantage is that we have a *lot* of text that uses the "start in column 0" format, like this: # @QCryptoBlockOptionsBase: # # The common options that apply to all full disk # encryption formats and we'd need to reindent it all. My view is that trying to look more like rST indent isn't sufficiently useful to be worth having to change all that. > This is something people may actually write. Indeed, they have :-) thanks -- PMM
