From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mout-p-101.mailbox.org (mout-p-101.mailbox.org [80.241.56.151]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 43EE639656E; Thu, 13 Aug 2026 14:31:13 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=80.241.56.151 ARC-Seal:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1786631476; cv=none; b=adYDwI5PAf+BwFxHlACkbrqmV88QnUXMWnrCsopnxVeJmnEvsqXpgMVELMIQO31JdXoffGFHYnPCMeuPciLWHMywcxLc2jfkJ/ZUbgXWtT5SsBVO06iBWb+Wxn/vfxyb9GNiEJPRmgLLtE0A7k/PqvmlLIOdyZ0IKKvdrMEwB84= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1786631476; c=relaxed/simple; bh=AaqukwTvvcsBWypfN+zPK9grkVcaWN4UuvP4kQ2j4Lg=; h=Message-ID:Subject:From:To:Cc:Date:In-Reply-To:References: Content-Type:MIME-Version; b=MV3pHtrK6R6UTu3YsFIMrlIli0WHa0IJUTM1pay+ehW/sX//mwwfhskHLRRVMFQ4DiEJqcbHY9NLGWhfjWQmmNzBI7fLvxdYDpOu0tLSTCa3nazbLqO6WiDHt4luXNGffrCNBIgqzOqZQrwxdS8YdkGsGwoSIlWYUS0WeGlYeGo= ARC-Authentication-Results:i=1; smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=mailbox.org; spf=pass smtp.mailfrom=mailbox.org; dkim=pass (2048-bit key) header.d=mailbox.org header.i=@mailbox.org header.b=hRMpNajt; arc=none smtp.client-ip=80.241.56.151 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=mailbox.org Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=mailbox.org Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=mailbox.org header.i=@mailbox.org header.b="hRMpNajt" Received: from smtp102.mailbox.org (smtp102.mailbox.org [10.196.197.102]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange x25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) by mout-p-101.mailbox.org (Postfix) with ESMTPS id 4hLSTT2Z2Zz8vDZ; Thu, 13 Aug 2026 16:31:09 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=mailbox.org; s=mail20150812; t=1786631469; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=7Sn1VIZwryE8kW4E+Ahizg6Crjnd5KmSy/koYSfKmlM=; b=hRMpNajtw9mBHGzZzq8BbGvaDC/55rEhJ83uvvcW9dE/DsmaaMCeD3RgGdt2s/8SsIa7v3 r8F+i+Z2wE1ZaV3ly6CntKCD98WhaTFUHFHq62l6/6BW+4VNvBKhh3AiMwAUfig1dzLFpw xX5+9tBZEw09msdskTPZanV/S0AuXmxaXvrmEb0lMi3CpJjCTg6C86ntSfSO0zlwmVAOQ+ TzSTX+NsyOvRsP2F8LqVtNvJ96ccCOH7NdftBFZRuuEMccGdkS6Qltf0vN5z1S+GVRNAXK 4H6XJIWWPXoi0XT/EgcStYvWybmkq1Qcg3dGQjQ47PpI1Oda+sRBAWtZIyYQLQ== Message-ID: <1e2d501f4da31fe945b839e648044de3501230fe.camel@mailbox.org> Subject: Re: [PATCH 5/5] Docs: software-requirements.rst replace optional tag with footnotes From: Manuel Ebner To: Jonathan Corbet , Shuah Khan , Miguel Ojeda , Boqun Feng , Gary Guo , =?ISO-8859-1?Q?Bj=F6rn?= Roy Baron , Benno Lossin , Andreas Hindborg , Alice Ryhl , Trevor Gross , Danilo Krummrich , Daniel Almeida , Tamir Duberstein , Alexandre Courbot , Onur =?ISO-8859-1?Q?=D6zkan?= , Nathan Chancellor , Nick Desaulniers , Bill Wendling , Justin Stitt Cc: workflows@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, rust-for-linux@vger.kernel.org, llvm@lists.linux.dev Date: Thu, 13 Aug 2026 16:30:55 +0200 In-Reply-To: <87tsoyi2k5.fsf@trenco.lwn.net> References: <20260812120805.1631430-3-manuelebnerli@mailbox.org> <20260812122426.1636227-2-manuelebnerli@mailbox.org> <87tsoyi2k5.fsf@trenco.lwn.net> Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable Precedence: bulk X-Mailing-List: workflows@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 X-MBO-RS-META: wqb37wku7584xmf1hqihzq1iwwxcrzag X-MBO-RS-ID: aed8cf22841651194df On Thu, 2026-08-13 at 07:15 -0600, Jonathan Corbet wrote: > Manuel Ebner writes: >=20 > > The optional tag isn't obvious nor defined. Therefore replace with foot= notes > > like the one of Sphinx. > >=20 > > Signed-off-by: Manuel Ebner > > --- > > =C2=A0.../process/software-requirements.rst=C2=A0=C2=A0=C2=A0=C2=A0=C2= =A0=C2=A0=C2=A0=C2=A0 | 22 ++++++++++++------- > > =C2=A01 file changed, 14 insertions(+), 8 deletions(-) >=20 > Explaining the optionals seems like a fine idea.=C2=A0 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 > =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D >=20 > .. [#f1] This tool is needed to [example use] Or they can be avoided altogether with (optional) tags and with requirement= s 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.=C2=A0 You only need e2fsprogs if you're using ext4.=C2=A0 gdb= only if > you're wanting to run a debugger.=C2=A0 jfsutils seems truly optional, et= c. > 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. > =20 > +Tool(sets) with only a few required uses have a footnote mentioning > +theese. Tools with more uses are elevatet to general requirements. > + > =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D > 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. >=20 > +The Required for row states which type of interaction with the kernel ne= eds > +the software. Multiple entries in one field are possible. If the field i= s 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 > + > +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D > + Program Required for Version Command to check the v= ersion > +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D > +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