Command prompt is unclear for new users

[ekohl]

trafficstars

Issue description

A lot of students run into the problem that the command line convention is not clear. We do explain it in the intro to command line, but maybe this should be done earlier or more explicit. Still many girls type in the entire thing including the output.

Language

English

Operating system

Windows, Linux

[ekohl]

To clarify: if Introduction to the Command line was before Installation, it would be clearer for users.

[YaKsenia]

There are two actual problems with command line that students face:

1. They type in the Terminal commands with the dollar sign at the beginning ('$). It would be better to emphasize at the beginning of the tutorial that they should not include it into a command. It could also help if you explain at the beginning the error ($: command not found) with explicit explanation why they get it and how to get rid of it.

2. They don't understand the difference between input and output in the tutorial. So they copy output and try to use it as a command in the Terminal. Input and output should be specified explicitly, better even with graphics.

For instance:

INPUT (you have to type the following line in your Terminal):

python3 --version

OUTPUT (don't type this, it is the result you should get after you typed the command):

Python 3.6.1

POSSIBLE ERROR

$: command not found

How to fix it: You probably used the command with a dollar sign at the beginning ('$'). So you should use the same command, but remove this sign (e . g. replace this python3 --version with this "python3 --version").

[nikhiljohn10]

Is there a way for users to not select the $ sign in gitbook? I have no clue how gitbook works. But I think this should be possible somehow.

Check this code https://jsfiddle.net/derek_shnosh/e7khwn1r

In that example, prompt is not selectable or copied. So the user understands that $ is not suppose to be copied.

[das-g]

Check this code https://jsfiddle.net/derek_shnosh/e7khwn1r

more minimal example: https://jsfiddle.net/qcv9z6ns/1/

I have no clue how gitbook works. But I think this should be possible somehow.

HonKit, the software we now use to render the tutorial, has some theming possibilities. Maybe these can be used to produce the required HTML and CSS? If not, there's also the possibility to create plugins that can probably do all kinds of modifications to the output.

[ekohl]

This looks like a plugin that does something similar with replacements: https://github.com/wikiti/gitbook-plugin-code-captions/blob/master/index.js

[sergei-maertens]

adding extra explanation or moving the introduction is too much for students to grasp and yet another thing to remember - I would really advocate for removing all shell prefixes everywhere, becaues:

• currently they are not consistent - dollar signs are shown as example for windows shells (cmd, PS) so there's no recognition
• windows promps have a whole path section prefix, and users have their own username. they need to make the mental User -> <actualUsername> replacement which is more mental overload
• copy pasting happens whether you like it or not, let's not create a frustrating experience for those people that decide to copy-paste