[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH 04/13] qapi/parser: preserve indentation in QAPIDoc sections
From: |
Markus Armbruster |
Subject: |
Re: [PATCH 04/13] qapi/parser: preserve indentation in QAPIDoc sections |
Date: |
Thu, 20 Jun 2024 17:07:48 +0200 |
User-agent: |
Gnus/5.13 (Gnus v5.13) |
John Snow <jsnow@redhat.com> writes:
> On Wed, Jun 19, 2024, 8:03 AM Markus Armbruster <armbru@redhat.com> wrote:
>
>> John Snow <jsnow@redhat.com> writes:
>>
>> > Change get_doc_indented() to preserve indentation on all subsequent text
>> > lines, and create a compatibility dedent() function for qapidoc.py to
>> > remove that indentation. This is being done for the benefit of a new
>>
>> Suggest "remove indentation the same way get_doc_indented() did."
>>
>
> Aight.
>
>
>> > qapidoc generator which requires that indentation in argument and
>> > features sections are preserved.
>> >
>> > Prior to this patch, a section like this:
>> >
>> > ```
>> > @name: lorem ipsum
>> > dolor sit amet
>> > consectetur adipiscing elit
>> > ```
>> >
>> > would have its body text be parsed as:
>>
>> Suggest "parsed into".
>>
>
> Why? (I mean, I'll do it, but I don't see the semantic difference
> personally)
>
"Parse as <language>" vs. "Parse into <representation>".
>> > (first and final newline only for presentation)
>> >
>> > ```
>> > lorem ipsum
>> > dolor sit amet
>> > consectetur adipiscing elit
>> > ```
>> >
>> > We want to preserve the indentation for even the first body line so that
>> > the entire block can be parsed directly as rST. This patch would now
>> > parse that segment as:
>>
>> If you change "parsed as" to "parsed into" above, then do it here, too.
>>
>> >
>> > ```
>> > lorem ipsum
>> > dolor sit amet
>> > consectetur adipiscing elit
>> > ```
>> >
>> > This is helpful for formatting arguments and features as field lists in
>> > rST, where the new generator will format this information as:
>> >
>> > ```
>> > :arg type name: lorem ipsum
>> > dolor sit amet
>> > consectetur apidiscing elit
>> > ```
>> >
>> > ...and can be formed by the simple concatenation of the field list
>> > construct and the body text. The indents help preserve the continuation
>> > of a block-level element, and further allow the use of additional rST
>> > block-level constructs such as code blocks, lists, and other such
>> > markup. Avoiding reflowing the text conditionally also helps preserve
>> > source line context for better rST error reporting from sphinx through
>> > generated source, too.
>>
>> What do you mean by "reflowing"?
>>
>
> Poorly phrased, was thinking about emacs too much. I mean munging the text
> post-hoc for the doc generator such that newlines are added or removed in
> the process of re-formatting text to get the proper indentation for the new
> rST form.
>
> In prototyping, this got messy very quickly and was difficult to correlate
> source line numbers across the transformation.
>
> It was easier to just not munge the text at all instead of munging it and
> then un-munging it.
>
> (semantic satiation: munge munge munge munge.)
Is this about a possible alternative solution you explored? Keeping
.get_doc_indented() as is, and then try to undo its damage?
[...]
- [PATCH 00/13] qapi: convert "Note" and "Example" sections to rST, John Snow, 2024/06/18
- [PATCH 01/13] [DO-NOT-MERGE]: Add some ad-hoc linting helpers., John Snow, 2024/06/18
- [PATCH 02/13] qapi: linter fixups, John Snow, 2024/06/18
- [PATCH 03/13] docs/qapidoc: delint a tiny portion of the module, John Snow, 2024/06/18
- [PATCH 04/13] qapi/parser: preserve indentation in QAPIDoc sections, John Snow, 2024/06/18
- Re: [PATCH 04/13] qapi/parser: preserve indentation in QAPIDoc sections, Markus Armbruster, 2024/06/19
- Re: [PATCH 04/13] qapi/parser: preserve indentation in QAPIDoc sections, John Snow, 2024/06/20
- Re: [PATCH 04/13] qapi/parser: preserve indentation in QAPIDoc sections,
Markus Armbruster <=
- Re: [PATCH 04/13] qapi/parser: preserve indentation in QAPIDoc sections, John Snow, 2024/06/20
- Re: [PATCH 04/13] qapi/parser: preserve indentation in QAPIDoc sections, Markus Armbruster, 2024/06/21
- Re: [PATCH 04/13] qapi/parser: preserve indentation in QAPIDoc sections, John Snow, 2024/06/21
- Re: [PATCH 04/13] qapi/parser: preserve indentation in QAPIDoc sections, Markus Armbruster, 2024/06/22
[PATCH 05/13] qapi/parser: fix comment parsing immediately following a doc block, John Snow, 2024/06/18
[PATCH 06/13] docs/qapidoc: fix nested parsing under untagged sections, John Snow, 2024/06/18
[PATCH 07/13] qapi: fix non-compliant JSON examples, John Snow, 2024/06/18