Discussion: showing prompts for interactive/console sessions

[gvwilson]

Should we show REPL prompts (e.g., the $ Bash prompt) when describing interactive sessions?

Pro:

1. I think we need to show prompts when we introduce multi-line commands (for loops).

2. I think we also need to show them when we have two or more users in play (which happens in the Git chapters, where the prompt includes the user ID).

3. I think we should show the prompt for Python/R when we are asking people to work directly in the console rather than writing a script, so that they can more easily track how we're doing things - in this chapter, we don't show the prompt when they are writing a script.

4. Looking at books by O'Reilly, and the original Kernighan et al books, they show the prompt for interactive shell sessions.

Con:

1. Users aren't supposed to type the prompts, so including them may mislead.

2. Including them makes copy/paste more difficult (have to edit out the $).

Thoughts below?

[lwjohnst86]

I disagree with using the prompt. As a non-computer science person and having taught myself R programming (and the shell/git), I remember when I was a novice (and even into being intermediate), I was also really confused about the $. For me it didn't help at all with understanding the material. And I know there are a lot of people like me in my field (biomedicine)... maybe in other fields its different but I very strongly disagree that having a prompt helps at all.

Regarding pro 4... just because others do it doesn't mean we should. I don't think that this point should be a pro, its more of an observation.

