Roland Hieber <rhi@xxxxxxxxxxxxxx> 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@xxxxxxxxxxxxxx> 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
