Differences

This shows you the differences between two versions of the page.

--- sdf_tutorial_editing_guide [2021/03/11 18:21] – updated intro becuase we are in the wiki peteyboy
+++ sdf_tutorial_editing_guide [2025/03/06 18:27] (current) – [Original Tutorial Site Editing] clean text, changed link to authoring page peteyboy
@@ Line 2: / Line 2: @@
 ===== Original Tutorial Site Editing =====
-This information is not for this wiki, but for the older, straight-HTML based SDF Tutorial pages, accessible via https://sdf.org/?tutorials
-You can more easily add to and edit [[start| this wiki]], but if you want to add to or update the other tutorials that haven't been migrated to the wiki yet, you may follow the directions below!
+:!: This tutorial is //not for editing this wiki//, but for the older, [[rcs|RCS]]-versioned straight-HTML-based SDF Tutorial pages, accessible via https://sdf.org/?tutorials
+You can easily [[wiki_authoring|contribute to this wiki]], but if you want to add to or update the HTML tutorials instead, you may follow the directions below!
 ===== 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 Tutorials project. The [[#creating_and_editing_tutorials|first section]] of the guide gives brief instructions for creating or editing tutorial files using RCS for version control. The [[#coding_a_tutorial|second part]] of the guide discusses tutorial-specific HTML coding and contains some template code.
+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 Tutorials project. The [[#creating_and_editing_tutorials |first section]] of the guide gives brief instructions for creating or editing tutorial files using RCS for version control. The [[#coding_a_tutorial |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 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.
@@ Line 27: / Line 29: @@
 ==== 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.
+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.
 <code>
@@ Line 46: / Line 48: @@
 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 [[#editing_an_existing_tutorial|next section]] to check the file in and out of RCS.
+You may now edit your tutorial using the instructions in the [[#editing_an_existing_tutorial |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.
@@ Line 60: / Line 62: @@
 </code>
-**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.**
+**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.** The way to figure this out is to run ''rlog <filename>'', which will tell you which user has checked out the file (run ''man rlog'' for more details on its use). On the flip side of this, **be sure you check in and unlock any file you change** when you are done making your changes (see commands for checking back in below).
 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'').
@@ Line 73: / Line 75: @@
 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.
+If you want to see what has been changed, you may use the ''rcsdiff'' command. Type ''man rcsdiff'' for details. Mostly you just need the ''-r'' flag, and you can run ''rlog'' to see what the recent version numbers are.
 ==== Editing the FAQs ====
-MetaARPA users can also edit the [[http://sdf.org/?faq|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.
+MetaARPA users can also edit the [[http://sdf.org/?faq |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|Before You Start Coding]] section for some implementation specifics, and at least skim the [[#coding_style|Coding Style]] section before proceeding.
+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 |Before You Start Coding]] section for some implementation specifics, and at least skim the [[#coding_style |Coding Style]] section before proceeding.
-If you are **not** familiar with HTML, the W3C site has a very brief tutorial, [[http://www.w3.org/MarkUp/Guide/|Getting Started With HTML]], which will teach you enough of the rudiments to be able to author a tutorial. In addition, the [[#html_template|template]] on this page is furnished with ample comments to help HTML beginners.
+If you are **not** familiar with HTML, the W3C site has a very brief tutorial, [[http://www.w3.org/MarkUp/Guide/ |Getting Started With HTML]], which will teach you enough of the rudiments to be able to author a tutorial. In addition, the [[#html_template |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. Write a tutorial (or a section, correction, addendum, etc.) in plain text and tack a note in ''bboard:<TUTORIALS>''. One of your MetaARPA colleagues may just volunteer to HTMLize your work for you.
-==== Before You Start Coding! ====
+===== Before You Start Coding! =====
 SDF tutorial files contain HTML code, but **they are not complete HTML documents**. When they are served to web browsers, the site's ''index.cgi'' wraps them in the site-wide navigation header and footer. The code in tutorial files represents the contents of a ''<body>'' element, and **must not contain** the following elements/tags:
@@ Line 98: / Line 103: @@
 Tutorial files will also contain an RCS **$Id** tag, which will look something like: ''$Id:filename.html,v 1.11 2011/01/01 11:11:11 username Exp $''. 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.
-=== Using Images ===
+==== Using Images ====
 **Do not hotlink images from other sites**. Put a copy of any image files you wish to use in ''/sys/html/tutorials/images'', and make sure their permissions allow the web server to read them (''chmod a+r'' will do this).
@@ Line 119: / Line 124: @@
 </code>
-=== Citing References ===
+==== Citing References ====
 In the event that you rely heavily upon a source in your tutorial, //particularly// if you use any direct quotations from it, you should cite the work properly.
-Include a heading for "References", or "Notes" in your tutorial (typically at the end) and use a numbered list (''<ol>'') to enumerate your sources in the [[http://www.chicagomanualofstyle.org/tools_citationguide.html|Chicago Style for Notes]].
+Include a heading for “References”, or “Notes” in your tutorial (typically at the end) and use a numbered list (''<ol>'') to enumerate your sources in the [[http://www.chicagomanualofstyle.org/tools_citationguide.html |Chicago Style for Notes]].
 <file config References or Notes>
@@ Line 137: / Line 142: @@
 </file>
-Then, where the sources are cited in the text of your tutorial, use a superscript (''<sup >'') number or a number in parenthesis hyperlinked to the appropriate list item.
+Then, where the sources are cited in the text of your tutorial, use a superscript ( ''<nowiki><sup></nowiki>'' ) number or a number in parenthesis hyperlinked to the appropriate list item.
 <file config Superscript >
@@ Line 155: / Line 160: @@
 </file>
-There are further examples of this in the [[#html_template|code template]] below.
+There are further examples of this in the [[#html_template |code template]] below.
-=== Which HTML Version? ===
+==== Which HTML Version? ====
-The current W3C recommendation is [[http://www.w3.org/TR/html5/|HTML 5]]. 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:
+The current W3C recommendation is [[http://www.w3.org/TR/html5/ |HTML 5]]. 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:
   * Structural Elements
-    * ''<h1>'', ..., ''<h6>''
+    * ''<h1>'', …, ''<h6>''
   * Grouping/Block-Level Elements
     * ''<p>''
@@ Line 176: / Line 181: @@
     * ''<img>''
     * ''<code>'', ''<samp>'', and ''<kbd>''
-    * ''<sup >'' and ''<sub>''
+    * ''<nowiki><sup></nowiki>'' and ''<sub>''
     * ''<strong>'', ''<small>'', and ''<em>''
     * ''<i>'', ''<b>'', ''<u>'', and ''<s>''
@@ Line 183: / Line 188: @@
 Many closing tags are optional, but for code clarity they can be nice. Stay away from XHTML self-closing tag forms, however (ie. ''<br/>'', ''<hr/>'', ''<img src="some_url"/>'', et cetera).
-==== Coding Style ====
+===== Coding Style =====
 You can //do a lot// with HTML and CSS. You can do even more if you throw Javascript into the mix.
@@ Line 189: / Line 194: @@
 But don't.
-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.
+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.
-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.
+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.
 **Please try as much as possible to use plain HTML when coding tutorials.** Everything you should need to write a clear tutorial is already in the language:
-  * Structure your tutorial using headings (''<h1>,<h2>;,...,<h6>''), and stay away from using ''<div>''s.
+  * Structure your tutorial using headings (''<h1>,<h2>;,…,<h6>''), and stay away from using ''<div>''s.
   * Use paragraphs (''<p>'') for blocks of prose, and preformatted blocks (''<pre>'') for source code listings, sample console output, or wherever else whitespace needs to be retained and a monospaced font used.
@@ Line 204: / Line 209: @@
   * For the names of commands, file names, or source code listings, use ''<code>''.
   * For example console text, use ''<samp>'' inside a ''<pre>'' block.
-  * And so-on...
+  * And so-on…
-There is a [[http://www.w3.org/TR/html5/text-level-semantics.html#usage-summary|usage summary of text-level semantic elements]] 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.
+There is a [[http://www.w3.org/TR/html5/text-level-semantics.html#usage-summary |usage summary of text-level semantic elements]] 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.
-==== HTML Template ====
+===== HTML Template =====
 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.
@@ Line 321: / Line 326: @@
 </file>
-$Id: tutorial_editing.html,v 1.24 2018/08/28 02:39:56 moondoggy Exp $<sup>1</sup> [[http://sdf.org/?tutorials/tutorial_editing|SDF Tutorial Editing Guide]] - legacy link
+$Id: tutorial_editing.html,v 1.24 2018/08/28 02:39:56 moondoggy Exp $<sup>1</sup> [[http://sdf.org/?tutorials/tutorial_editing|SDF Tutorial Editing Guide]] - traditional link (using [[wp>Revision_Control_System|RCS]])\\
 <sup>1</sup> Replicated from the tutorial_editing.html,v 1.24 2018/08/28 text.
-To see how this template looks when rendered, visit ''[[http://sdf.org/?tutorials/tutorial_template|http://sdf.org/?tutorials/tutorial_template]]''.
+To see how this template looks when rendered, visit ''[[http://sdf.org/?tutorials/tutorial_template |http://sdf.org/?tutorials/tutorial_template]]''.