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/17 03:48] – [Before You Start Coding!] hc9sdf_tutorial_editing_guide [2022/03/02 19:57] (current) – [HTML Template] hc9
Line 86: 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 98: 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 119: 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 137: Line 137:
 </file> </file>
  
-<nowiki> +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.
- +
-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. +
- +
-</nowiki>+
  
 <file config Superscript > <file config Superscript >
Line 161: 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 187: 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 212: 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.
sdf_tutorial_editing_guide.1615952928.txt.gz · Last modified: 2021/03/17 03:48 by hc9