On Thu, Jan 9, 2025, 3:00 AM Markus Armbruster <arm...@redhat.com> wrote:
> John Snow <js...@redhat.com> writes: > > > On Fri, Dec 20, 2024 at 8:22 AM Markus Armbruster <arm...@redhat.com> > wrote: > > > >> John Snow <js...@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... > If a TODO is fine (and you don't mind pinging me in the future), then the comment I left in the visit_freeform() function (it's in another patch) explaining that the custom parser can be dropped after we sunset the old qapidoc is likely sufficient if I just add a "TODO". Sound good? > 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 <js...@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 <arm...@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 :) >
