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

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" [off-list ref] wrote:

quoted

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!

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.
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html