On Wed, 16 Mar 2022 15:48:56 -0600 Jonathan Corbet <corbet@xxxxxxx> wrote: > > 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. I agree on both points. Thanks Jon. -- Steve
