On Fri, Jun 14, 2024, 6:55 AM Markus Armbruster <[email protected]> wrote:
> John Snow <[email protected]> writes: > > > If we parse all examples as QMP, we need them to conform to a standard > > so that they render correctly. Once the QMP lexer is active for > > examples, these will produce warning messages and fail the build. > > > > The QMP lexer still supports elisions, but they must be represented as > > the value "...", so two examples have been adjusted to support that > > format here. > > I think this could use a bit more context. I believe you're referring > to docs/sphinx/qmp_lexer.py. It describes itself as "a Sphinx extension > that provides a QMP lexer for code blocks." > That's our guy! I explain its use a bit more in ... some other patch, somewhere... > "If we parse all examples as QMP" and "Once the QMP lexer is active for > examples" suggests we're *not* using it for (some?) examples. So what > are we using it for? > My incremental backup doc makes use of it; you have to "opt in" to using the QMP lexer instead of the generic lexer. The example conversion patch later in this series opts all of the qapi docs into using it. ((Later, it's possible to make "Example::" choose the QMP lexer by default on any of our generated QMP pages. (and opting out would require explicit code-block syntax with the lexer of choice named.))) > > Signed-off-by: John Snow <[email protected]> > > Patch looks lovely. > > Hat tip to Victor Toso, who fixed up most examples two years ago. Back > then we couldn't decide how to do elisions, so we left some unfixed. > Sorry I didn't chime in back then! "..." is arbitrary, but it's what we already use for the qmp lexer and in the incremental backup/bitmap docs, so I figured consistency was good. The QMP lexer has syntax support for ->, <- and ... and otherwise requires the examples to be valid JSON. It doesn't understand grammar, though, so it's kind of "dumb", but this is one small protection. >
