Message-ID: <20230828135147.sm2zdwwc7j7rfikd@quantum>
Date:   Mon, 28 Aug 2023 08:51:47 -0500
From:   Nishanth Menon <nm@...com>
To:     Jonathan Corbet <corbet@....net>
CC:     Mauro Carvalho Chehab <mchehab@...nel.org>,
        <linux-kernel@...r.kernel.org>, <linux-doc@...r.kernel.org>,
        <bpf@...r.kernel.org>,
        Heinrich Schuchardt <heinrich.schuchardt@...onical.com>,
        Mattijs Korpershoek <mkorpershoek@...libre.com>,
        Simon Glass <sjg@...omium.org>, Tom Rini <trini@...sulko.com>,
        Neha Francis <n-francis@...com>
Subject: Re: [PATCH 1/2] Documentation: sphinx: Add sphinx-prompt

On 07:41-20230828, Jonathan Corbet wrote:
> Nishanth Menon <nm@...com> writes:
> 
> > Hi Jon,
> >
> > On 16:46-20230825, Jonathan Corbet wrote:
> 
> >> So it would sure be nice for the changelog to say what this actually
> >> does.
> >
> > All this does is to bring in a better rendered documentation when
> > published in html format.
> > https://youtu.be/ItjdVa59jjE shows how the "copy-paste" functionality is
> > improved.
> 
> Youtube references aren't a great way to explain the value of a patch;
> you'll find that maintainers will, in general, lack the time or
> inclination to follow them up.  The patch should explain itself.
> 
> >> This appears to add a build dependency for the docs; we can't just add
> >> that without updating the documentation, adjusting
> >> scripts/sphinx-pre-install, and so on.
> >
> > I had checked scripts/shinx-pre-install and that picks up
> > Documentation/sphinx/requirements.txt and installs the dependencies
> > from there using pip. Am I missing something?
> >
> > Same thing with Documentation/doc-guide/sphinx.rst
> >
> > Am I missing something?
> 
> That works, I guess, but doesn't change the fact that you have added
> another docs build dependency.  That will, among other things, break the
> build for anybody who is set up to do it now until they install your new
> package.  That's not something we want to do without good reason.

True, and fair enough.

> 
> >> But, beyond that, this extension goes entirely counter to the idea that
> >> the plain-text files are the primary form of documentation; it adds
> >> clutter and makes those files less readable.  We can do that when the
> >
> > Are you sure this is going against the readable text documentation? If
> > anything it reduces the clutter and allows the text doc to be
> > copy-paste-able as well.
> >
> > https://lore.kernel.org/all/20230824182107.3702766-3-nm@ti.com/
> >
> > As you see from the diffstat:
> >  1 file changed, 10 insertions(+), 10 deletions(-)
> >
> > Nothing extra added. What kind of clutter are you suggesting we added
> > with the change?
> >
> > prompt:: bash $ is clearly readable that this is prompt documentation
> > in fact, dropping the "$" in the example logs, one can easily copy paste
> > the documentation from rst files as well.
> 
> .. prompt:: is clutter.  It also adds a bit of extra cognitive load to
> reading that part of the documentation.

It is no additional cognitive load from what is already there:

-.. code-block:: bash
+.. prompt:: bash $

> 
> Quick copy-paste of multiple lines of privileged shell commands has
> never really been a requirement for the kernel docs; why do we need that
> so badly?

Just hated people who read online documentation from having to spend
extra few seconds in copy pasting and then realizing oops "$" came along
with it.

> 
> I appreciate attempts to improve our documentation, and hope that you
> will continue to do so.  I am far from convinced, though, that this
> change clears the bar for mainline inclusion.

:) OK - I tried.. Thanks for explaining (though I disagree).
-- 
Regards,
Nishanth Menon
Key (0xDDB5849D1736249D) / Fingerprint: F8A2 8693 54EB 8232 17A3  1A34 DDB5 849D 1736 249D

Powered by blists - more mailing lists