[PATCH net] docs: netdev-FAQ: add missing underlines to questions

[PATCH net] docs: netdev-FAQ: add missing underlines to questions

[Baruch Siach]

Signed-off-by: Baruch Siach <baruch@tkos.co.il>
---
 Documentation/networking/netdev-FAQ.rst | 18 +++++++++++-------
 1 file changed, 11 insertions(+), 7 deletions(-)

diff --git a/Documentation/networking/netdev-FAQ.rst b/Documentation/networking/netdev-FAQ.rst
index 4b9ed5874d5a..4ef90fe26640 100644
--- a/Documentation/networking/netdev-FAQ.rst
+++ b/Documentation/networking/netdev-FAQ.rst
@@ -82,6 +82,7 @@ focus for ``net`` is on stabilization and bug fixes.
 Finally, the vX.Y gets released, and the whole cycle starts over.
 
 Q: So where are we now in this cycle?
+-------------------------------------
 
 Load the mainline (Linus) page here:
 
@@ -108,6 +109,7 @@ with.
 Q: I sent a patch and I'm wondering what happened to it?
 --------------------------------------------------------
 Q: How can I tell whether it got merged?
+----------------------------------------
 A: Start by looking at the main patchworks queue for netdev:
 
   https://patchwork.kernel.org/project/netdevbpf/list/
@@ -124,8 +126,8 @@ bottom of the priority list.
 
 Q: I submitted multiple versions of the patch series
 ----------------------------------------------------
-Q: should I directly update patchwork for the previous versions of these
-patch series?
+Q: should I directly update patchwork for the previous versions of these patch series?
+--------------------------------------------------------------------------------------
 A: No, please don't interfere with the patch status on patchwork, leave
 it to the maintainer to figure out what is the most recent and current
 version that should be applied. If there is any doubt, the maintainer
@@ -171,8 +173,8 @@ simply clone the repo, and then git grep the mainline commit ID, e.g.
 
 Q: I see a network patch and I think it should be backported to stable.
 -----------------------------------------------------------------------
-Q: Should I request it via stable@vger.kernel.org like the references in
-the kernel's Documentation/process/stable-kernel-rules.rst file say?
+Q: Should I request it via stable@vger.kernel.org like the references in the kernel's Documentation/process/stable-kernel-rules.rst file say?
+---------------------------------------------------------------------------------------------------------------------------------------------
 A: No, not for networking.  Check the stable queues as per above first
 to see if it is already queued.  If not, then send a mail to netdev,
 listing the upstream commit ID and why you think it should be a stable
@@ -192,8 +194,8 @@ be avoided.
 
 Q: I have created a network patch and I think it should be backported to stable.
 --------------------------------------------------------------------------------
-Q: Should I add a Cc: stable@vger.kernel.org like the references in the
-kernel's Documentation/ directory say?
+Q: Should I add a Cc: stable@vger.kernel.org like the references in the kernel's Documentation/ directory say?
+--------------------------------------------------------------------------------------------------------------
 A: No.  See above answer.  In short, if you think it really belongs in
 stable, then ensure you write a decent commit log that describes who
 gets impacted by the bug fix and how it manifests itself, and when the
@@ -234,12 +236,14 @@ it is requested that you make it look like this::
 Q: I am working in existing code that has the former comment style and not the latter.
 --------------------------------------------------------------------------------------
 Q: Should I submit new code in the former style or the latter?
+--------------------------------------------------------------
 A: Make it the latter style, so that eventually all code in the domain
 of netdev is of this format.
 
 Q: I found a bug that might have possible security implications or similar.
 ---------------------------------------------------------------------------
-Q: Should I mail the main netdev maintainer off-list?**
+Q: Should I mail the main netdev maintainer off-list?
+-----------------------------------------------------
 A: No. The current netdev maintainer has consistently requested that
 people use the mailing lists and not reach out directly.  If you aren't
 OK with that, then perhaps consider mailing security@kernel.org or
-- 
2.29.2

Re: [PATCH net] docs: netdev-FAQ: add missing underlines to questions

[Jakub Kicinski]

