forked from pifty/tutes-dump
You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
450 lines
20 KiB
HTML
450 lines
20 KiB
HTML
<style type="text/css">
|
|
@import url('http://sdf.org/tutorials/tutorials.css');
|
|
</style>
|
|
|
|
<main>
|
|
<h1>SDF Tutorial Editing Guide</h1>
|
|
|
|
<!-- table o' contents -->
|
|
<ul>
|
|
<li><a href="#intro">Introduction</a></li>
|
|
<li><a href="">Creating and Editing Tutorials</a>
|
|
<ul>
|
|
<li><a href="#create-tutorial">Creating a New Tutorial</a></li>
|
|
<li><a href="#edit-tutorial">Editing an Existing Tutorial</a></li>
|
|
<li><a href="#edit-faq">Editing the FAQs</a></li>
|
|
</ul></li>
|
|
<li><a href="#coding">Coding A Tutorial</a>
|
|
<ul>
|
|
<li><a href="#before-you-code">Before You Start Coding!</a></li>
|
|
<ul>
|
|
<li><a href="#using-images">Using Images</a></li>
|
|
<li><a href="#citing-references">Citing References</a></li>
|
|
<li><a href="#which-html">Which HTML Version?</a></li>
|
|
</ul>
|
|
<li><a href="#coding-style">Coding Style</a></li>
|
|
<li><a href="#template">Tutorial Template</a></li>
|
|
</ul></li>
|
|
<!-- Hopefully this is forthcoming...
|
|
<li><a href="#writing-tips">On Writing Tutorials</a></li>
|
|
-->
|
|
</ul>
|
|
|
|
<h2 id="intro">Introduction</h2>
|
|
<blockquote>
|
|
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.<br> — From
|
|
the <cite>README.TXT</cite>
|
|
</blockquote>
|
|
|
|
<p>This guide has been introduced to help members more easily
|
|
contribute to the SDF Tutorials project. The <a href="#rcs">first
|
|
section</a> of the guide gives brief instructions for creating or
|
|
editing tutorial files using <abbr title="Revision Control
|
|
System">RCS</abbr> for version control. The <a href="#coding">second
|
|
part</a> of the guide discusses tutorial-specific HTML coding and
|
|
contains some template code.<!-- The <a href="#writing">final part</a> of
|
|
the guide gives some pointers on writing style.</p> -->
|
|
|
|
<p>It would behoove you to read the original <code>README.TXT</code> of
|
|
the SDF Tutorials Project in the tutorial files directory
|
|
(<code>/sys/html/tutorials</code>). 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.</p>
|
|
|
|
<p>This guide assumes knowledge of basic shell use and text file
|
|
editing. Familiarity with HTML is not necessary, though it may prove
|
|
helpful.</p>
|
|
|
|
<h2 id="rcs">Creating and Editing Tutorials</h2>
|
|
|
|
<p>To create or edit a tutorial, change your working directory to <code>/sys/html/tutorials</code> in your shell on the main SDF cluster (e.g. sdf.org, not MetaArray):</p>
|
|
|
|
<pre><samp>$ cd /sys/html/tutorials</samp></pre>
|
|
|
|
<h3 id="create-tutorial">Creating a New Tutorial</h3>
|
|
|
|
<p>Inside the tutorials directory, you can use <code>echo</code> to
|
|
quickly create an empty HTML file with an RCS Id tag at the bottom.
|
|
Use the <code>umask</code> command first to make sure that the
|
|
permissions on the new file will allow the web server (and other
|
|
users) to read it.</p>
|
|
|
|
<pre><samp>$ umask 022
|
|
$ echo -e "\n\$Id\$" > <var>your_tutorial_filename.html</var>
|
|
</samp></pre>
|
|
|
|
<p>Use the command <code>ci -u</code> to check-in the file with RCS
|
|
and leave it unlocked it so that anyone can edit it.</p>
|
|
|
|
<pre><samp>$ ci -u <var>your_tutorial_filename.html</var></samp></pre>
|
|
|
|
<p>The first time you check-in a file, you will be asked for a
|
|
description of it. Please write something useful.</p>
|
|
|
|
<p>You may now edit your tutorial using the instructions in
|
|
the <a href="#edit-tutorial">next section</a> to check the file in and
|
|
out of RCS.</p>
|
|
|
|
<p>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 <code>index.html</code> file in the tutorials
|
|
directory to do this. When editing the <code>index.html</code> file,
|
|
use the same check-in/check-out procedure that you do when editing a
|
|
tutorial.</p>
|
|
|
|
<h3 id="edit-tutorial">Editing an Existing Tutorial</h3>
|
|
|
|
<p>Inside the tutorials directory, use the command <code>co -l</code>
|
|
to check out the file with RCS and lock it while you make your edits.</p>
|
|
|
|
<pre><samp>$ co -l <var>filename</var></samp></pre>
|
|
|
|
<p><strong>If when using <code>co -l</code> 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.</strong></p>
|
|
|
|
<p>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 <code>http://sdf.org/?tutorials/<var>filename_without_extension</var></code>
|
|
(e.g., if you are
|
|
editing <code>/sys/html/tutorials/nmap_for_dummies.html</code>, the
|
|
URL will
|
|
be <code>http://sdf.org/?tutorials/nmap_for_dummies</code>).</p>
|
|
|
|
<p>When you are finished editing the file, use the command <code>ci
|
|
-u</code> to check the file back in with RCS and unlock it so that
|
|
others may edit it.</p>
|
|
|
|
<pre><samp>$ ci -u <var>filename</var></samp></pre>
|
|
|
|
<p>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.</p>
|
|
|
|
<h3 id="edit-faq">Editing the FAQs</h3>
|
|
MetaARPA users can also edit the <a href="http://sdf.org/?faq">FAQs</a>. These
|
|
are plain text files, found in <code>/sys/html/tutorials/FAQ/</code>. The list
|
|
of FAQs for each section is in a dotfile '<code>.list</code>'. These FAQ files
|
|
are synced regularly with those shown by the <code>faq</code> command.
|
|
|
|
<h2 id="coding">Coding A Tutorial</h2>
|
|
|
|
<p>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 <a href="#before-you-code">Before You Start
|
|
Coding</a> section for some implementation specifics, and at least skim the <a href="#coding-style">Coding Style</a> section before proceeding.</p>
|
|
|
|
<p>If you are <strong>not</strong> familiar with HTML, the
|
|
<abbr title="World Wide Web Consortium">W3C</abbr> site has a very brief
|
|
tutorial, <a href="http://www.w3.org/MarkUp/Guide/"><cite>Getting
|
|
Started With HTML</cite></a>, which will teach you enough of the
|
|
rudiments to be able to author a tutorial. In addition,
|
|
the <a href="#template">template</a> on this page is furnished with
|
|
ample comments to help HTML beginners.</a></p>
|
|
|
|
<p>If you don't have the time or inclination to learn HTML, you may
|
|
still be able to contribute to the Tutorials Project. Write a tutorial
|
|
(or a section, correction, addendum, etc.) in plain text and tack a
|
|
note in <code>bboard:<TUTORIALS></code>. One of your MetaARPA
|
|
colleagues may just volunteer to HTMLize your work for you.</p>
|
|
|
|
<!-- ================================================ -->
|
|
<h3 id="before-you-code">Before You Start Coding!</h3>
|
|
|
|
<p>SDF tutorial files contain HTML code, but <strong>they are not
|
|
complete HTML documents</strong>. When they are served to web
|
|
browsers, the site's <code>index.cgi</code> wraps them in the
|
|
site-wide navigation header and footer. The code in tutorial files
|
|
represents the contents of a <code><body></code> element,
|
|
and <strong>must not contain</strong> the following elements/tags:</p>
|
|
|
|
<ul>
|
|
<li><code><html>, </html></code>
|
|
<li><code><head>, </head></code>
|
|
<li><code><meta></code>
|
|
<li><code><base></code>
|
|
<li><code><body>, </body></code>
|
|
</ul>
|
|
|
|
<p>Tutorial files will also contain an RCS <b>$Id</b> tag, which will
|
|
look something like: <code>$Id:filename.html,v 1.11 2011/01/01
|
|
11:11:11 username Exp $</code>. There is no need to edit this, as it
|
|
is automatically generated by RCS. It is best to leave it as the last
|
|
line of the file.</p>
|
|
|
|
<!-- ================================= -->
|
|
<h4 id="using-images">Using Images</h4>
|
|
|
|
<p><strong>Do not hotlink images from other sites</strong>. Put a copy
|
|
of any image files you wish to use
|
|
in <code>/sys/html/tutorials/images</code>, and make sure their
|
|
permissions allow the web server to read them (<code>chmod a+r</code>
|
|
will do this).</p>
|
|
|
|
<p><strong>Always provide a description of the image</strong> for
|
|
users of text-based browsers and the visually impaired in
|
|
the <code>alt</code> attribute of the <code><img></code>
|
|
tag.</p>
|
|
|
|
<p>Incorrect:</p>
|
|
|
|
<pre><code><img src="tutorials/images/example.png"></code></pre>
|
|
|
|
<p>Correct:</p>
|
|
|
|
<pre><code><img src="http://sdf.org/tutorials/images/example.png"
|
|
alt="Image of a Blickensderfer No. 5 typewriter"></code></pre>
|
|
|
|
<!-- ================================ -->
|
|
<h4 id="citing-references">Citing References</h4>
|
|
|
|
<p>In the event that you rely heavily upon a source in your
|
|
tutorial, <em>particularly</em> if you use any direct quotations from
|
|
it, you should cite the work properly.</p>
|
|
|
|
<p>Include a heading for "References", or "Notes" in your tutorial
|
|
(typically at the end) and use a numbered list
|
|
(<code><ol></code>) to enumerate your sources in
|
|
the <a href="http://www.chicagomanualofstyle.org/tools_citationguide.html">Chicago
|
|
Style for Notes</a>.</p>
|
|
|
|
<pre><code><h2 id="notes">Notes</h2>
|
|
<ol>
|
|
<li id="bartles">James Bartles, <cite>Boogers For Breakfast</cite>
|
|
(Sacramento: Wine Cooler Press, 1979), 74.</li>
|
|
<li id="moribund">Delron Moribund, "Crossover Calisthenics", <cite>
|
|
Travesties of Better Judgement</cite> 64 (2009): 56-60.</li>
|
|
</ol>
|
|
</code></pre>
|
|
|
|
<p>Then, where the sources are cited in the text of your tutorial, use
|
|
a superscript (<code><sup></code>) number or a number in
|
|
parenthesis hyperlinked to the appropriate list item.</p>
|
|
|
|
<pre><code><p>The secret to a proper nose-goblin ganache is in the picking<sup><a
|
|
href="#bartles">1</a></sup>. (...)</p></code></pre>
|
|
|
|
<p>Or,</p>
|
|
|
|
<pre><code><p>Without adequate stretching beforehand, you are certain to suffer a
|
|
Ludmilian haemorrhage(<a href="#moribund">2</a>). (...)</p></code></pre>
|
|
|
|
<p>There are further examples of this in the <a href="#template">code
|
|
template</a> below.</p>
|
|
|
|
<!-- ================================== -->
|
|
<h4 id="which-html">Which HTML Version?</h4>
|
|
|
|
<p>The current W3C recommendation is <a href="http://www.w3.org/TR/html5/">HTML 5</a>. In most respects, the core elements of HTML haven't changed since the mid 1990s; some tags have been added, and some removed. To maximize backwards compatibility, you might restrict yourself to the following elements, which have gone unchanged since 1996:</p>
|
|
|
|
<ul>
|
|
<li>Structural Elements
|
|
<ul>
|
|
<li><code><h1></code>, ..., <code><h6></code></li>
|
|
</ul>
|
|
</li>
|
|
<li>Grouping/Block-Level Elements
|
|
<ul>
|
|
<li><code><p></code></li>
|
|
<li><code><pre></code></li>
|
|
<li><code><ul></code>,<code><ol></code>, <code><dl></code> and their subordinates</li>
|
|
<li><code><blockquote></code></li>
|
|
<li><code><hr></code></li>
|
|
<li><code><table></code> and its subordinates</li>
|
|
<li>and, of course, <code><div></code>
|
|
</ul>
|
|
</li>
|
|
<li>Text-level/Inline Elements
|
|
<ul>
|
|
<li><code><br></code></li>
|
|
<li><code><a></code></li>
|
|
<li><code><img></code></li>
|
|
<li><code><code></code>, <code><samp></code>, and <code><kbd></code></li>
|
|
<li><code><sup></code> and <code><sub></code></li>
|
|
<li><code><strong></code>, <code><small></code>, and <code><em></code></li>
|
|
<li><code><i></code>, <code><b></code>, <code><u></code>, and <code><s></code></li>
|
|
<li><code><dfn></code>, <code><var></code>, and <code><cite></code></li>
|
|
</ul>
|
|
</ul>
|
|
<p>Many closing tags are optional, but for code clarity they can be
|
|
nice. Stay away from XHTML self-closing tag forms, however
|
|
(ie. <code><br/></code>, <code><hr/></code>, <code><img
|
|
src="some_url"/></code>, et cetera).</p>
|
|
<!-- ================================== -->
|
|
<h3 id="coding-style">Coding Style</h3>
|
|
|
|
<p>You can do <em>a lot</em> with HTML and CSS. You can do even more
|
|
if you throw Javascript into the mix.</p>
|
|
<p>But don't.</p>
|
|
<p>SDF tutorials are a resource for all users, and the means by which
|
|
the tutorials will be accessed are as diverse as the users
|
|
themselves. Some will be reading with text-based browsers over telnet
|
|
connections, some may be disabled and require the use of a
|
|
screen-reader. If your tutorial makes heavy use of CSS or — god
|
|
forbid — Javascript, then you're not taking the needs of all
|
|
users into consideration.</p>
|
|
|
|
<p>Furthermore, the tutorials are a collaborative effort. You may be
|
|
the first author to work on a tutorial, but you probably won't be the
|
|
last. If your tutorial is a hairball of style attributes and
|
|
idiosyncratic tag/element usage, it only makes it harder for the next
|
|
author to edit/expand — particularly if they're not as
|
|
well-versed in web coding as you are.</p>
|
|
|
|
<p><strong>Please try as much as possible to use plain HTML when
|
|
coding tutorials.</strong> Everything you should need to write a clear
|
|
tutorial is already in the language:</p>
|
|
|
|
<ul>
|
|
<li>Structure your tutorial using headings (<code><h1>,<h2>,...,<h6></code>), and stay away from using <code><div></code>s.</li>
|
|
|
|
<li>Use paragraphs (<code><p></code>) for blocks of prose, and preformatted blocks (<code><pre></code>) for source code listings, sample console output, or wherever else whitespace needs to be retained and a monospaced font used.</li>
|
|
|
|
</ul>
|
|
|
|
<p>Rather than use styled <code><span></code> tags or other
|
|
generic grouping elements, use semantic tags which describe the text
|
|
you want to differentiate from body text. If the user's browser
|
|
supports the tag, it will be presented differently. </p>
|
|
|
|
<ul>
|
|
<li>For important text, use <code><strong></code>.
|
|
<li>For emphasis, use <code><em></code>.
|
|
<li>For the names of commands, file names, or source code listings, use <code><code></code>.
|
|
<li>For example console text, use <code><samp></code> inside a <code><pre></code> block.
|
|
<li>And so-on...
|
|
</ul>
|
|
|
|
<p>There is a <a href="http://www.w3.org/TR/html5/text-level-semantics.html#usage-summary">usage summary of text-level semantic elements</a> for the current W3C recommendation (HTML 5). It's handy. Not all tags are supported by all browsers, but a semantically tagged tutorial is more useful — and easier to style — than a document full of custom styled spans.</p>
|
|
|
|
<!-- ============================== -->
|
|
<h3 id="template">HTML Template</h3>
|
|
<p>The code below may be used as a template if you are creating a new tutorial, or re-writing one from scratch. You don't have to use it; it is merely provided as a convenience.</p>
|
|
|
|
<p>The text contained between the <code><!--</code> and <code>--></code> tokens are <i>comments</i>, and may be discarded.</p>
|
|
|
|
<pre><code>
|
|
<i><!-- SDF Tutorial Template
|
|
======================================================================
|
|
Use of this code is entirely optional. It is provided as a sample of
|
|
coding style, and a quick way to start a new tutorial for users who
|
|
may be beginners with HTML. --></i>
|
|
|
|
<style type="text/css">
|
|
@import url('http://sdf.org/tutorials/tutorials.css');
|
|
</style>
|
|
|
|
<i><!-- The title of the tutorial should be the only level-1 header
|
|
(<h1>) in the document. --></i>
|
|
<h1>Title of Tutorial</h1>
|
|
|
|
<i><!-- For longer tutorials, a table of contents is nice. Shorter
|
|
tutorials (like this one) really don't need it, so this section can be
|
|
omitted. Replace the <ul> tags with <ol> tags for a numbered list. --></i>
|
|
<ul>
|
|
<li>
|
|
<a href="#section-1">Section Heading</a>
|
|
<i><!-- to get an indented section of the list, we simply embed a
|
|
list inside of a list item --></i>
|
|
<ul>
|
|
<li>
|
|
<a href="#subsection-1">Subsection Heading</a>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#section-2">Another Section Heading</a></li>
|
|
<li><a href="#notes">Notes</a></li>
|
|
</ul>
|
|
|
|
<i><!-- This is the beginning of a section. It starts with a level-2
|
|
heading (<h2>) and has been given an 'id' attribute so that it may be
|
|
linked to. --></i>
|
|
<h2 id="section-1">Section Heading</h2>
|
|
|
|
<i><!-- Remember to always contain your paragraphs in <p> tags. For
|
|
strings of code, filenames, commands, etc., which appear inside of a
|
|
paragraph, wrap them in <code> tags to differentiate them from the
|
|
rest of the paragraph's text. --></i>
|
|
<p>By issuing the <code>sac -nar</code> command, your spirit animal
|
|
will be changed to the narwhal.</p>
|
|
|
|
<i><!-- For entire blocks of code, place the <code> inside of a <pre>
|
|
instead of a <p>. Text inside of a <pre> has its whitespace characters
|
|
(space, tab, carriage-return) interpreted literally, unlike text
|
|
inside of a <p>. --></i>
|
|
<pre><code>10 PRINT "DO YOU EAT BOOGERS?"
|
|
20 INPUT X
|
|
30 IF X="YES" THEN PRINT "YOU'RE A GOOD MAN, CHARLIE BROWN.": END
|
|
40 IF X="NO" THEN PRINT "WHAT, YOU THINK YOU'RE BETTER THAN ME?"
|
|
</code></pre>
|
|
|
|
<i><!-- For sample program output, console sessions, etc., use <samp>
|
|
inside a <pre> block. --></i>
|
|
<pre><samp>$ finger man@arms
|
|
Login: man Name: Duncan
|
|
Directory: /eternia/heroic_warriors/man Shell: /bin/bashasaurus
|
|
No mail.
|
|
Plan: Make Orko clean-up the mess he left in my workshop.
|
|
</samp></pre>
|
|
|
|
<i><!-- This sub-section begins with a level-3 heading (<h3>). HTML
|
|
provides tags for sections nested six levels deep (tags <h1>
|
|
through <h6>). If you need to nest sections seven or more levels deep
|
|
...you might consider restructuring your tutorial! --></i>
|
|
<h3 id="subsection-1">Subsection Heading</h3>
|
|
|
|
<i><!-- For VERY IMPORTANT TEXT, make it <strong>. To add emphasis to a
|
|
word or phrase, use <em>. --></i>
|
|
<p><strong>Do not forget to flush the buffer</strong>. If you do, the
|
|
smell will be <em>intolerable</em>.</p>
|
|
|
|
<h2 id="section-2">Another Section Heading</h2>
|
|
|
|
<i><!-- This paragraph gives an example of two styles of footnote
|
|
referencing. Both are hyperlinked to corresponding list items (<li>)
|
|
in the Notes section below. --></i>
|
|
<p>The Honeywell 6080 can be induced to perform a samba by pressing
|
|
the button labeled "Samba" on the operator's
|
|
console<a href="#fn1"><sup>1</sup></a>. That mainframe's forté,
|
|
however, is the foxtrot(<a href="#fn2">2</a>), but the inducement of
|
|
that particular step is beyond the scope of this tutorial.</p>
|
|
|
|
<i><!-- Here is a sample footnotes section. In this example, we're using
|
|
footnotes to cite a reference, but this same style can be used for
|
|
footnotes of any kind. Your tutorial may not require any footnotes. If
|
|
it doesn't, feel free to snip this entire section out. --></i>
|
|
<h2 id="notes">Notes</h2>
|
|
|
|
<i><!-- We're using an ordered list (<ol>) so that the notes are
|
|
automatically numbered. A single reference is cited twice in the
|
|
tutorial. As you can see, you may use an abbreviated form of citation
|
|
for subsequent references to a single work. --></i>
|
|
<ol>
|
|
<li id="fn1">Zurgone Vemliat, <cite>Mainframe Dancing Habits</cite>
|
|
(Milwaukie: Brewers' Press, 1988), 96.</li>
|
|
<li id="fn2">Vemliat, <cite>Mainframe</cite>, 112.</li>
|
|
</ol>
|
|
|
|
<i><!-- At the very end, here, is the RCS Id tag. Let it be, my friend. --></i>
|
|
$Id: tutorial_editing.html,v 1.24 2018/08/28 02:39:56 moondoggy Exp $
|
|
|
|
</code></pre>
|
|
|
|
<p>To see how this template looks when rendered, visit <a href="http://sdf.org/?tutorials/tutorial_template"><code>http://sdf.org/?tutorials/tutorial_template</code></a>.</p>
|
|
|
|
<!-- SOMEBODY WRITE THIS SECTION
|
|
<h2 id="writing">Tips on Writing Good Tutorials</h2>
|
|
|
|
<p>*** Write something really good here. ***</p>
|
|
-->
|
|
</main>
|