I removed the "code-block" directives from the rst files,
and used "::" suggested by Jonathan. The rst files themselves are now
easier to read in vi.  However, the rendered HTML output has some differences:
(1) The text that was previously in code-block no longer indents. It aligns
      with the preceding text, regardless of how many spaces I add.
(2) Previously, "code-block" removed '\' and combined the text into a
single line.
     This is no longer happening -- the '\' is not expanded.

These differences do not seem to be a blocker. I'm attaching the html files to
this email. If there is no objection, I'll change to using the new
method of "::".

-Rong

On Sat, Oct 5, 2024 at 7:43 AM Jonathan Corbet <corbet@lwn.net> wrote:
>
> Kees Cook <kees@kernel.org> writes:
>
> > The tradition in kernel .rst is to do this with the trailing "::", e.g.:
> >
> > +Configure the kernel with::
> > +
> > +     CONFIG_AUTOFDO_CLANG=y
> >
> > This loses the language-specific highlighting when rendered. Perhaps the
> > "::" extension can be further extended?
> >
> > +Configure the kernel with::(make)
> > +
> > +     CONFIG_AUTOFDO_CLANG=y
> >
> > Then we could avoid the extra 2 lines but still gain the rendered language
> > highlights?
>
> The :: notation is standard Sphinx, not an extension we have done.  So
> the proposed syntax would have to be done from the beginning, I'm not
> sure how easy or hard that would be, or whether it would be worth it.
> But then, I've always seen relatively little value in the highlighting;
> others clearly differ.
>
> Thanks,
>
> jon