initial checkin
authorEdgar Bering <ebering@csclub.uwaterloo.ca>
Fri, 1 Aug 2008 03:49:50 +0000 (23:49 -0400)
committerEdgar Bering <ebering@csclub.uwaterloo.ca>
Fri, 1 Aug 2008 03:49:50 +0000 (23:49 -0400)
holy-fuck-a-shell.pod [new file with mode: 0644]
outline [new file with mode: 0644]

diff --git a/holy-fuck-a-shell.pod b/holy-fuck-a-shell.pod
new file mode 100644 (file)
index 0000000..7af4ba3
--- /dev/null
@@ -0,0 +1,358 @@
+=head1 Welcome to Unix
+
+Welcome to the unix environment. Here you have the familiar point
+and click gui, but thats not why you're reading this, you're here for
+the shell. So what is this mysterious shell you've been told about by
+upper year students? It is a command line interface to your computer.
+Where the gui is like pointing and grunting the shell is using language.
+A beginner might not do much better than pointing and grunting, but with
+practice one can control a computer with the skill of a poet.
+
+=head2 A few useful keys before we begin
+
+As you've probably guessed the shell is a command line interface that
+you type into. Its essentially an interactive programming language,
+like the interactions window in DrScheme, but designed to operate on
+the system and work in a rather diverse environment. Its also designed
+for convinence, and as you'll discover quite powerful. Before we get
+started there are a few keystrokes you'll need to be aware of.
+
+First, commands that you type in edit just like a line of text, you can
+scroll back and forth, use home and end keys, delete and backspace, etc.
+However its only one line, so the obvious question is what do up and down
+do? Well, they scroll back and foreward in your I<command history>, a log
+of everything you've done previous. Say you want to re-do something, just
+press up until the command you want re-appears. You can make small changes
+if you like, and if you go to far or want to get back to a blank line just
+scroll back down with the down arrow.
+
+If you want to view your command history use the command C<history>. To run
+an old command type C<!number> where number is the number next to the 
+command in history.
+
+Most shells also provide tab completion of commands and file names, to
+use this just press tab after typing part of a file path or command, as long
+as its unique. If its not the shell will show you all the possibilities.
+
+=head2 Getting to the Shell
+
+There are several ways to access the shell remotely and locally. Remote
+shells can be obtained by connecting to a server with a program called
+Secure Shell or ssh. If you're local to a linux or unix system just start
+any of the many terminal programs.
+
+=head3 From Windows
+
+There are several utilities that can provide access to ssh from Windows, 
+the main one used by people at Waterloo is PuTTY 
+L<http://www.chiark.greenend.org.uk/~sgtatham/putty/>.
+
+=for commentary
+
+ebering doesn't like writing about windows, someone else can do this shit
+
+=cut
+
+=head3 From Mac OSX
+
+Mac OS X comes with X11 (more on X11 later) installed, and with X11 comes
+a unix shell with most of the features discussed here, including an 
+ssh client. To access the student environment open X11 and open a terminal and
+use ssh just like in the linux section. You can also use many of the non
+student environment commands on your mac.
+
+=head3 From Linux
+
+To connect to the student environment from linux just start a terminal program
+and use ssh like on a mac, ssh will be documented in its own section. Also
+most of the things in this guide are useable on your local terminal as well.
+
+=head3 ssh(1) 
+
+The ssh utility is invoked from your local command line like this
+
+ $ssh username@hostname
+
+At this point you will be prompted for your password. For the student.cs
+environment hostname is student.cs.uwaterloo.ca or just student.cs from
+inside the network. Your user name is your quest id.
+
+=head4 ssh keys (optional)
+
+ssh can be configured to log in automatically without prompting you for your
+password using cryptographic keys to authenticate. To set this up do the 
+following:
+
+ $ssh-keygen -t dsa
+ Generating public/private dsa key pair.
+ Enter file in which to save the key (~/.ssh/id_dsa): 
+ Enter passphrase (empty for no passphrase): 
+ Enter same passphrase again: 
+ Your identification has been saved in ~/.ssh/id_dsa.
+ Your public key has been saved in ~/.ssh/id_dsa.pub.
+ The key fingerprint is:
+ <some numbers> user@host
+ $ssh-keygen -t rsa
+ Generating public/private rsa key pair.
+ Enter file in which to save the key (~/.ssh/id_rsa): 
+ Enter passphrase (empty for no passphrase): 
+ Enter same passphrase again: 
+ Your identification has been saved in ~/.ssh/id_rsa.
+ Your public key has been saved in ~/.ssh/id_rsa.pub.
+ The key fingerprint is:
+ <some numbers> user@host
+ $scp ~/id*.pub user@host:~/ 
+ user@host's password: 
+ id_rsa.pub
+ id_dsa.pub
+ $ssh user@host
+ user@host's password:
+ user@host$cat ~/id_rsa.pub >> ~/.ssh/authorized_keys
+ user@host$cat ~/id_dsa.pub >> ~/.ssh/authorized_keys
+
+This is optional and more detail can be found in the man page. More
+on those next...
+
+=head2 Getting Help
+
+Now that you can log in easily (or at least login if you skipped the section on 
+keys) you're probably wondering what you can do, we'll get to that, but first 
+a way to get help beyond this guide. For most commands (which are just 
+programs) the authors often include manual or man pages (the good ones anyway) 
+documenting how to use the program. To access this information use the C<man> 
+command like this:
+
+ $man <command name>
+
+There are also manual entries on various system calls and program libraries, 
+configuration files, and system daemons. These are in different numbered 
+sections, type C<man man> for more information.
+
+=head2 Thats all well and good, what can I do?
+
+Like we said earlier, the shell can be used to command a computer. So anything 
+you could do in graphical programs you can do on the shell and more. Many shell 
+tools don't translate well to pointing and clicking, just like its hard to read 
+a poem to a caveman. Commands don't function in a vaccum though, they take 
+input a variety of ways. The first is standard input, normally attached to your 
+keyboard (but it can be moved around), the second is command line arguments and 
+flags. Arguments are just placed after the command, and the man page can 
+explain which flags are avaiable and how to use them. Two common ones are 
+C<--help> and C<--verbose> which have obvious functions. The third input method 
+is reading from various files, some specified on the command line some searched 
+for by default.
+
+We'll start with some basic file tools and command and control abilities.
+
+=head2 The file system and what to do about it
+
+Programs are just files on disk and manipulate data which is also on the disk, 
+so it obviously follows that the most important programs are the ones for 
+working with files on the disk. This section will go over the filesystem and 
+these important programs.
+
+=head3 The filesystem is organized into directories
+
+The file system in the unix environment starts with C</> or the root, different 
+drives are all attached as directories under the root. For now don't worry 
+about drives and lets chat about directories. In unix everything as a running 
+or "working" directory, including your shell prompt. To see what your current 
+directory is use the B<p>rint B<w>orking B<d>irectory command C<pwd> at the 
+prompt. This will give you the I<absolute path> to your working directory. Any 
+I<relative paths> you specify will be relative to this location. To go 
+somewhere else use the B<c>hange B<d>irectory command C<cd> followed by the 
+path you wish to change to. With no arguments it takes you to your home 
+directory. The path specified can be relative or absolute.
+
+=over
+
+=item I<absolute paths>
+
+Absolute paths are specified starting from the system root and look like 
+C</this/path/is/absolute>. Absolute paths are important when working with 
+other people or when going somewhere completely different on the filesystem, 
+really anywhere precision is needed.
+
+=item I<relative path>
+
+Relative paths are specified relative to your (or a program's) current working 
+directory and are just like they sound. They start without a C</> (remember 
+that C</> specifies the system root) and otherwise work exactly the same. There 
+are a few special directories that can be used in relative paths, the first is 
+C<.> which stands for the current directory. The second is C<..> which is the 
+directory above the current directory. Here are some examples:
+
+ $pwd
+ /home/user
+ $cd /etc/games
+ $pwd
+ /etc/games
+ $cd ../config
+ $pwd
+ /etc/config
+ $cd network/
+ $pwd
+ /etc/config/netowrk
+ $cd ..
+ $pwd
+ /etc/config
+ $cd ./network
+ $pwd
+ /etc/config/network
+
+=back
+
+Which directories exist isn't set in stone, you B<r>eB<m>ove B<dir>ectories 
+with the C<rmdir> command, and B<m>aB<k>e them with C<mkdir>. C<rmdir> takes an 
+existing path and removes the directory (you can't remove one with anything in 
+it). C<mkdir> takes a valid path and makes a directory.
+
+Paths may seem confusing, but they are a rather straightforeward way of 
+specifying both directory locations and filenames. How do you specify a filename 
+you ask? Just like a directory. If you're in C</path/to> and want a file called 
+C<afile> all you need to do is write C<afile>. If you're somewhere else you can 
+get to it absolutely C</path/to/afile> or use any of the other things mentioned 
+in path specification to name it.
+
+=head3 Files, they're people too
+
+Speaking of files, you probably want to see them. The first step to seeing 
+files is seeing where they are, the command for this is the B<l>iB<s>t command 
+C<ls>, which shows the files in your current directory, as well as directories. 
+C<ls> might be set up for colour coded output, it might not be, the man page 
+can explain how to set that up. C<ls> also has a B<l>ong format, viewed using 
+C<ls -l>, which provides a lot of useful information about the files listed. 
+Again the man pages can give you more information.
+
+Now that you know the names of your files you might want to actually get at 
+their contents. The simplest way is C<cat> which takes a file name and spits 
+out the contents to the screen. This is nice for short files, but you can't
+scroll back. Two commands that give you a little more control are C<head> 
+and C<tail> which display the start and end of files. C<tail> is particularly 
+useful in watching log files using the B<f>ollow flag C<-f>, which watches the 
+file for updates and displays the new entries as they appear. A third way to 
+view files, which is perahps the most convinient, is something known as a 
+I<pager> program. There are many pagers, this author's favorite is C<less>, 
+which takes a filename argument and lets you scroll up and down as well as 
+search. To search in less type C</> followed by what you're looking for. To 
+find more matches press C<n> to go foreward and C<N> to go back. In less 
+C</> actually takes a pattern, to learn about those check the man pages or 
+the text manipulation and editing tutorial.
+
+You might be asking how to create files now. Lots of programs create files 
+as output, there are logs, data files, random crap, so what you probably 
+want is a way to edit text. Thats easy, use C<pico> or C<nano> for simple 
+command like editors. However these editors are rather simple and lack power, 
+for a full introduction to the vast text editing capabilities refer to the 
+text manipulation and editing tutorial.
+
+Files can also be B<m>oB<v>ed around, B<c>oB<p>ied and B<r>eB<m>oved. The 
+commands C<mv> and C<cp> do moving and copying, taking the original filename 
+as the first argument and the destination as the second. If the second is a 
+directory then the filename is kept the same and the file is placed in that 
+directory, if a name is specified then the file will be moved or copied to 
+the new name. C<rm> removes files given to it as arguments, as many as you 
+like.
+
+=head3 Your home folder (theres no place like it)
+
+When specifying paths there is another special character C<~>, which is short 
+for your home directory. Your home directory is exactly what it sounds like, 
+your place on the file system to keep your crap. If you use C<cd> without an 
+argument it will take you to your home dir. Whats in your home dir? Well, any 
+files you want to keep. Is that it? No, also kept in your homedir are so-called 
+"dot files" since their filenames start with a C<.> so they don't normally show 
+up in C<ls>, to view them use the B<a>ll option for C<ls>, C<-a>. These dot 
+files store configuration information for various programs, as well as B<r>un 
+B<c>ommands files with commands to be run on startup of various applications. 
+You can edit these to customise your various preferences for applications, but 
+consult the man pages first to make sure you enter sane values.
+
+Also in your home folder is your web folder, usually called C<www> or 
+C<public_html>, depending on the configuration of the system. To set up a 
+personal web page all you have to do is place your html (or text or whatever) 
+files in there and make sure they are world readable. Word Readable? What? 
+Its a permission, subject of the next section.
+
+=head3 File permissions, or how to keep people out of your crap.
+
+In unix every file has an owner, these owners are the users, and an owning
+group, which is some group that the owner is a member of. You can control who 
+can read, write, and execute your files based on these categories: user, group, 
+everyone. Collectively these permissions are known as the file's 
+(or directory's) I<mode>. To view a file's mode use a long listing with 
+C<ls -l> and look at the I<mode string>. Mode strings are 10 characters, the 
+first character specifies if the file is a file with a C<-> or something 
+special, like a directory C<d> or a character device like a terminal with C<c>. 
+Following the file type are nine characters, they represent the 3 permissions 
+for the 3 groups, the first three characters stand for B<r>ead, B<w>rite, and 
+eB<x>ecute for the user, and repeat for the group and everyone. For example 
+C<-rw-r-r> provides the owner read-write access and everyone else.
+
+To B<ch>ange B<mod>es, B<own>er, or B<gr>ouB<p> of a file use the commands 
+C<chmod>,C<chown>, and C<chgrp> (actually C<chown> can also change groups). 
+We won't go into C<chown> since only the superuser (a user with more permissions 
+than normal, for administrative purposes) can use it. To use C<chmod> to change 
+modes first pass in a mode alteration followed by files you own. A mode 
+alteration has the form C<w[+,-]p> where C<w> stands for who the mode change is 
+for, B<u>ser owning the file, B<g>roup, B<o>thers, or B<a>ll groups, followed a 
+C<+> to grant the permission or a C<-> to revoke it, and C<p> stands for the 
+ability to change, B<r>ead, B<w>rite, or eB<x>ecute.
+
+You may be wondering about the execute permission. This grants people the 
+ability to run your files, if you have binaries or executable scripts to 
+permission. Depending on the programs you might want to be careful with this. 
+On directories, where executing makes little sense it is the permission to 
+traverse or change into the directory.
+
+=head3 Talking about more than one file at a time
+
+Often its useful to talk about a group of files (like to tell C<rm> about them, 
+or backup your website with C<cp>). The shell has a way to do this. Using a 
+wildcard C<*> you can name all files that match a patern, for example C<*.mp3> 
+would be all mp3s in a folder. Multiple wildcards can be used in a single name, 
+but note they don't match C</>, that is they don't traverse directories. There is
+also the C<?> wildcard which matches any one character.
+
+Specific characters can also be matched using C<[..]> with the characters or a
+range of characters (say C<[a-z]> to match all lowercase) to match. Note that
+this only matches once, so for repeats you must repeat your bracket expression.
+
+For more information on this matching/expansion, which is called 
+I<file globbing> consult C<man 7 glob> (there will probably also be an entry
+in section 3 of the system manual for glob. This is for a C library function
+that actually works out the list of files from the glob expression).
+
+If you want to specify a C<*>, C<?> or C<[> you must escape it with a C<\>,
+and to get a literal C<\> you must escape that as well, using C<\\> in its
+place. There are a few other characters that must be escaped: a space,
+C<">, C<'>, and C<;> for reasons that may or may not be obvious now, but 
+will be after the next section.
+
+=for commentary
+
+A section on searching for files (even if its just a blurb) would be
+nice...
+
+=cut
+
+=head2 What the shell really gives you.. power.
+
+Up until now we've only really covered features that you can find in your
+familiar point and click environment. Going back to the language analogy
+think of that as boring vocabulary work and whats about to be covered
+grammar, rhyme, and meter work. This section discusses the features of the
+shell that separate it from the gui, the programmable loops, variables that
+affect program execution, and io redirection. This section describes the
+machinary the shell provides to put words together to form ideas.
+
+=for commentary
+
+Now I have to write this fucking section. Subsections:
+Jobs and controlling them
+Variables, Environment Variables
+IO Redirection and the Pipe
+Loops and conditionals
+Scripts and arguments for them
+
+=cut
diff --git a/outline b/outline
new file mode 100644 (file)
index 0000000..85684e6
--- /dev/null
+++ b/outline
@@ -0,0 +1,4 @@
+1) holy fuck you have a shell
+2) documents, editing, spellchecking, printing
+3) code project management, vim and emacs plugins, make and vcs techniques from a directory with e-mailed patches to git/svning
+4) communicating with other people, e-mail and newsgroups, procmail, mailing patches