Re: [PATCH 5/5] Docs: software-requirements.rst replace optional tag with footnotes

[Manuel Ebner <manuelebnerli@mailbox.org>]

On Thu, 2026-08-13 at 07:15 -0600, Jonathan Corbet wrote:
> Manuel Ebner <manuelebnerli@mailbox.org> writes:
> 
> > The optional tag isn't obvious nor defined. Therefore replace with footnotes
> > like the one of Sphinx.
> > 
> > Signed-off-by: Manuel Ebner <manuelebnerli@mailbox.org>
> > ---
> >  .../process/software-requirements.rst         | 22 ++++++++++++-------
> >  1 file changed, 14 insertions(+), 8 deletions(-)
> 
> Explaining the optionals seems like a fine idea.  I'm a bit less
> convinced about the mess of footnotes.

Maybe footnotes can be reused when adding more to the list like this:

> bash [#f1]_            4.2              bash --version
> bc [#f1]_              1.06.95          bc --version
> bindgen [#f1]_         0.71.1           bindgen --version
> ====================== ===============  ========================================
> 
> .. [#f1] This tool is needed to [example use]

Or they can be avoided altogether with (optional) tags and with requirements
in the paragraphs below. bindgen is already like this.
For me that's the fallback option.

> Especially since many of the entries that are *not* marked as optional
> really are.  You only need e2fsprogs if you're using ext4.  gdb only if
> you're wanting to run a debugger.  jfsutils seems truly optional, etc.
> Even GCC is optional if you're using Clang.

I came up with the idea today to limit optional:
>     ...
>  you probably do not need to concern yourself with pcmciautils.
>  
> +Tool(sets) with only a few required uses have a footnote mentioning
> +theese. Tools with more uses are elevatet to general requirements.
> +
> ====================== ===============  ========================================
>         Program        Minimal version       Command to check the version
>     ...


> I'm not sure what would be best...perhaps replace the --version field
> (which people can figure out) with an explanation of when each
> dependency would be needed?

This could work out, it's the widest field.

An initial idea was to add a row and keys like this:
>  ...
>  you probably do not need to concern yourself with pcmciautils.
> 
> +The Required for row states which type of interaction with the kernel needs
> +the software. Multiple entries in one field are possible. If the field is empty
> +this means it is to complicated to describe with this key and you should get the
> +software just in case.
> +
> +Key
> +---
> +Ch change code     Do documentation    Co compile          I  install
> +Bo boot            Bu bug hunting      A  analyze          M  misc
> +De debugging       U  use beyond boot
> +
> +=============  ================ =============  =================================
> +   Program       Required for       Version       Command to check the version
> +=============  ================ =============  =================================
> +bash           I, M                  4.2              bash --version

I ditched this idea because the table would have been to cluttered and it's a lot
of work to choose keys for each tools.

> jon

Thanks and please advice
 Manuel