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

On Tue, Aug 07, 2018 at 07:14:05AM -0600, Jonathan Corbet wrote:

On Tue, 7 Aug 2018 12:48:44 +1000
"Tobin C. Harding" [off-list ref] wrote:

quoted

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)

That can certainly work; just don't call it foo.rst until it actually is a
valid RST file.

And, of course, go easy with the later steps and try to avoid the
temptation to mark up everything; we really want to preserve the
readability of the plain-text files.

Yeah I get over zealous sometimes, I'll keep it in mind.

What is the current view on references embedded in the text versus a
local label with the full reference at the bottom of the file.  I've
seen both and do not know which is _more_ readable?


1.	some random text referencing
	:ref:`Documentation/path/to/file.rst <label>` and more text
	

2.	some random text referencing `file`_ and more text
	...

	.. Links
	.. _file path/to/file.rst:


Although the later form is found in Documentation/ it does not seem work
for local build (since the path is relative) or am I doing something
wrong with my local build?

And for the first form I could not get the html link produced to work if
the <label> was omitted - this label seems superfluous if it is to the
top of the file (I've already added a couple of such labels).

These are minor issues, answer only if and when you have time.


thanks,
Tobin.