On Tue, 15 Dec 2020 19:18:19 +0200 Baruch Siach wrote:
> Signed-off-by: Baruch Siach <baruch@tkos.co.il>
> ---
>  Documentation/networking/netdev-FAQ.rst | 18 +++++++++++-------
>  1 file changed, 11 insertions(+), 7 deletions(-)
> 
> diff --git a/Documentation/networking/netdev-FAQ.rst b/Documentation/networking/netdev-FAQ.rst
> index 4b9ed5874d5a..4ef90fe26640 100644
> --- a/Documentation/networking/netdev-FAQ.rst
> +++ b/Documentation/networking/netdev-FAQ.rst
> @@ -82,6 +82,7 @@ focus for ``net`` is on stabilization and bug fixes.
>  Finally, the vX.Y gets released, and the whole cycle starts over.
>  
>  Q: So where are we now in this cycle?
> +-------------------------------------
>  
>  Load the mainline (Linus) page here:
>  
> @@ -108,6 +109,7 @@ with.
>  Q: I sent a patch and I'm wondering what happened to it?
>  --------------------------------------------------------
>  Q: How can I tell whether it got merged?
> +----------------------------------------

I think this and the following fixes should be folded into a single
line (unless it's possible in RST for header to span multiple lines):

I sent a patch and I'm wondering what happened to it - how can I tell whether it got merged?
--------------------------------------------------------------------------------------------

To be honest I think we can also drop the Q: and A: prefixes now that
we're using RST.

And perhaps we can add an index of questions at the beginning of the
the file?

Re: [PATCH net] docs: netdev-FAQ: add missing underlines to questions

[Baruch Siach]

Hi Jakub,

On Thu, Dec 17 2020, Jakub Kicinski wrote:
> On Tue, 15 Dec 2020 19:18:19 +0200 Baruch Siach wrote:
>> Signed-off-by: Baruch Siach <baruch@tkos.co.il>
>> ---
>>  Documentation/networking/netdev-FAQ.rst | 18 +++++++++++-------
>>  1 file changed, 11 insertions(+), 7 deletions(-)
>> 
>> diff --git a/Documentation/networking/netdev-FAQ.rst b/Documentation/networking/netdev-FAQ.rst
>> index 4b9ed5874d5a..4ef90fe26640 100644
>> --- a/Documentation/networking/netdev-FAQ.rst
>> +++ b/Documentation/networking/netdev-FAQ.rst
>> @@ -82,6 +82,7 @@ focus for ``net`` is on stabilization and bug fixes.
>>  Finally, the vX.Y gets released, and the whole cycle starts over.
>>  
>>  Q: So where are we now in this cycle?
>> +-------------------------------------
>>  
>>  Load the mainline (Linus) page here:
>>  
>> @@ -108,6 +109,7 @@ with.
>>  Q: I sent a patch and I'm wondering what happened to it?
>>  --------------------------------------------------------
>>  Q: How can I tell whether it got merged?
>> +----------------------------------------
>
> I think this and the following fixes should be folded into a single
> line (unless it's possible in RST for header to span multiple lines):
>
> I sent a patch and I'm wondering what happened to it - how can I tell whether it got merged?
> --------------------------------------------------------------------------------------------
>
> To be honest I think we can also drop the Q: and A: prefixes now that
> we're using RST.
>
> And perhaps we can add an index of questions at the beginning of the
> the file?

Sphinx creates side bar index of the questions in the HTML version. See

  https://www.kernel.org/doc/html/latest/networking/netdev-FAQ.html

Other formats provide other index methods.

baruch

-- 
                                                     ~. .~   Tk Open Systems
=}------------------------------------------------ooO--U--Ooo------------{=
   - baruch@tkos.co.il - tel: +972.52.368.4656, http://www.tkos.co.il -

Re: [PATCH net] docs: netdev-FAQ: add missing underlines to questions

[Jakub Kicinski]

On Sun, 20 Dec 2020 10:29:12 +0200 Baruch Siach wrote:
> > I think this and the following fixes should be folded into a single
> > line (unless it's possible in RST for header to span multiple lines):
> >
> > I sent a patch and I'm wondering what happened to it - how can I tell whether it got merged?
> > --------------------------------------------------------------------------------------------
> >
> > To be honest I think we can also drop the Q: and A: prefixes now that
> > we're using RST.
> >
> > And perhaps we can add an index of questions at the beginning of the
> > the file?  
> 
> Sphinx creates side bar index of the questions in the HTML version. See
> 
>   https://www.kernel.org/doc/html/latest/networking/netdev-FAQ.html
> 
> Other formats provide other index methods.

Interesting. It doesn't render the questions in that bar when I build
locally with make htmldocs. But I see it on kernel.org, so I guess
that's what matters most.