Markus Armbruster <[email protected]> writes:
> Vladimir Sementsov-Ogievskiy <[email protected]> writes:
>
>> Add explicit validation for QAPI documentation formatting rules:
>>
>> 1. Lines must not exceed 70 columns in width (including '# ' prefix)
>> 2. Sentences must be separated by two spaces
>>
>> Example sections are excluded, we don't require them to be <= 70,
>> that would be too restrictive.
>>
>> Example sections share common 80-columns recommendations (not
>> requirements).
>>
>> Signed-off-by: Vladimir Sementsov-Ogievskiy <[email protected]>
>> ---
>>
>> Hi all!
>>
>> This substitutes my previous attempt
>> "[PATCH v2 00/33] qapi: docs: width=70 and two spaces between sentences"
>> Supersedes: <[email protected]>
>>
>> v3:
>> 01: ignore example sections
>> other commits: dropped :)
>>
>> Of course, this _does not_ build on top of current master. v3 is
>> to be based on top of coming soon doc-cleanup series by Markus.
[...]
>> + single_space_pattern = r'[.!?] [A-Z0-9]'
>
> This pattern matches possible sentence ends that lack a second space:
> sentence-ending punctuation, single space, capital letter or digit.
>
> The pattern avoids common false positives in the middle of a sentence,
> such as "i.e." here:
>
> # Describes a block export, i.e. how single node should be exported on
> ~~~~~
>
> Good. There's still a risk of false positives, though: a capital letter
> need not be the start of a sentence, it could also be a proper noun, or
> the pronoun "I". I figure the latter is vanishingly unlikely to occur
> in technical documentation. Example of the former:
>
> # @format: Extent type (e.g. FLAT or SPARSE)
>
> You filter these out below.
>
> Digits are even more ambiguous than capital letters: they can occur in
> the middle of a sentence as much as at the beginning. Do they occur?
>
> $ git-grep '\. [0-9]' \*.json
> docs/interop/firmware.json:# of SMRAM. 48MB should suffice
> for 4TB of guest-phys
>
> Yes, but only in a QAPI schema we don't actually parse. We should
> probably update these to conform to conventions. Not today.
Actually, we do parse it, but only in "make check". See
docs/meson.build. The cleanup series I just sent covers it.
Unfortunately, this adds another case for you. In master:
# @executable: Identifies the firmware executable. The @mode
# indicates whether there will be an associated
# NVRAM template present. The preferred
# corresponding QEMU command line options are
# -drive
if=none,id=pflash0,readonly=on,file=@executable.@filename,format=@executable.@format
# -machine pflash0=pflash0
# or equivalent -blockdev instead of -drive. When
# @mode is @combined the executable must be
# cloned before use and configured with readonly=off.
# With QEMU versions older than 4.0, you have to use
# -drive
if=pflash,unit=0,readonly=on,file=@executable.@filename,format=@executable.@format
My series cleans this up to
# @executable: Identifies the firmware executable. The @mode
# indicates whether there will be an associated NVRAM template
# present. The preferred corresponding QEMU command line options
# are
#
# ::
#
# -drive
if=none,id=pflash0,readonly=on,file=@executable.@filename,format=@executable.@format
# -machine pflash0=pflash0
#
# or equivalent -blockdev instead of -drive. When @mode is
# @combined the executable must be cloned before use and
# configured with readonly=off. With QEMU versions older than
# 4.0, you have to use
#
# ::
#
# -drive
if=pflash,unit=0,readonly=on,file=@executable.@filename,format=@executable.@format
This uses ReST markup for literal blocks. There are two forms.
1. A paragraph containing just "::" starts a literal block.
2. A paragraph ending with "::" also starts one.
In either case, the block's contents is indented.
See https://docutils.sourceforge.io/docs/user/rst/quickref.html#literal-blocks
for more.
I think you need to switch literal mode on when you detect a qmp-example
directive or a literal block, and record the line's indentation. switch
it off at the first line that is no more indented than the recorded
indentation.
[...]
