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

On Fri,  3 Aug 2018 08:31:00 +1000
"Tobin C. Harding" [off-list ref] 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 <redacted>
---
 .../{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!

 - 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.

 - 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?

Thanks,

jon