Re: [PATCH 1/2] Documentation: sphinx: Add sphinx-prompt

[Mauro Carvalho Chehab]

Em Mon, 28 Aug 2023 09:12:07 -0600
Jonathan Corbet <corbet@xxxxxxx> escreveu:

> Matthew Wilcox <willy@xxxxxxxxxxxxx> writes:
> 
> > On Mon, Aug 28, 2023 at 07:41:39AM -0600, Jonathan Corbet wrote:  
> >> 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.  
> >
> > I'd ask that you reconsider.  Looking at patch 2, I prefer what is
> > written there.  I don't think it adds cognitive load when reading the
> > plain docs.  I find the "copy and paste from html" argument not very
> > convincing, but I do like "copy and paste from rst", which this enables.  
> 
> Do you really think that the benefit from that justifies adding a build
> dependency and breaking everybody's docs build until they install it?  I
> rather suspect I would hear back from people who feel otherwise if I did
> that... 

I agree with Jon: it needs at least a patch for scripts/sphinx-pre-install.
Adding dependencies there is not the easiest thing to do, as one needs to
test the change against all supported distros to ensure that the new package
name will be the same everywhere. Also, if I'm not mistaken, some developers
don't want to use pip to install packages, wanting instead to have the
distro-provided package.

Also, having an extra build dependency will surely break already-existing
CI automation. Making the new dependency optional would be a way to go,
but this will cause troubles at the html output after such change.

> > I also have a certain fond memory of how the plan9 people set up 'rc'
> > (their shell) so that ";" was both an empty statement, and the default
> > prompt.  So you could copy-paste lines starting with the ; prompt and
> > they'd work.  It's a small usabillity improvement, but it is there,
> > and wow is it annoying when you don't have it any more.  
> 
> Ah, OK, so what we really need is a bash patch :)

Probably the hardest part would be to do copy-and-paste on places
where there are both shell prompt commands and their results. I'm
pretty sure we have things like:

	some example::

		$ run_some_command
		comand results line 1
		comand results line 2
		comand results line 3
		...
		comand results line n

		$ run_another_command

does sphinx-prompt handle things like that, placing just:

	run_some_command
	run_another_command

at the paste buffer, ignoring any command result lines?

IMO, the above described usease is where having a prompt will help
to identify what should be copied/pasted and what are the command
results. I mean, if someone wants to just place the commands to
run, he could write, instead:

	Run those shell commands to do something::

		run_some_command
		run_another_command


Regards,
Mauro