[ SDF Public Access UNIX System .. Est. 1987 ]

join welcome faq status members store tour gopher abuse dialup minecraft
social tilde europa webmail gallery usermap irc tutorials telnet git ssh

SDF HTML Tutorial Editing Guide

The instructions that follow are for creating and editing HTML-based user-contributed tutorials. To contribute to the SDF tutorial wiki, see SDF Tutorial Wiki

Table of Contents

Introduction

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.
— From the README.TXT

This guide has been introduced to help members more easily contribute to the SDF HTML Tutorials project. The first section of the guide gives brief instructions for creating or editing tutorial files using RCS for version control. The second part of the guide discusses tutorial-specific HTML coding and contains some template code.

It would behoove you to read the original README.TXT of the SDF HTML Tutorials Project in the tutorial files directory (/sys/html/tutorials). It not only expresses the aim of the project, but it also contains more detailed information on the use of RCS than is given here.

This guide assumes knowledge of basic shell use and text file editing. Familiarity with HTML is not necessary, though it may prove helpful.

Creating and Editing Tutorials

To create or edit a tutorial, change your working directory to /sys/html/tutorials in your shell on the main SDF cluster (e.g. sdf.org, not MetaArray):

$ cd /sys/html/tutorials

Creating a New Tutorial

Inside the tutorials directory, you can use echo to quickly create an empty HTML file with an RCS Id tag at the bottom. Use the umask command first to make sure that the permissions on the new file will allow the web server (and other users) to read it.

$ umask 022
$ echo -e "\n\$Id\$" > your_tutorial_filename.html

Use the command ci -u to check-in the file with RCS and leave it unlocked it so that anyone can edit it.

$ ci -u your_tutorial_filename.html

The first time you check-in a file, you will be asked for a description of it. Please write something useful.

You may now edit your tutorial using the instructions in the next section to check the file in and out of RCS.

Once your tutorial is ready for public display, please add it to the list of available tutorials so people can actually find it on the web. You must edit the index.html file in the tutorials directory to do this. When editing the index.html file, use the same check-in/check-out procedure that you do when editing a tutorial.

Editing an Existing Tutorial

Inside the tutorials directory, use the command co -l to check out the file with RCS and lock it while you make your edits.

$ co -l filename

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. You can see the latest author by running rlog filename, which will tell you which user has checked out the file (run man rlog for more details on its use).

You may now edit the file using your preferred text editor. If you save your work periodically, you can load and reload the tutorial in your web browser to see your changes. The URL for the tutorial file will be http://sdf.org/?tutorials/filename_without_extension (e.g., if you are editing /sys/html/tutorials/nmap_for_dummies.html, the URL will be http://sdf.org/?tutorials/nmap_for_dummies).

When you are finished editing the file, use the command ci -u to check the file back in with RCS and unlock it so that others may edit it.

$ ci -u filename

When you check-in a file, you will be asked to describe the changes you've made to it. Be as terse as you like, but please write something useful.

Undoing Edits Before Checking In

If, after editing a file, you wish to not check in your changes and revert to the version without your changes, simply run a checkout with an un-lock, similar to how you checked out before:

$ co -u filename

You may get a warning asking if you want to remove write privileges on the file--you *do*, so say "yes". This will reload the previous version of the file to the current folder and unlock it so others can make changes again. If you wish to try again, use the same step as above.

Editing the FAQs

MetaARPA users can also edit the FAQs. These are plain text files, found in /sys/html/tutorials/FAQ/. The list of FAQs for each section is in a dotfile '.list'. These FAQ files are synced regularly with those shown by the faq command.

Coding A Tutorial

Tutorials are coded using HTML. If you are already handy with HTML, then you are just moments away from editing your tutorial! Please read the Before You Start Coding section for some implementation specifics, and at least skim the Coding Style section before proceeding.

If you are not familiar with HTML, the W3C site has a very brief tutorial, Getting Started With HTML, which will teach you enough of the rudiments to be able to author a tutorial. In addition, the template on this page is furnished with ample comments to help HTML beginners.

If you don't have the time or inclination to learn HTML, you may still be able to contribute to the Tutorials Project.


©1987-2065 SDF Public Access UNIX System, Inc. 501(c)(7)
(this page was generated using ksh, sed and awk)