lists.openwall.net   lists  /  announce  owl-users  owl-dev  john-users  john-dev  passwdqc-users  yescrypt  popa3d-users  /  oss-security  kernel-hardening  musl  sabotage  tlsify  passwords  /  crypt-dev  xvendor  /  Bugtraq  Full-Disclosure  linux-kernel  linux-netdev  linux-ext4  linux-hardening  linux-cve-announce  PHC 
Open Source and information security mailing list archives
 
Hash Suite: Windows password security audit tool. GUI, reports in PDF.
[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Message-ID: <87h6om4u6o.fsf@meer.lwn.net>
Date:   Fri, 25 Aug 2023 16:46:07 -0600
From:   Jonathan Corbet <corbet@....net>
To:     Nishanth Menon <nm@...com>,
        Mauro Carvalho Chehab <mchehab@...nel.org>
Cc:     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>, Nishanth Menon <nm@...com>
Subject: Re: [PATCH 1/2] Documentation: sphinx: Add sphinx-prompt

Nishanth Menon <nm@...com> writes:

> Sphinx-prompt[1] helps bring-in '.. prompt::' option that allows a
> better rendered documentation, yet be able to copy paste without
> picking up the prompt from the rendered documentation.
>
> [1] https://pypi.org/project/sphinx-prompt/
> Link: https://lore.kernel.org/all/87fs48rgto.fsf@baylibre.com/
> Suggested-by: Mattijs Korpershoek <mkorpershoek@...libre.com>
> Suggested-by: Heinrich Schuchardt <heinrich.schuchardt@...onical.com>
> Signed-off-by: Nishanth Menon <nm@...com>
> ---
> I would have added Reported-by for Simon, since he reported the issue in
> the first place.. but it was for the u-boot documentation, so skipping
> here.
>
>  Documentation/conf.py                 | 2 +-
>  Documentation/sphinx/requirements.txt | 1 +
>  2 files changed, 2 insertions(+), 1 deletion(-)

So it would sure be nice for the changelog to say what this actually
does.

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.

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
benefit is sufficient, but I'm pretty far from convinced that this is
the case here.  Certainly the case hasn't been made in the changelog.
What *is* the benefit of making this change?

Thanks,

jon

Powered by blists - more mailing lists

Powered by Openwall GNU/*/Linux Powered by OpenVZ