Updated README.md: Typos, re-wording, formatting.

README.md

@@ -43,27 +43,22 @@ address shown at the top of this file.
 
 Change into picocom's source directory and say:
 
-```
-  make
-```
+    make
 
 This will be enough to compile picocom for most modern Unix-like
 systems. If you want, you can then strip the resulting binary like
 this:
 
-```
-  strip picocom
-```
+    strip picocom
 
 Striping the binary is not required, it just reduces its size by a few
 kilobytes. Then you can copy the picocom binary, as well as the
 man-page, to wherever you put your binaries and man-pages. For
 example:
 
-```
-  cp picocom ~/bin
-  cp picocom.1 ~/man/man1
-```
+
+	cp picocom ~/bin
+	cp picocom.1 ~/man/man1
 
 Again, this is not strictly necessary. You can run picocom and read
 its man-page directly from the source directory. 
@@ -75,19 +70,16 @@ compile-time options and enable or disable some compile-time features
 by commenting in or out the respective lines. Once you edit the
 Makefile, to recompile say:
 
-```
-  make clean
-  make
-```
+
+	make clean
+	make
 
 If your system's default make(1) command is not GNU Make (or
 compatible enough), find out how you can run GNU Make on your
 system. For example:
 
-```
-  gmake clean
-  gmake
-```
+	gmake clean
+	gmake
 
 Alternatively, you might have to make some trivial edits to the
 Makefile for it to work with your system's make(1) command.
@@ -110,30 +102,22 @@ through a device node named `/dev/ttyS0`.
 You can start picocom with its default option values (default serial
 port settings) like this:
 
-```
-  picocom /dev/ttyS0
-```
+	picocom /dev/ttyS0
 
 If you have not installed the picocom binary to a suitable place, then
 you can run it directly from the source distribution directory like
 this:
 
-```
-  ./picocom /dev/ttyS0
-```
+	./picocom /dev/ttyS0
 
 If this fails with a message like:
 
-```
-  FATAL: cannot open /dev/ttyS0: Permission denied
-```
+	FATAL: cannot open /dev/ttyS0: Permission denied
 
 This means that you do not have permissions to access the serial
 port's device node. To overcome this you can run picocom as root:
 
-```
-  sudo picocom /dev/ttyS0
-```
+	sudo picocom /dev/ttyS0
 
 Alternatively, and preferably, you can add yourself to the user-group
 that your system has for allowing access to serial ports. For most
@@ -141,9 +125,7 @@ Unix-like systems this group is called "dialout". Consult you system's
 documentation to find out how you can do this (as it differs form
 system to system). On most Linux systems you can do it like this:
 
-```
-  sudo usermod -a -G dialout username
-```
+	sudo usermod -a -G dialout username
 
 You will need to log-out and then log-in back again for this change to
 take effect.
@@ -153,42 +135,32 @@ desired values using picocom's command line options. For example, to
 set the baud-rate to 115200bps (the default is 9600bps), and enable
 hardware flow-control (RTS/CTS handshake) you can say:
 
-```
-  picocom -b 115200 -f h /dev/ttyS0
-```
+	picocom -b 115200 -f h /dev/ttyS0
 
 or:
 
-```
-  picocom --baud 115200 --flow h /dev/ttyS0
-```
+	picocom --baud 115200 --flow h /dev/ttyS0
 
 To see all available options run picocom like this:
 
-```
-  picocom --help
-```
+	picocom --help
 
 Once picocom starts, it initializes the serial port and prints the
 message:
 
-```
-  Terminal is ready
-```
+	Terminal is ready
 
 From now on, every character you type is sent to the serial port, and
 every character received from the serial port is sent ro your
 terminal.  Including control and special characters. Assuming that
 there is nothing connected to the other end of your serial port, to
-respond to the characters you send it (e.g. echo them back to you),
+respond to the characters you send to it (e.g. echo them back to you),
 then nothing that you type in picocom will appear on your
 terminal. This is normal.
 
 To exit picocom you have to type:
 
-```
-  C-a, C-x
-```
+	C-a, C-x
 
 Which means you have to type [Conttol-A] followed by [Control-X]. You
 can do this by pressing and holding down the [Control] key, then
@@ -205,34 +177,28 @@ Next you should take a look at the very detailed picocom manual
 page. It can be accessed like this (assuming you are inside the
 picocom distribution source directory):
 
-```
-  man ./picocom.1
-```
+	man ./picocom.1
 
 or (assuming you have installed the manual page to a suitable place):
 
-```
-  man picocom
-```
+	man picocom
 
 Thanks for using picocom
 
 ## A low-tech terminal server
 
-You can use picocom to patch-together a very simple, *very low-tech*,
-terminal server.
+You can use *picocom* to patch-together a very simple, *very
+low-tech*, terminal server.
 
-The situation is like this: You have, in your lab, a box with
-several serial ports on it where you connect the console ports of
-embedded devices, development boards, etc. Let's call it
-"termbox". You want to access these console ports remotelly.
+The situation is like this: You have, in your lab, a box with several
+serial ports on it, where you connect the console ports of embedded
+devices, development boards, etc. Let's call it "termbox". You want to
+access these console ports remotely.
 
 If you provide shell-access to termbox for your users, then it's as
 simple as having the users say (from their remote workstations):
 
