Re: The RPC's roadmap regarding GitHub

[Michael Richardson <[e-mail]>]

Jean Mahoney <[e-mail]> wrote:
    > On 8/5/26 4:19 PM, Rohan Mahy wrote:
    >> Hi,
    >> I don't need an LLM to replace an include with its contents. It's just
    >> losing more semantics compared to using the included files directly, and
    >> adds a step for the authors.
    >> Jean created an issue.

    > [JM] And the answer I received for that issue is that kramdown-rfc can
    > already put included files in the markdown output when you run the following
    > two commands (although it doesn't put markers around included content):

    > kramdown-rfc mydraft.md >mydraft.xml

Yes, kramdown will process the included files when creating the XML.
This happens today, all the time.  After this step, you now have XML that you
could edit....
But the goal was for the RPC to have markdown that it can edit, and that
authors can review.  So, that does not result in what we want yet...

    > kramdown-rfc-extract-markdown mydraft.xml >mydraft-files-inline.md

So I guess the point is that the markdown that kramdown stores has the
includes included into the markdown [which makes sense], so this cycle gives
us markdown with includes expanded as a single file.
I guess that's progress towards the above goal.

If/when there are edits that have an impact on the contents of the
(generated) examples, then the authors would have to patch the inline
contents.  An example of such an edit: allocation of IANA code points.

Authors now have to paste the content in.
Plus: we can do this via git rather than potentially format breaking emails.
Negative: we can still break things in hard to see ways, which was the point
of the automation in the first place.

kramdown-rfc-extract-figures-tables and kramdown-rfc-extract-sourcecode can
pull source code out of XML and turn it back into split out files, and with
the right markdown (and resulting XML annotation), can use meaningful
filenames.

If the markdown embedded in the XML can be extended to put markers around the
embedded content, then probably a tool could exist to turn the consolidated
markdown back into markdown+includes+files.
Authors could then re-run their example creation scripts, consolidate the
results back into a single inline markdown file, and send that as a single PR
to update the examples.

I know Carsten is away, but I figure once he reads the above, he'll just
nerdsnipe me, pointing out that there is a --regenerate-includes-files
option, which has been there since 2017 :-)


--
Michael Richardson <[e-mail]>   . o O ( IPv6 IøT consulting )
           Sandelman Software Works Inc, Ottawa and Worldwide

**       My working hours and your working hours may be different.         **
** Please do not feel obligated to reply outside your normal working hours **