On Thu, Jun 20, 2024, 11:07 AM Markus Armbruster <arm...@redhat.com> wrote:
> John Snow <js...@redhat.com> writes: > > > On Wed, Jun 19, 2024, 8:03 AM Markus Armbruster <arm...@redhat.com> > wrote: > > > >> John Snow <js...@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? > precisamente. That solution was categorically worse. > [...] > >
