From mboxrd@z Thu Jan  1 00:00:00 1970
From: "Tobin C. Harding" <me@tobin.cc>
Subject: Re: [RFC bpf-next v2 3/3] docs: Split filter.txt into separate
 documents.
Date: Wed, 8 Aug 2018 09:19:52 +1000
Message-ID: <20180807231951.GD11191@eros>
References: <20180802223100.26236-1-me@tobin.cc>
 <20180802223100.26236-4-me@tobin.cc>
 <20180803070818.3d3e52e4@lwn.net>
 <20180807024844.GW3088@eros>
 <20180807071405.58d38277@lwn.net>
Mime-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Cc: Daniel Borkmann <daniel@iogearbox.net>,
        Alexei Starovoitov <ast@kernel.org>,
        "David S. Miller" <davem@davemloft.net>, linux-doc@vger.kernel.org,
        netdev@vger.kernel.org, linux-kernel@vger.kernel.org
To: Jonathan Corbet <corbet@lwn.net>
Return-path: <linux-kernel-owner@vger.kernel.org>
Content-Disposition: inline
In-Reply-To: <20180807071405.58d38277@lwn.net>
Sender: linux-kernel-owner@vger.kernel.org
List-Id: netdev.vger.kernel.org

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" <me@tobin.cc> wrote:
> 
> > 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.