For pro 3 (at least for R, can't speak for Python)... nope, definitely we should not have a prompt when teaching R for interactive use. The prompt is a very computer science thing that data analysts will not grasp immediately or even after a while. For showing code for interactive console use, I'd say stating it in text works better. Unless you want to repeatedly remind novice-intermediate learners what you mean when you use the prompt, they will forget! (I did and I'm not unique).

I think pro 2 is the one that makes the most sense for using the prompt. Maybe only for those sessions?

I'd add some other cons:

• It's something else you need to explain. Especially why the shell prompt is $ but R is > and in ipython it is >>> (I think, I don't remember), while in Jupyter Notebook there is no prompt. Explaining what the prompt is conceptually we could do in the beginning, but I don't think we need to use it in every code block.
• It's an additional symbol to remember as a novice. Text explaining where to write the code works just as well and they don't have to remember anything new with words they already know. It's only a symbol to indicate the location of the commands, and it can be confusing because commands are shown in the code block, not symbols. The people I work with on a daily basis are almost entirely novices, and whenever I show them things with prompts, they always confuse them as "important commands you need to include" ... but since they aren't commands "why are they there then?" ... because of historical reasons..? To me that is not a good enough reason.

You can see I have strong opinions about this 😄

Edit: I definitely don't think any of the above pros apply to the git lesson though. Its only interactive, so there is no need to differentiate between script and interactive. Why do we have the prompt there when none of the pros apply?

[joelostblom]

I am also for omitting prompts by default and agree with Luke's points above. I do think it is useful to point out in the text when the prompt changes, e.g. "going from $ to > in a loop means that you can continue typing", or "notice how the name in the prompt changes when you log in as a different user". Same goes for scripts, if we are clear in the text, that is in my opinion a better help than a changing prompt (which might or might not be noticed).

[joelostblom]

And the IPython Console and Jupyter Notebooks also have a prompt, the In [1]: to the left of every line/cell, but I would not consider adding that in each code cell in the book (although I would point out what it means when the number increments or changes to an *)

[ChristinaLK]

I feel most strongly about pro point 3 - distinguishing between files and what's meant to be entered in a console. Which doesn't require a prompt (can do this via color, in the text).

[gvwilson]

Unfortunately the print edition will almost certainly be black and white - color will up the price significantly.

[ChristinaLK]

I guess I was thinking white on black (console) vs black on white (files) but that's not how they're universally used...

Is this for the RSE text or novice text?

[mbonsma]

Regarding Python, I have been confused when roaming internet help pages and encountering the different styles of Python prompt that show up depending on the context (i.e. >>> vs In [1]:), so my comment is more of a question: do the prompt defaults ever change? Is there a danger of a particular prompt becoming obsolete or are they pretty standard for each language?

[joelostblom]

In my experience, the defaults seem to stay the same for any particular shell, but readily change between shells. So unfortunately learning it in one shell does not translate to others, I guess the concept that it can change is the main transferable knowledge (and the R std prompt is the same as bash continuation which might be particularly confusing).

For the ones we're teaching:

Shell	Std prompt	Cont prompt
Bash	$	>
R	>	+
Python	>>>	...
IPython	In [1]:	...:

[gvwilson]

Decision at 2019-11-12's meeting:

1. Ask the publisher.
2. If the publisher doesn't care, run a Twitter poll.

Please upvote/downvote this message or add a comment below.

Email to publisher:

Hi Randi,

I hope you don't mind me asking for guidance, but we're deadlocked on a formatting issue for a book project and I hope you can help. When we are showing people software and its output, we sometimes want to show them an interactive session where they immediately see the results of what they type. One option is to include the prompt that the computer puts up saying it's ready for input:

$ show files

The other is to show only the command:

show files

The argument in favor of including the prompt is that it's an accurate depiction of what the user sees on their screen, and that it makes it easier to distinguish between interactive sessions (with the $ prompt) and non-interactive sessions (code saved in files). The argument against is that people aren't supposed to type the $ themselves, so having it is confusing; that it makes copying and pasting more difficult; and that the line between interactive and non-interactive sessions is blurry these days because of things like the Jupyter Notebook (which is interactive but doesn't use prompts).

Does Taylor & Francis have a rule in its style guide for this? If so, we decided in last night's biweekly meeting that we'll adopt whatever you recommend. If not, we're going to have to resort to a Twitter poll...

Thanks,
Greg

[lwjohnst86]

Good idea. Though if the publisher doesn't have a recommendation, we'll have to be careful which account we send the twitter poll out too, don't want to have too biased a sample. Like @gvwilson, your network probably has a lot of SWC people and its obvious from SWC material which way they would vote (I made an issue long ago to SWC as a learner about the prompt being confusing but I got shot down). Maybe several of us do a twitter poll to our respective audiences we may get a slightly less biased response. But even then, it might not be very representative of what learners care about. Has SWC ever done a survey to learners about it?

Sorry, my scientist and epidemiologist hat makes me very very wary of survey results.

[lwjohnst86]

Looking forward to the response!!

[gvwilson]

Message sent.

[gvwilson]

Response from publisher:

I am afraid we don’t have a specific rule on this. We usually defer to author preference. But, if I were to weigh in, I would suggest it is better to include the prompt the computer puts up ( $ show files) to include a more accurate depiction in the book. However, you may want to go ahead with a Twitter poll on this, to be more democratic.

So, who would like to draft the Twitter poll, because y'all know I'll slant it :-)

[elliewix]

I can try here. I think it would be good to have a few examples mocked up in a markdown file we could link to in the tweet or as a reply. The question prompt is rough, so I think linking off to more info would be best.

"When it comes to usefulness and clarity, what is your opinion on console/script/cell prompts appearing within a programming text(book)?"

• Very important
• Somewhat important
• Somewhat unimportant
• Very unimportant

(here's a mock up I have not posted).

[gvwilson]

Thanks for taking a crack at this: what would you think of taking a slightly different tack and asking when/whether such prompts should appear?

When should prompts like $ and > appear in textbook programming examples?

• Never
• In interactive console sessions only but not when showing programs saved in files
• In both

[elliewix]

This is a bit harsh, but I think could be molded up. I think that it's also erasing the python/R elements of the book. The second option is too long for twitter. Your third option is referencing a definition that only appears within the second option. Here's a tweak:

Should programming textbook examples include prompts like $ and > etc for console/cell sessions and/or programs saved in files? Link for more info: blaaaa.

• Neither case
• Only for console sessions
• In both cases

[lwjohnst86]

I like @elliewix second option so far. Should there be some reference to it being for learners? Otherwise, I know my twitter network (not that its very big 😛) probably wouldn't know what that means or may not answer. I think the nuance indicated in the question will be lost on most people unless they are involved in teaching of programming... The link will include some examples to show the differences?

[elliewix]

Good call.

"Should introductory programming textbook" ?

I should also add a "show the results" or "no opinion/either fine" option.

[joelostblom]

Thanks @elliewix! Minor comment in case you haven't posted already: could you include >>> as well to make it clear we don't only talk about bash (since > could be interpreted as either R or bash by the reader).

[elliewix]

I also added a few to make it clear that I'm not pairing $ and >>> as part of the same console. You wouldn't believe the pedantic tweets I get about clearly Not The Point details like that, but made the list a bit more inclusive.

Great, here's a finalized mockup, I'll tweet it out if I can get three thumbs up within the next 24 hours without any more corrections.

Any comments on how many days to leave the poll open? We could do 7 to leave it open until we have our next meeting.

I'm thinking we could link this issue for more background as needed, and we can post this as a

Look ok?

[SaraMati]

looks great, and leaving it on till our next meeting gives it enough time to be seen.

[gvwilson]

👍 to the wording, but I'd take out the link to this issue (because otherwise we could wind up with a pile of drive-by comments on everything we're doing, not just this question).

[elliewix]

That's fair. Should I just omit a link to more info, or add a reference to this project?

[gvwilson]

I vote for just leaving the link out for now.

[elliewix]

OK, I've got my three thumbs up, so I'm going to post it!

[elliewix]

OK tweet is out: https://twitter.com/elliewix/status/1196519719328718848

[elliewix]

Poll results:

94 votes, Only for console sessions has 64% majority. Neither and both had an even rate, of about 17%.