MetaARPA contributed UNIX, INTERNET and SDF tutorials | 
------------------------------------------------------

ABSTRACT
--------
Many young and very impressionable people discover SDF every day.  They ask
us what we might feel are stupid questions, but it's not their fault.  They've
grown up only knowing that hackers destroy computer networks and exploit
people and their information.  The solution is not to ridicule or shun these 
kiddiots, but to show them that there is a better and truer way.  This
project is meant to be attractive to both people who want to teach and those 
who want to learn.  The target audience is the general public, with little or
no computer skills, to advanced concepts.  And while not all of them will
do so, some will ask you:

 kAn u tell me H4ck my <PERSON HERE>'s <LAME WEBMAIL SERVICE HERE> ACc0unT?

                                - or -

 how can i hack <SOME FAMOUS PRIVATE NETWORK> with this shell?

We don't need to have a condescending attitude and, while parody might be 
fun, we don't need to patronize (or reinforce) this lame behaviour.  What
we should do is take every question seriously, explain in simple language
why that sort of activity is not considered cool and what sort of related
activity is much more interesting.

It might serve the project well to phrase things using the terminology
the newbies are using, correcting or clarifying it where necessary.  One
controversal term that comes to mind is that of a hacker the act of
hacking.   However, I don't recommend that you publish a tutorial 
written entirely in PsyChoChiCkEN .. 

Note about internal information:
Please remember that these files are published on the central SDF
website, and therefore are accessed by a large number of people
and robots as well.  Do not publish information in the tutorials,
which is normally only accessible for internal users (with accounts
on SDF), as this could be a security or spam threat; especially,
do not put up real e-mail addresses, links to normally hidden
scripts, contents of configuration files or similar stuff.

HOW TO
------
First of all, this is a SHARED set of tutorials that are authored and 
edited by the SDF MetaARPA membership.  Just because a user starts a
tutorial doesn't mean they are responsible for all updates.  We are 
using RCS for file locking and version control along with tagging.  The 
files are formatted using HTML and should have a uniform look and feel.  
The directory hiearchy looks like this:

  /sys/html/tutorials/            <-- base directory, contains tutorials
                     /index.html  <-- the main ToC (Table of Contents)
                     /images      <-- images you wish to use in a tutorial
                     /software    <-- PD or shareware downloads
                                      (though it is best to link to sites)
                     /RCS         <-- RCS meta-data files

[FILE CREATION]
To create a tutorial, use your favourite editor using a unique filename
with an .html extension.  Be sure to include a RCS ID tag at the bottom
of your file, which essentially is:  \$Id\$  (take out the backslashes).
Also, make sure the permissions for the file are acceptable for use by
the webserver; ie, "chmod og+r file" or "umask 022" before creating the
file.

Once you have finished editing your first version, save your file and
then run 'ci -u filename' at the shell.  You will be asked for a
description of the file. End with a '.' on a blank line.  This will
add the file to the repository, and leave the file unlocked.

[FILE EDITING]
Editing is open to all MetaARPA members.  Though no formal permission from
the initial author is needed, please be sure that your changes or additions
are necessary or helpful.  Run the 'co -l filename' command at the shell.

  **NOTE** If when using 'co -l' you are told that the file is already locked
           please STOP what you are doing and wait for it to be checked back
           in.  If it does not get checked back in, email the author and
           let them know you want to check out the file and edit it.

This will copy out the file from RCS and allow you to make changes to
it. The command 'rcsdiff filename' will run diff on the file currently
on the filesystem and the most recently checked in version of the file.
See the man pages for other options to rcsdiff.

Once your changes have been made, save your file, double check the
permissions, and then run 'ci -u filename'. It is very important that
you do this and report the changes you've made. The file will be updated
and left unlocked. The file will then be available for others to check
out and revise as needed.

The "check-in" command (ci) prompts users for a "log" of changes made.
These logs are stored and become part of the revision history of a file.
To view these logs type 'rlog filename'.  Some refinement is possible;
see rlog(1) for options.

[ADDING A TOPIC]
Topics are stored in the 'index.html' file.  Please follow the format of the
file when adding a new topic.  Although it is fine to add a new topic while
it is still a draft, it would be best to make sure your tutorial is complete
before actually making it available to readers.  If at some point topics
can be organized into 'chapters' the purpose of the 'index.html' might 
change to be a general table of contents for chapter files (ch?.html).

When linking to a new topic, be sure to use the following syntax in your
href line:  href=http://sdf.lonestar.org/index.cgi?tutorials/YOURTOPICHERE
it is not necessary to include the .html file extension.  What this does is
it allows the standard SDF header menu and footer to be 'wrapped' around
your tutorial page.

[DISCUSSIONS]
Discussions concerning this project should be posted on the bboard:<TUTORIALS>

$Id: README.TXT,v 1.16 2009/01/29 07:39:09 smj Exp $