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