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