Re: [PATCH 1/3] docs: tracing: use refs for cross-referencing

[Jonathan Corbet <corbet@lwn.net>]

Roland Hieber <rhi@pengutronix.de> writes:

> On Sun, Mar 13, 2022 at 07:55:19PM -0400, Steven Rostedt wrote:
>> On Sun, 13 Mar 2022 11:55:55 +0100
>> Roland Hieber <rhi@pengutronix.de> wrote:
>> 
>> > Help cross-linking the documents by using the :ref: role.
>> 
>> Note, I and many other people read the .rst files directly, and do not
>> rely on any processing. Is there a better way to do a cross reference
>> like this, because I find this a bit ugly to read.
>
> The main point of this series was to get rid of the manually numbered
> sections (which the next patch does). Relying on manual section numbers
> for cross-referencing is error-prone, which my first iteration of the
> patch already showed… Unfortunately, the sphinx reST syntax is not very
> flexible here.

I agree on the removal of the numbered sections.  Those always end up
being wrong after a while.

> I could imagine leaving the file names in when a reference points to a
> different document, like in this hunk:
>
>> > -set_ftrace_filter 'ftrace filter commands' (see the 'Filter commands'
>> > -section of Documentation/trace/ftrace.rst), but there are major
>> > +set_ftrace_filter 'ftrace filter commands' (see the section
>> > +:ref:`ftrace_filter_commands`), but there are major

In general, all of those references and labels clutter the source
considerably and aren't hugely useful to readers of the plain-text
documents.  There are times when they are the best thing to do, but I
think that moderation is indicated.  Just giving the file name will
generate a cross-reference to that file; I would hope that would be
enough most of the time.

Thanks,

jon