-```
-  $ ssh -t user@termbox picocom -b 115200 /dev/ttyS0
-```
+	$ ssh -t user@termbox picocom -b 115200 /dev/ttyS0
 
 Or make a convenient script/alias for this. Remember the `-t` switch
 which instructs ssh to create a pseudo-tty, otherwise picocom won't
@@ -241,13 +207,13 @@ work.
 What if you *don't* want to give users shell-access to termbox? Then
 you can use picocom in a setup like the one described below. Just
 remember, there are countless variations to this theme, the one below
-is just one of them.
+is just one of them. Also, keep in mind that some of the commands
+shown below may have small differences from system to system; more so
+if you go from Linux to other Unix-like systems.
 
 Login to termbox and create a user called _termbox_:
 
-```
-  $ sudo useradd -r -m termbox
-```
+	$ sudo useradd -r -m termbox
 
 The `-r` means "system account", and the `-m` means *do* make the
 home-directory. Mostly we need this account's home-directory as a
@@ -257,74 +223,65 @@ password.
 Switch to the _termbox_ account and create a `bin` directory in its
 home-dir.
 
-```
-  $ sudo su termbox
-  $ cd ~
-  $ mkdir bin
-```
+	$ sudo su termbox
+	$ cd ~
+	$ mkdir bin
 
 Copy the picocom binary in `~termbox/bin` (if you don't have it
 globally installed):
 
-```
-  $ cp /path/to/picocom ./bin
-```
+	$ cp /path/to/picocom ./bin
 
 For every serial port you want to provide access to, create a file
 named after the port in `~termbox/bin` which looks like this:
 
-```
-  $ cat ./bin/ttyS0
-  #!/bin/sh
-  exec /home/termbox/bin/picocom \
-      --send-cmd '' \
-      --receive-cmd '' \
-      -b 115200 \
-      /dev/ttyS0
-```
+	$ cat ./bin/ttyS0
+	\#!/bin/sh
+	exec /home/termbox/bin/picocom \
+	  --send-cmd '' \
+	  --receive-cmd '' \
+	  -b 115200 \
+	  /dev/ttyS0
 
 And make it executable:
 
-```
-  $ chmod +x ./bin/ttyS0
-```
+	$ chmod +x ./bin/ttyS0
 
 Repeat accordingly for every other port. Now the contents of
 `~termbox/bin` should look like this:
 
-```
-  $ ls -l ./bin
-  -rwxrwxr-x 1 termbox termbox 102128 Aug 29 13:56 picocom*
-  -rwxrwxr-x 1 termbox termbox    108 Aug 29 14:07 ttyS0*
-  -rwxrwxr-x 1 termbox termbox    108 Aug 29 14:07 ttyS1*
-  ... and so on ...
-```
+	$ ls -l ./bin
+	-rwxrwxr-x 1 termbox termbox 102128 Aug 29 13:56 picocom*
+	-rwxrwxr-x 1 termbox termbox    108 Aug 29 14:07 ttyS0*
+	-rwxrwxr-x 1 termbox termbox    108 Aug 29 14:07 ttyS1*
+	... and so on ...
 
 Exit the _termbox_ account:
 
-```
-  $ exit
-```
+	$ exit
 
 Now, for every serial port, create a user account named after the
 port, like this:
 
-```
-  $ sudo useradd -r -g dialout -M -s ~termbox/bin/ttyS0 ttyS0
-```
+	$ sudo useradd -r -g dialout -d ~termbox -M -s ~termbox/bin/ttyS0 ttyS0
 
 Observe that we make `dialout` the default group for this account, so
 the account has access to the serial ports. Also observe that we make
 the script we just wrote (`~termbox/bin/ttyS0`) the login-shell for
-the account.
+the account. The `-d` option instructs useradd to use `/home/termbox`
+as the user's home directory, and the `-M` switch instructs it *not*
+to create the home-directory. We don't really need a home directory
+for the _ttyS0_ account, since picocom will not read or write any
+files, but we provide one, regardless, because *some* systems need a
+valid home-directory to cd-into on login (else they choke). We could
+as well have used `/` as the home directory, or we could have let
+useradd create the usual `/home/ttyS0`.
 
-Then set a password for it:
+Then set a password for the newly created account:
 
-```
-  $ sudo passwd ttyS0
-  Enter new UNIX password: ******
-  Retype new UNIX password: *****
-```
+	$ sudo passwd ttyS0
+	Enter new UNIX password: ******
+	Retype new UNIX password: ******
 
 Repeat (create user account, set password) for every port you want to
 give access to.
@@ -332,9 +289,7 @@ give access to.
 You 're set. All a user has to do to remotelly access the console on
 termbox's `/dev/ttyS0` port, is:
 
-```
-  ssh ttyS0@termbox
-```
+	ssh ttyS0@termbox
 
 Some interesting points:
 
@@ -358,5 +313,11 @@ Some interesting points:
   *will not* let the user inject shell-commands when supplying
   aditional arguments to them.
 
+- If you allow send- and receive-file operations as described above,
+  you will, most likely, also need a way for your users to put files
+  on termbox, and get files back from it. There are many ways to
+  arrange for this, but they are beyond the scope of this simple
+  example.
+
 Again, this is only *one* possible setup. There are countless other
-variations.
+variations and elaborations you can try. Be creative!