On Thu, 2026-08-13 at 07:15 -0600, Jonathan Corbet wrote: > Manuel Ebner <[email protected]> writes: > > > The optional tag isn't obvious nor defined. Therefore replace with footnotes > > like the one of Sphinx. > > > > Signed-off-by: Manuel Ebner <[email protected]> > > --- > > .../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
