User Tools

Site Tools


sdf_tutorial_editing_guide

Differences

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

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
sdf_tutorial_editing_guide [2021/03/11 00:20] – [HTML Template] hc9sdf_tutorial_editing_guide [2022/03/02 19:57] (current) – [HTML Template] hc9
Line 1: Line 1:
-====== SDF Tutorial Editing Guide ======+====== SDF HTML Tutorial Editing Guide ======
  
-===== Introduction =====+===== Original Tutorial Site Editing ===== 
 +This information is not for this wiki, but for the older, ([[wp>Revision_Control_System|RCS]]) straight-HTML based SDF Tutorial pages, accessible via https://sdf.org/?tutorials
  
-    * 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+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! 
 + 
 +===== 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. 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.
Line 82: Line 86:
 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. 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: 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 94: Line 98:
 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. 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). **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 115: Line 119:
 </code> </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. 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.
Line 133: Line 137:
 </file> </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 > <file config Superscript >
Line 153: Line 157:
 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:
Line 172: Line 176:
     * ''<img>''     * ''<img>''
     * ''<code>'', ''<samp>'', and ''<kbd>''     * ''<code>'', ''<samp>'', and ''<kbd>''
-    * ''<sup >'' and ''<sub>''+    * ''<nowiki><sup></nowiki>'' and ''<sub>''
     * ''<strong>'', ''<small>'', and ''<em>''     * ''<strong>'', ''<small>'', and ''<em>''
     * ''<i>'', ''<b>'', ''<u>'', and ''<s>''     * ''<i>'', ''<b>'', ''<u>'', and ''<s>''
Line 179: Line 183:
 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). 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. You can //do a lot// with HTML and CSS. You can do even more if you throw Javascript into the mix.
Line 204: Line 208:
 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. 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 317: Line 321:
 </file> </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. <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]]''.
  
sdf_tutorial_editing_guide.1615422025.txt.gz · Last modified: 2021/03/11 00:20 by hc9