tutes-dump/site-tutorials/tutorial_editing.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>  &mdash; 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:&lt;TUTORIALS&gt;</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>&lt;body&gt;</code> element,
and <strong>must not contain</strong> the following elements/tags:</p>

<ul>
<li><code>&lt;html&gt;, &lt;/html&gt;</code>
<li><code>&lt;head&gt;, &lt;/head&gt;</code>
<li><code>&lt;meta&gt;</code>
<li><code>&lt;base&gt;</code>
<li><code>&lt;body&gt;, &lt;/body&gt;</code>
</ul>      

<p>Tutorial files will also contain an RCS <b>&#36;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>&lt;img&gt;</code>
tag.</p>

<p>Incorrect:</p>

<pre><code>&lt;img src="tutorials/images/example.png"&gt;</code></pre>
    
<p>Correct:</p>

<pre><code>&lt;img src="http://sdf.org/tutorials/images/example.png" 
     alt="Image of a Blickensderfer No. 5 typewriter"&gt;</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>&lt;ol&gt;</code>) to enumerate your sources in
the <a href="http://www.chicagomanualofstyle.org/tools_citationguide.html">Chicago
Style for Notes</a>.</p>

<pre><code>&lt;h2 id="notes"&gt;Notes&lt;/h2&gt;
&lt;ol&gt;
  &lt;li id="bartles"&gt;James Bartles, &lt;cite&gt;Boogers For Breakfast&lt;/cite&gt; 
  (Sacramento: Wine Cooler Press, 1979), 74.&lt;/li&gt;
  &lt;li id="moribund"&gt;Delron Moribund, "Crossover Calisthenics", &lt;cite&gt;
  Travesties of Better Judgement&lt;/cite&gt; 64 (2009): 56-60.&lt;/li&gt;
&lt;/ol&gt;
</code></pre>

<p>Then, where the sources are cited in the text of your tutorial, use
a superscript (<code>&lt;sup&gt;</code>) number or a number in
parenthesis hyperlinked to the appropriate list item.</p>

<pre><code>&lt;p&gt;The secret to a proper nose-goblin ganache is in the picking&lt;sup&gt;&lt;a 
  href="#bartles"&gt;1&lt;/a&gt;&lt;/sup&gt;. (...)&lt;/p&gt;</code></pre>

<p>Or,</p>

<pre><code>&lt;p&gt;Without adequate stretching beforehand, you are certain to suffer a 
Ludmilian haemorrhage(&lt;a href="#moribund"&gt;2&lt;/a&gt;). (...)&lt;/p&gt;</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>&lt;h1&gt;</code>, ..., <code>&lt;h6&gt;</code></li>
    </ul>
  </li>
  <li>Grouping/Block-Level Elements
    <ul>
      <li><code>&lt;p&gt;</code></li>
      <li><code>&lt;pre&gt;</code></li>
      <li><code>&lt;ul&gt;</code>,<code>&lt;ol&gt;</code>, <code>&lt;dl&gt;</code> and their subordinates</li>
      <li><code>&lt;blockquote&gt;</code></li>
      <li><code>&lt;hr&gt;</code></li>
      <li><code>&lt;table&gt;</code> and its subordinates</li>
      <li>and, of course, <code>&lt;div&gt;</code>
    </ul>
  </li>
  <li>Text-level/Inline Elements
    <ul>
      <li><code>&lt;br&gt;</code></li>
      <li><code>&lt;a&gt;</code></li>
      <li><code>&lt;img&gt;</code></li>
      <li><code>&lt;code&gt;</code>, <code>&lt;samp&gt;</code>, and <code>&lt;kbd&gt;</code></li>
      <li><code>&lt;sup&gt;</code> and <code>&lt;sub&gt;</code></li>
      <li><code>&lt;strong&gt;</code>, <code>&lt;small&gt;</code>, and <code>&lt;em&gt;</code></li>
      <li><code>&lt;i&gt;</code>, <code>&lt;b&gt;</code>, <code>&lt;u&gt;</code>, and <code>&lt;s&gt;</code></li>
      <li><code>&lt;dfn&gt;</code>, <code>&lt;var&gt;</code>, and <code>&lt;cite&gt;</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>&lt;br/&gt;</code>, <code>&lt;hr/&gt;</code>, <code>&lt;img
