peteyboy/tutes-dump
2
1
Fork 0
forked from pifty/tutes-dump
Code Issues Pull Requests Projects Releases Wiki Activity

Replace escape <,> with <, >

Browse Source 
for i in *.html.docuwiki; do perl -pi -e "s/&gt;/>/g" $i; done
for i in *.html.docuwiki; do perl -pi -e "s/&lt;/</g" $i; done
This commit is contained in:
peteyboy
2021-03-11 23:50:37 +00:00
parent 11889ecf9e
commit c81979dcbf
63 changed files with 573 additions and 573 deletions
Download Patch File Download Diff File Expand all files Collapse all files
dump/tutorial_editing.html.docuwiki
+119 -119
View File
@@ -34,7 +34,7 @@ To create or edit a tutorial, change your working directory to "/sys/html/tutori
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.
$ umask 022
$ echo -e "\n\$Id\$" &gt; your_tutorial_filename.html
$ echo -e "\n\$Id\$" > your_tutorial_filename.html
Use the command "ci -u" to check-in the file with RCS and leave it unlocked it so that anyone can edit it.
@@ -72,17 +72,17 @@ Tutorials are coded using HTML. If you are already handy with HTML, then you are
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 [[#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:&lt;TUTORIALS&gt;". 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! ====
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 "&lt;body&gt;" 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:
* "&lt;html&gt;, &lt;/html&gt;"
* "&lt;head&gt;, &lt;/head&gt;"
* "&lt;meta&gt;"
* "&lt;base&gt;"
* "&lt;body&gt;, &lt;/body&gt;"
* "<html>, </html>"
* "<head>, </head>"
* "<meta>"
* "<base>"
* "<body>, </body>"
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.
@@ -90,41 +90,41 @@ Tutorial files will also contain an RCS **$Id** tag, which will look something l
**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).
**Always provide a description of the image** for users of text-based browsers and the visually impaired in the "alt" attribute of the "&lt;img&gt;" tag.
**Always provide a description of the image** for users of text-based browsers and the visually impaired in the "alt" attribute of the "<img>" tag.
Incorrect:
"&lt;img src="tutorials/images/example.png"&gt;"
"<img src="tutorials/images/example.png">"
Correct:
"&lt;img src="http://sdf.org/tutorials/images/example.png"
alt="Image of a Blickensderfer No. 5 typewriter"&gt;"
"<img src="http://sdf.org/tutorials/images/example.png"
alt="Image of a Blickensderfer No. 5 typewriter">"
=== 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 ("&lt;ol&gt;") 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]].
"&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;
"<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>
"
Then, where the sources are cited in the text of your tutorial, use a superscript ("&lt;sup&gt;") 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.
"&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;"
"<p>The secret to a proper nose-goblin ganache is in the picking<sup><a
href="#bartles">1</a></sup>. (...)</p>"
Or,
"&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;"
"<p>Without adequate stretching beforehand, you are certain to suffer a
Ludmilian haemorrhage(<a href="#moribund">2</a>). (...)</p>"
There are further examples of this in the [[#template|code template]] below.
@@ -133,26 +133,26 @@ There are further examples of this in the [[#template|code template]] below.
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
* "&lt;h1&gt;", ..., "&lt;h6&gt;"
* "<h1>", ..., "<h6>"
* Grouping/Block-Level Elements
* "&lt;p&gt;"
* "&lt;pre&gt;"
* "&lt;ul&gt;","&lt;ol&gt;", "&lt;dl&gt;" and their subordinates
* "&lt;blockquote&gt;"
* "&lt;hr&gt;"
* "&lt;table&gt;" and its subordinates
* and, of course, "&lt;div&gt;"
* "<p>"
* "<pre>"
* "<ul>","<ol>", "<dl>" and their subordinates
* "<blockquote>"
* "<hr>"
* "<table>" and its subordinates
* and, of course, "<div>"
* Text-level/Inline Elements
* "&lt;br&gt;"
* "&lt;a&gt;"
* "&lt;img&gt;"
* "&lt;code&gt;", "&lt;samp&gt;", and "&lt;kbd&gt;"
* "&lt;sup&gt;" and "&lt;sub&gt;"
* "&lt;strong&gt;", "&lt;small&gt;", and "&lt;em&gt;"
* "&lt;i&gt;", "&lt;b&gt;", "&lt;u&gt;", and "&lt;s&gt;"
* "&lt;dfn&gt;", "&lt;var&gt;", and "&lt;cite&gt;"
* "<br>"
* "<a>"
* "<img>"
* "<code>", "<samp>", and "<kbd>"
* "<sup>" and "<sub>"
* "<strong>", "<small>", and "<em>"
* "<i>", "<b>", "<u>", and "<s>"
* "<dfn>", "<var>", and "<cite>"
Many closing tags are optional, but for code clarity they can be nice. Stay away from XHTML self-closing tag forms, however (ie. "&lt;br/&gt;", "&lt;hr/&gt;", "&lt;img src="some_url"/&gt;", 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 ====
@@ -166,15 +166,15 @@ Furthermore, the tutorials are a collaborative effort. You may be the first auth
**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 ("&lt;h1&gt;,&lt;h2&gt;,...,&lt;h6&gt;"), and stay away from using "&lt;div&gt;"s.
* Use paragraphs ("&lt;p&gt;") for blocks of prose, and preformatted blocks ("&lt;pre&gt;") for source code listings, sample console output, or wherever else whitespace needs to be retained and a monospaced font used.
* 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.
Rather than use styled "&lt;span&gt;" 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.
Rather than use styled "<span>" 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.
* For important text, use "&lt;strong&gt;".
* For emphasis, use "&lt;em&gt;".
* For the names of commands, file names, or source code listings, use "&lt;code&gt;".
* For example console text, use "&lt;samp&gt;" inside a "&lt;pre&gt;" block.
* For important text, use "<strong>".
* For emphasis, use "<em>".
* 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...
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.
@@ -183,111 +183,111 @@ There is a [[http://www.w3.org/TR/html5/text-level-semantics.html#usage-summary|
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 text contained between the "&lt;!--" and "--&gt;" tokens are //comments//, and may be discarded.
The text contained between the "<!--" and "-->" tokens are //comments//, and may be discarded.
"
//&lt;!-- SDF Tutorial Template
//<!-- 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;//
may be beginners with HTML. -->//
&lt;style type="text/css"&gt;
<style type="text/css">
@import url('http://sdf.org/tutorials/tutorials.css');
&lt;/style&gt;
</style>
//&lt;!-- The title of the tutorial should be the only level-1 header
(&lt;h1&gt;) in the document. --&gt;//
&lt;h1&gt;Title of Tutorial&lt;/h1&gt;
//<!-- The title of the tutorial should be the only level-1 header
(<h1>) in the document. -->//
<h1>Title of Tutorial</h1>
//&lt;!-- For longer tutorials, a table of contents is nice. Shorter
//<!-- 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;//
&lt;ul&gt;
&lt;li&gt;
&lt;a href="#section-1"&gt;Section Heading&lt;/a&gt;
//&lt;!-- to get an indented section of the list, we simply embed a
list inside of a list item --&gt;//
&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;
omitted. Replace the <ul> tags with <ol> tags for a numbered list. -->//
<ul>
<li>
<a href="#section-1">Section Heading</a>
//<!-- to get an indented section of the list, we simply embed a
list inside of a list item -->//
<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>
//&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;//
&lt;h2 id="section-1"&gt;Section Heading&lt;/h2&gt;
//<!-- 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. -->//
<h2 id="section-1">Section Heading</h2>
//&lt;!-- Remember to always contain your paragraphs in &lt;p&gt; tags. For
//<!-- 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 &lt;code&gt; tags to differentiate them from the
rest of the paragraph's text. --&gt;//
&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;
paragraph, wrap them in <code> tags to differentiate them from the
rest of the paragraph's text. -->//
<p>By issuing the <code>sac -nar</code> command, your spirit animal
will be changed to the narwhal.</p>
//&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
//<!-- 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 &lt;p&gt;. --&gt;//
&lt;pre&gt;&lt;code&gt;10 PRINT "DO YOU EAT BOOGERS?"
inside of a <p>. -->//
<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?"
&lt;/code&gt;&lt;/pre&gt;
</code></pre>
//&lt;!-- For sample program output, console sessions, etc., use &lt;samp&gt;
inside a &lt;pre&gt; block. --&gt;//
&lt;pre&gt;&lt;samp&gt;$ finger man@arms
//<!-- For sample program output, console sessions, etc., use <samp>
inside a <pre> block. -->//
<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.
&lt;/samp&gt;&lt;/pre&gt;
</samp></pre>
//&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;//
&lt;h3 id="subsection-1"&gt;Subsection Heading&lt;/h3&gt;
//<!-- 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! -->//
<h3 id="subsection-1">Subsection Heading</h3>
//&lt;!-- For VERY IMPORTANT TEXT, make it &lt;strong&gt;. To add emphasis to a
word or phrase, use &lt;em&gt;. --&gt;//
&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;
//<!-- For VERY IMPORTANT TEXT, make it <strong>. To add emphasis to a
word or phrase, use <em>. -->//
<p><strong>Do not forget to flush the buffer</strong>. If you do, the
smell will be <em>intolerable</em>.</p>
&lt;h2 id="section-2"&gt;Another Section Heading&lt;/h2&gt;
<h2 id="section-2">Another Section Heading</h2>
//&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;//
&lt;p&gt;The Honeywell 6080 can be induced to perform a samba by pressing
//<!-- This paragraph gives an example of two styles of footnote
referencing. Both are hyperlinked to corresponding list items (<li>)
in the Notes section below. -->//
<p>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é,
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;
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>
//&lt;!-- Here is a sample footnotes section. In this example, we're using
//<!-- 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;//
&lt;h2 id="notes"&gt;Notes&lt;/h2&gt;
it doesn't, feel free to snip this entire section out. -->//
<h2 id="notes">Notes</h2>
//&lt;!-- We're using an ordered list (&lt;ol&gt;) so that the notes are
//<!-- 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. --&gt;//
&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;
for subsequent references to a single work. -->//
<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>
//&lt;!-- At the very end, here, is the RCS Id tag. Let it be, my friend. --&gt;//
//<!-- At the very end, here, is the RCS Id tag. Let it be, my friend. -->//
$Id: tutorial_editing.html,v 1.24 2018/08/28 02:39:56 moondoggy Exp $
"