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... 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 :)