src="some_url"/&gt;</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 &mdash; god
forbid &mdash; 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 &mdash; 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>&lt;h1&gt;,&lt;h2&gt;,...,&lt;h6&gt;</code>), and stay away from using <code>&lt;div&gt;</code>s.</li>

  <li>Use paragraphs (<code>&lt;p&gt;</code>) for blocks of prose, and preformatted blocks (<code>&lt;pre&gt;</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>&lt;span&gt;</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>&lt;strong&gt;</code>.
  <li>For emphasis, use <code>&lt;em&gt;</code>.
  <li>For the names of commands, file names, or source code listings, use <code>&lt;code&gt;</code>.
  <li>For example console text, use <code>&lt;samp&gt;</code> inside a <code>&lt;pre&gt;</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 &mdash; and easier to style &mdash; 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>&lt;!--</code> and <code>--&gt;</code> tokens are <i>comments</i>, and may be discarded.</p>

<pre><code>
<i>&lt;!-- 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. --&gt;</i>

&lt;style type="text/css"&gt;
  @import url('http://sdf.org/tutorials/tutorials.css');
&lt;/style&gt;

<i>&lt;!-- The title of the tutorial should be the only level-1 header
(&lt;h1&gt;) in the document. --&gt;</i>
&lt;h1&gt;Title of Tutorial&lt;/h1&gt; 

<i>&lt;!-- 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 &lt;ul&gt; tags with &lt;ol&gt; tags for a numbered list. --&gt;</i>
&lt;ul&gt;
  &lt;li&gt;
    &lt;a href="#section-1"&gt;Section Heading&lt;/a&gt;
    <i>&lt;!-- to get an indented section of the list, we simply embed a
    list inside of a list item --&gt;</i>
    &lt;ul&gt;
      &lt;li&gt;
        &lt;a href="#subsection-1"&gt;Subsection Heading&lt;/a&gt;
      &lt;/li&gt;
    &lt;/ul&gt;
  &lt;/li&gt;
  &lt;li&gt;&lt;a href="#section-2"&gt;Another Section Heading&lt;/a&gt;&lt;/li&gt;
  &lt;li&gt;&lt;a href="#notes"&gt;Notes&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;

<i>&lt;!-- This is the beginning of a section. It starts with a level-2
heading (&lt;h2&gt;) and has been given an 'id' attribute so that it may be
linked to. --&gt;</i>
&lt;h2 id="section-1"&gt;Section Heading&lt;/h2&gt;

<i>&lt;!-- Remember to always contain your paragraphs in &lt;p&gt; tags. For
strings of code, filenames, commands, etc., which appear inside of a
paragraph, wrap them in &lt;code&gt; tags to differentiate them from the
rest of the paragraph's text. --&gt;</i>
&lt;p&gt;By issuing the &lt;code&gt;sac -nar&lt;/code&gt; command, your spirit animal
will be changed to the narwhal.&lt;/p&gt;

<i>&lt;!-- For entire blocks of code, place the &lt;code&gt; inside of a &lt;pre&gt;
instead of a &lt;p&gt;. Text inside of a &lt;pre&gt; has its whitespace characters
(space, tab, carriage-return) interpreted literally, unlike text
inside of a &lt;p&gt;. --&gt;</i>
&lt;pre&gt;&lt;code&gt;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?"
&lt;/code&gt;&lt;/pre&gt;

<i>&lt;!-- For sample program output, console sessions, etc., use &lt;samp&gt;
inside a &lt;pre&gt; block. --&gt;</i>
&lt;pre&gt;&lt;samp&gt;$ 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.
&lt;/samp&gt;&lt;/pre&gt;

<i>&lt;!-- This sub-section begins with a level-3 heading (&lt;h3&gt;). HTML
provides tags for sections nested six levels deep (tags &lt;h1&gt;
through &lt;h6&gt;). If you need to nest sections seven or more levels deep
...you might consider restructuring your tutorial! --&gt;</i>
&lt;h3 id="subsection-1"&gt;Subsection Heading&lt;/h3&gt;

<i>&lt;!-- For VERY IMPORTANT TEXT, make it &lt;strong&gt;. To add emphasis to a
word or phrase, use &lt;em&gt;. --&gt;</i>
&lt;p&gt;&lt;strong&gt;Do not forget to flush the buffer&lt;/strong&gt;. If you do, the
smell will be &lt;em&gt;intolerable&lt;/em&gt;.&lt;/p&gt;

&lt;h2 id="section-2"&gt;Another Section Heading&lt;/h2&gt;

<i>&lt;!-- This paragraph gives an example of two styles of footnote
referencing. Both are hyperlinked to corresponding list items (&lt;li&gt;)
in the Notes section below. --&gt;</i>
&lt;p&gt;The Honeywell 6080 can be induced to perform a samba by pressing
the button labeled "Samba" on the operator's
console&lt;a href="#fn1"&gt;&lt;sup&gt;1&lt;/sup&gt;&lt;/a&gt;. That mainframe's fort&eacute;,
however, is the foxtrot(&lt;a href="#fn2"&gt;2&lt;/a&gt;), but the inducement of
that particular step is beyond the scope of this tutorial.&lt;/p&gt;

<i>&lt;!-- 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. --&gt;</i>
&lt;h2 id="notes"&gt;Notes&lt;/h2&gt;

<i>&lt;!-- We're using an ordered list (&lt;ol&gt;) 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. --&gt;</i>
&lt;ol&gt;
  &lt;li id="fn1"&gt;Zurgone Vemliat, &lt;cite&gt;Mainframe Dancing Habits&lt;/cite&gt; 
  (Milwaukie: Brewers' Press, 1988), 96.&lt;/li&gt;
  &lt;li id="fn2"&gt;Vemliat, &lt;cite&gt;Mainframe&lt;/cite&gt;, 112.&lt;/li&gt;
&lt;/ol&gt;
 
<i>&lt;!-- At the very end, here, is the RCS Id tag. Let it be, my friend. --&gt;</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>