Re: [RFC bpf-next v2 3/3] docs: Split filter.txt into separate documents.

[Tobin C. Harding]

On Fri, Aug 03, 2018 at 07:08:18AM -0600, Jonathan Corbet wrote:
> On Fri,  3 Aug 2018 08:31:00 +1000
> "Tobin C. Harding" <me@xxxxxxxx> wrote:
> 
> > In preparation for conversion of Documentation/networking/filter.txt it
> > was noticed that the document contains a lot of information.  The
> > document may be more accessible if it was split up.  Some parts pertain
> > to everyone, let's put these bits in core-api/.  The more hard core bits
> > about eBPF internals could be put with the other BPF docs in
> > Documentation/bpf/.  There is a small bit of information on testing and
> > miscellaneous matters that are useful for everyone (everyone does
> > testing, right) so lets keep that info at the bottom of both new
> > documents.  (This includes the original authors.)
> > 
> > Split Documentation/networking/filter.txt into
> > Documentation/bpf/eBPF.rst and Documentation/core-api/bpf.rst
> > 
> > Signed-off-by: Tobin C. Harding <me@xxxxxxxx>
> > ---
> >  .../{networking/filter.txt => bpf/eBPF.rst}   | 590 +----------------
> >  Documentation/core-api/bpf.rst                | 599 ++++++++++++++++++
> 
> Some overall thoughts...
> 
>  - A good step in the right direction, and worthwhile work.  Thanks for
>    doing this!

Thanks for you thoughts Jon.

>  - The new eBPF.rst file is not actually an RST file.  Giving it that
>    extension while not converting the contents will confuse Sphinx.  I'd
>    call it .txt at this point.

I'm a bit stumped as the best way to structure a patch set that does

	foo.txt -> foo.rst

conversion.  FTR the conditions I'm trying to meet are:

1. Each patch should be discreet and leave the kernel in a _correct_
   state.
2. One thing per patch.
3. Maintainers should be able to take the first 'n' patches without
   taking the whole set.

How about these steps:

	1. start with foo.txt
	2. do typo and grammar fixes (any number of patches).
	3. rename to foo.rst, do whitespace changes, code snippet
	   indentation, heading adornments, update references to this file.
	   (single patch).
	4. Fix up references in the file text to use RST (i.e :ref: blah)
	5. Fix up RST markers (backticks etc). (any number of patches)

Any better ideas or further suggestions?  I like 4 and 5 separate since
they can be done in multiple ways so may be controversial.

>  - The document now known as core-api/bpf.rst is still covering two
>    separate things.  One is the socket-filter API, while the other is
>    classic BPF.  Since cBPF is still used elsewhere (seccomp), it's of
>    wider interest.  Also, this is user-space API stuff, not kernel API
>    stuff, so I think that Documentation/userspace-api/ is the right place
>    for it.
> 
> I'm kind of thinking this through as I type it, but I guess I'm arguing
> for the creation of three files, all in Documentation/userspace-api/:
> 
>  - socket-filter.rst on how to write socket filters
>  - cBPF.rst describing classic BPF and its tools
>  - eBPF.rst describing extended BPF
> 
> Tying cBPF.rst into seccomp_filter.rst could also be helpful for our
> readers.
> 
> Does this make sense?

Yep, that all makes sense.  Patch set to come.

thanks,
Tobin.