netdev - Re: [PATCH net] Documentation: netdev-FAQ: make all questions into headings

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20191030090252.7eedec35@cakuba.hsd1.ca.comcast.net>
Date:   Wed, 30 Oct 2019 09:02:52 -0700
From:   Jakub Kicinski <jakub.kicinski@...ronome.com>
To:     Jonathan Corbet <corbet@....net>
Cc:     davem@...emloft.net, netdev@...r.kernel.org,
        oss-drivers@...ronome.com, linux-doc@...r.kernel.org,
        Simon Horman <simon.horman@...ronome.com>
Subject: Re: [PATCH net] Documentation: netdev-FAQ: make all questions into
 headings

On Wed, 30 Oct 2019 02:44:30 -0600, Jonathan Corbet wrote:
> On Tue, 29 Oct 2019 10:12:15 -0700
> Jakub Kicinski <jakub.kicinski@...ronome.com> wrote:
> > -Q: I see a network patch and I think it should be backported to stable.
> > ------------------------------------------------------------------------
> > -Q: Should I request it via stable@...r.kernel.org like the references in
> > -the kernel's Documentation/process/stable-kernel-rules.rst file say?
> > +Q: I see a network patch and I think it should be backported to stable. Should I request it via stable@...r.kernel.org like the references in the kernel's Documentation/process/stable-kernel-rules.rst file say?
> > +------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------  
> 
> I don't think that making these massive heading lines actually improves the
> experience - for readers of either the plain-text or formatted docs.  If
> you really want to create headings, the heading here should be "Stable
> backports" or some such with the question appearing below.  But do the
> questions really need to be headings?

I agree that this is suboptimal. I couldn't come up with a better way
of handling this. I think consistently formatting all questions in one
way and answers in another make the document far easier to interpret.
I had hard time follow the current formatting:

https://www.kernel.org/doc/html/latest/networking/netdev-FAQ.html#q-i-have-created-a-network-patch-and-i-think-it-should-be-backported-to-stable

Is there a more appropriate form of emphasis we could use here? Even
if we add independent headings questions should remain emphasised
_somehow_ I reckon..