Re: [PATCH 09/23] qapi/source: allow multi-line QAPISourceInfo advancing

[Markus Armbruster]

John Snow <jsnow@redhat.com> writes:

> On Fri, Dec 20, 2024 at 8:22 AM Markus Armbruster <armbru@redhat.com> wrote:
>
>> John Snow <jsnow@redhat.com> writes:
>>
>> > This is for the sake of the new rST generator (the "transmogrifier") so
>> > we can advance multiple lines on occasion while keeping the
>> > generated<-->source mappings accurate.
>> >
>> > next_line now simply takes an optional n parameter which chooses the
>> > number of lines to advance.
>> >
>> >
>> > RFC: Here's the exorbitant detail on why I want this:
>> >
>> > This is used mainly when converting section syntax in free-form
>> > documentation to more traditional rST section header syntax, which
>> > does not always line up 1:1 for line counts.
>> >
>> > For example:
>> >
>> > ```
>> >  ##
>> >  # = Section     <-- Info is pointing here, "L1"
>> >  #
>> >  # Lorem Ipsum
>> >  ##
>> > ```
>> >
>> > would be transformed to rST as:
>> >
>> > ```
>> > =======        <-- L1
>> > Section        <-- L1
>> > =======        <-- L1
>> >                <-- L2
>> > Lorem Ipsum    <-- L3
>> > ```
>>
>> I can't help to wonder...  Could we simply use rST markup instead?
>>
>> "Later", "maybe later", or even "please ask me later" would be perfectly
>> acceptable answers.
>>
>
> Yeah, I'd be happy with that, I just didn't want to add more complexity to
> the pile so I went for what I felt was "simplest":

Avoiding mission creep is good.

> - Leave source syntax alone
> - Copy and modify the existing freeform doc parser
> - Quickly allow for multi-line advancing where it appeared to be important.
>
> Modifying freeform syntax to be purely rST that isn't modified or rewritten
> at all has benefits:
>
> - No need to mangle or multiplex source line source information
> - Less code
> - More straightforward
>
> I'm quite happy to do it later, is there some kind of "ticket" system you'd
> tolerate using for tracking nits for cleanup? I *will* forget if we don't
> listify and track them, I'm sorry (but wise enough) to admit. I just don't
> want to get sidetracked on little side-quests right now. (Quite prone to
> this...)

TODO comment in code this would obviously kill?  Not exactly a ticket
system...

scripts/qapi/TODO?  Still not a ticket system...

Other ideas?

>> > After consuming the single "Section" line from the source, we want to
>> > advance the source pointer to the next non-empty line which requires
>> > jumping by more than one line.
>> >
>> > Signed-off-by: John Snow <jsnow@redhat.com>
>> > ---
>> >  scripts/qapi/source.py | 4 ++--
>> >  1 file changed, 2 insertions(+), 2 deletions(-)
>> >
>> > diff --git a/scripts/qapi/source.py b/scripts/qapi/source.py
>> > index 7b379fdc925..ffdc3f482ac 100644
>> > --- a/scripts/qapi/source.py
>> > +++ b/scripts/qapi/source.py
>> > @@ -47,9 +47,9 @@ def set_defn(self, meta: str, name: str) -> None:
>> >          self.defn_meta = meta
>> >          self.defn_name = name
>> >
>> > -    def next_line(self: T) -> T:
>> > +    def next_line(self: T, n: int = 1) -> T:
>> >          info = copy.copy(self)
>> > -        info.line += 1
>> > +        info.line += n
>> >          return info
>> >
>> >      def loc(self) -> str:
>>
>> Assuming we need this:
>> Reviewed-by: Markus Armbruster <armbru@redhat.com>
>
> Thanks! We can always drop stuff later if we wind up not needing it, it's
> just a means to an end.

Yes, and this one isn't exactly a complexity bomb :)