SDF HTML教程编辑指南：修订间差异

2023年7月14日 (五) 18:42的版本

下面的说明是关于创建和编辑基于HTML的用户贡献的教程。要为SDF wiki 教程贡献，请看SDF wiki 教程。

简介

每天都有许多年轻的、非常容易受影响的人发现SDF。他们问我们一些我们可能觉得很愚蠢的问题，但这并不是他们的错。他们在成长过程中只知道黑客会破坏计算机网络，利用人们和他们的信息。解决方案不是嘲笑或回避这些孩子，而是告诉他们有一个更好、更真实的方法。 -- 摘自README.TXT

本指南的编写是为了帮助成员更容易地为SDF HTML教程项目做出贡献。指南的第一部分简要说明了如何使用RCS^[1]进行版本控制来创建或编辑教程文件。指南的第二部分讨论了针对教程的HTML代码，并包含一些模板代码。

你最好阅读一下教程文件目录（/sys/html/tutorials）中SDF HTML教程项目的原始README.TXT。它不仅表达了项目的目的，而且还包含了比这里更详细的RCS使用信息。

本指南假定读者具有基本的shell使用和文本文件编辑知识。熟悉HTML是不必要的，尽管它可能会有帮助。

创建和编辑教程

要创建或编辑一个教程，请将你的工作目录改为/sys/html/tutorials，在你的SDF主集群（例如sdf.org，而不是MetaArray）的shell中：

$ cd /sys/html/tutorials

创建一个新的教程

在教程目录内，你可以使用echo来快速创建一个空的HTML文件，同时在底部有一个RCS Id标签。首先使用umask命令，以确保新文件的权限允许网络服务器（和其他用户）读取它。

$ umask 022
$ echo -e "\n\$Id\$" > your_tutorial_filename.html

使用命令ci -u将该文件用RCS签入，并将其解锁，以便任何人都可以编辑它。

$ ci -u your_tutorial_filename.html

在你第一次签入一个文件时，你会被要求对其进行描述。请写一些有用的东西。

现在你可以使用下一节的说明编辑你的教程，以检查文件是否进入和离开RCS。

一旦你的教程准备好公开展示，请将其添加到可用的教程列表中，以便人们能够在网上真正找到它。你必须编辑教程目录中的index.html文件来完成这项工作。编辑index.html文件时，请使用与编辑教程时相同的签入/签出程序。

编辑一个现有的教程

在tutorials目录下，使用co -l命令用RCS检查文件，并在你进行编辑时锁定它。

$ co -l filename

如果在使用co -l时，你被告知该文件已经被锁定，请停止你正在做的事情，并等待它被重新签入。如果它没有被签入，请给作者发邮件，让他们知道你想签出该文件并编辑它。

现在你可以使用你喜欢的文本编辑器编辑该文件。如果你定期保存你的工作，你可以在你的网络浏览器中加载和重新加载教程以查看你的变化。教程文件的URL将是http://sdf.org/?tutorials/filename_without_extension（例如，如果你正在编辑/sys/html/tutorials/nmap_for_dummies.html，URL将是http://sdf.org/?tutorials/nmap_for_dummies）。

当你完成了对文件的编辑，使用命令ci -u将该文件用RCS签入，并解锁，以便其他人可以编辑它。

$ ci -u filename

当你签入一个文件时，你会被要求描述你对它所做的修改。随你怎么说，但请写一些有用的东西。

签入之前撤销编辑

如果在编辑完一个文件后，你希望不签入你的修改，恢复到没有你的修改的版本，只需运行一个带有解锁的签出，类似于你之前的签出方式：

$ co -u filename

你可能会收到一个警告，询问你是否要删除文件的写入权限---你*需要*，因此输入*yes*。这将把以前版本的文件重新加载到当前文件夹中，并解锁，以便其他人可以再次进行修改。如果你想再试一次，请使用与上述相同的步骤。

编辑FAQ

MetaARPA会员也可以编辑FAQ。这些是纯文本文件，能在/sys/html/tutorials/FAQ/中找到。每个部分的FAQ列表都在一个点文件".list"中。这些FAQ文件与faq命令所显示的文件定期同步。

（用html）编辑一个教程

教程是用HTML编码的。如果你对HTML已经驾轻就熟，那么你离编辑你的教程就只有一步之遥了!请阅读 "在你开始写代码之前"部分，了解一些实施的具体细节，并在继续前至少略过编码风格部分。

如果你不熟悉HTML，W3C^[2]网站有一个非常简短的教程，即《HTML入门》，它将教会你足够多的基础知识，以便能够编写一个教程。此外，本页面的模板还提供了大量的评论，以帮助HTML初学者。

如果您没有时间或意愿学习HTML，您仍然可以为教程项目做出贡献。用纯文本编写教程（或者是一份章节、一处更正、附录等），并在 bboard:<TUTORIALS> 中添加注释。您的 MetaARPA 同事可能会自愿为您将作品 HTML 化。

在您开始写代码之前！

SDF 教程文件包含 HTML 代码，但不是完整的 HTML 文档。当它们被提供给 Web 浏览器时，网站的 index.cgi 会将它们封装在全站导航的页眉和页脚中。教程文件中的代码代表 <body> 元素内的内容，并且确保不得包含以下元素/标记

<html>, </html>
<head>, </head>
<meta>
<base>
<body>, </body>

教程文件也将包含一个RCS $Id标签，它看起来像这样： $Id:filename.html,v 1.11 2011/01/01 11:11:11 username Exp $ 。无需编辑，因为它是由RCS自动生成的。最好将其作为文件的最后一行。

使用图片

请勿从其他网站热链图片。在/sys/html/tutorials/images中放置您希望使用的任何图像文件的副本。并确保它们的权限允许Web服务器读取它们（chmod a+r可以做到这一点）。

始终在<img>标签的alt属性中为基于文本的浏览器用户和视障人士提供图片说明。

错误：

<img src="tutorials/images/example.png">

正确：

<img src="http://sdf.org/tutorials/images/example.png" 
     alt="Image of a Blickensderfer No. 5 typewriter">

引用参考文献

如果您在教程中严重依赖某一资料来源，尤其是直接引用该资料来源，您应适当引用该作品。

在您的教程中包含一个 "参考文献 "或 "注释 "标题（通常在最后），并使用编号列表（<ol>）按照芝加哥注释风格（ Chicago Style for Notes）列举您的资料来源。

<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>

然后，在教程正文中引用资料来源时，使用上标（<sup>）编号或括号中的编号超链接到相应的列表项。

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

或者，

<p>Without adequate stretching beforehand, you are certain to suffer a 
Ludmilian haemorrhage(<a href="#moribund">2</a>). (...)</p>

在下面的代码模板中有更多的例子。

哪个HTML版本？

目前W3C推荐的是HTML 5。在大多数方面，HTML的核心元素自20世纪90年代中期以来就没有改变过；只是增加了一些标记，删除了一些标记。为了最大限度地实现向后兼容性，您可以将自己限制在以下元素中，这些元素自1996年以来一直没有变化：

标题元素
- <h1>, ..., <h6>
分组/区块元素
- <p>
- <pre>
- <ul>,<ol>, <dl>及其下属
- <blockquote>
- <hr>
- <table> 及其下属
- 当然还有<div>
文本级/内联元素
- <br>
- <a>
- <img>
- <code>, <samp>以及 <kbd>
- <sup> 以及 <sub>
- <strong>, <small>以及 <em>
- <i>, <b>, <u>以及 <s>
- <dfn>, <var>以及 <cite>

许多结束标记虽然是可选的，但为了代码的清晰度，最好可以使用。但是，请远离XHTML自闭合标签形式（即<br/>、<hr/>、<img src="some_url"/>等）。

代码风格

使用HTML和CSS可以做很多事情。如果将Javascript加入其中，您可以做得更多。

但不要。

SDF 教程是面向所有用户的资源，用户访问教程的方式多种多样。有些用户会通过 telnet 连接使用基于文本的浏览器阅读，有些用户可能会有残疾，需要使用屏幕阅读器。如果您的教程大量使用CSS或Javascript，那么您就没有考虑到所有用户的需求。

此外，教程是一项协作工作。您可能是第一个编写教程的作者，但您可能不会是最后一个。如果您的教程是一个到处使用各种样式属性和标签/元素特异毛球，只会增加下一位作者编辑/扩展的难度——尤其是如果他们不像您一样精通网页编码的话。

在编写教程时，请尽量使用纯HTML。编写一个清晰的教程所需的一切都已经在语言中了：

使用标题标签(<h1>,<h2>,…,<h6>)来组织您的教程，不要使用<div>。
在零散的文段中使用段落标签 (<p>)，在源代码列表、控制台输出示例或其他需要保留原格式和使用单倍行距字体的地方使用预定义格式标签 (<pre>)。

与其使用样式标签<span>或其他通用分组元素，不如使用语义化标签来描述您希望与正文文本区分开来的文本。如果用户的浏览器支持该标记，则会以不同的方式显示。

对于重要文本，请使用<strong>
如需强调，请使用<em>
对于命令名称、文件名或源代码列表，使用<code>
例如控制台文本，在<pre>块内使用<samp>
等等...

在当前的W3C建议（HTML 5）中，有一份文本级语义元素的使用摘要。这很方便。并非所有浏览器都支持所有标签，但语义标签教程比充满自定义样式跨度的文档更有用，也更易于样式化。

HTML模板

如果您要创建一个新的教程或从头开始重新编写一个教程，下面的代码可以用作模板。不是必须使用这个模板，只是为你提供方便。

在标记之间的文本是注释，可以丢弃。

<!-- SDF Tutorial Template
======================================================================
该代码的使用完全是可选的。它是作为代码风格的示例，
也是为可能是HTML初学者提供的快速开始新教程的方法。
 -->

<style type="text/css">
  @import url('https://sdf.org/tutorials/tutorials.css');
</style>

<!-- 在整个文档中，教程标题应是唯一的一级标题(<h1>)。  -->
<h1>Title of Tutorial</h1> 

<!-- 对于较长的教程，最好有目录。
较短的教程（如本教程）确实不需要目录，因此本部分可以省略。
可以用<ol>标签替换<ul>标签，以获得编号列表。 -->
<ul>
  <li>
    <a href="#section-1">Section Heading</a>
    <!-- 要获得列表的缩进部分，我们只需在列表项中再嵌入一个列表即可。 
    -->
    <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>

<!-- 这是一个章节的开头。开始于一个二级标题(<h2>)，
并被赋予一个 "id "属性，以便可以链接。 
-->
<h2 id="section-1">Section Heading</h2>

<!-- 请记住始终将段落包含在 <p> 标记中。 对于出现在
段落内的代码、文件名、命令等字符串，请将它们包含
在 <code> 标记中，以将它们与段落文本的其余部分区分开来。
-->
<p>By issuing the <code>sac -nar</code> command, your spirit animal
will be changed to the narwhal.</p>

<!-- 对于整个代码块，请将 <code> 放置在 <pre> 而不是 <p> 内。 
<pre> 内的文本按字面意思解释其空白字符
（空格、制表符、回车符），这与 <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?"
</code></pre>

<!-- 对于示例程序输出、控制台会话等，在<pre>块内使用<samp>。.
-->
<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.
</samp></pre>

<!-- 本小节以三级标题（<h3>）开始。
HTML为嵌套六层的部分提供了标签（标签<h1>到<h6>）。
如果您需要嵌套七层或更深的部分……您可以考虑调整您的教程！ 
-->
<h3 id="subsection-1">Subsection Heading</h3>

<!-- 对于非常重要的文本，请使用<strong>。要强调一个
单词或短语，请使用<em>。 -->
<p><strong>Do not forget to flush the buffer</strong>. If you do, the
smell will be <em>intolerable</em>.</p>

<h2 id="section-2">Another Section Heading</h2>

<!-- 本段给出了两种脚注引用风格的示例。 
两者都超链接到下面“注释”部分中相应的列表项 (<li>)。 
-->
<p>The Honeywell 6080 can be induced to perform a samba by pressing
the button labeled "Samba" on the operator's
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>

<!-- 下面是脚注部分的示例。在本示例中，我们使用脚注引用参考文献，
但同样的样式可用于任何类型的脚注。您的教程可能不需要任何脚注。
如果不需要，请随意删去整个部分。
-->
<h2 id="notes">Notes</h2>

<!-- 我们使用有序列表（<ol>）对注释进行自动编号。
在本教程中，一个参考文献被引用了两次。
正如您所看到的，您可以使用缩写形式引用单篇作品的后续参考文献。
-->
<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>
 
<!-- 最后是RCS Id标签。就这样吧，我的朋友。 -->
$Id: tutorial_editing.html,v 1.29 2021/06/08 00:28:33 peteyboy Exp $

要查看该模板的渲染效果，请访问https://sdf.org/?tutorials/tutorial_template。

注释：

↑ Revision Control System
↑ World Wide Web Consortium

[1] Revision Control System

[2] World Wide Web Consortium

[1]

[2]

@@ 第37行： / 第37行： @@
 ==== 创建一个新的教程 ====
-在教程目录内，你可以使用echo来快速创建一个空的HTML文件，同时在底部有一个RCS Id标签。首先使用umask命令，以确保新文件的权限允许网络服务器（和其他用户）读取它。<syntaxhighlight lang="shell" line="1">
+在教程目录内，你可以使用echo来快速创建一个空的HTML文件，同时在底部有一个RCS Id标签。首先使用umask命令，以确保新文件的权限允许网络服务器（和其他用户）读取它。<syntaxhighlight lang="shell">
 $ umask 022
 $ echo -e "\n\$Id\$" > your_tutorial_filename.html
-</syntaxhighlight>使用命令<code>ci -u</code>将该文件用RCS签入，并将其解锁，以便任何人都可以编辑它。<syntaxhighlight lang="shell" line="1">
+</syntaxhighlight>使用命令<code>ci -u</code>将该文件用RCS签入，并将其解锁，以便任何人都可以编辑它。<syntaxhighlight lang="shell">
 $ ci -u your_tutorial_filename.html
 </syntaxhighlight>在你第一次签入一个文件时，你会被要求对其进行描述。请写一些有用的东西。
@@ 第49行： / 第49行： @@
 ==== 编辑一个现有的教程 ====
-在tutorials目录下，使用<code>co -l</code>命令用RCS检查文件，并在你进行编辑时锁定它。<syntaxhighlight lang="shell" line="1">
+在tutorials目录下，使用<code>co -l</code>命令用RCS检查文件，并在你进行编辑时锁定它。<syntaxhighlight lang="shell">
 $ co -l filename
 </syntaxhighlight>'''<u>如果在使用<code>co -l</code>时，你被告知该文件已经被锁定，请停止你正在做的事情，并等待它被重新签入。如果它没有被签入，请给作者发邮件，让他们知道你想签出该文件并编辑它。</u>'''
@@ 第55行： / 第55行： @@
 现在你可以使用你喜欢的文本编辑器编辑该文件。如果你定期保存你的工作，你可以在你的网络浏览器中加载和重新加载教程以查看你的变化。教程文件的URL将是<code><nowiki>http://sdf.org/?tutorials/filename_without_extension</nowiki></code>（例如，如果你正在编辑<code>/sys/html/tutorials/nmap_for_dummies.html</code>，URL将是<code><nowiki>http://sdf.org/?tutorials/nmap_for_dummies</nowiki></code>）。
-当你完成了对文件的编辑，使用命令<code>ci -u</code>将该文件用RCS签入，并解锁，以便其他人可以编辑它。<syntaxhighlight lang="shell" line="1">
+当你完成了对文件的编辑，使用命令<code>ci -u</code>将该文件用RCS签入，并解锁，以便其他人可以编辑它。<syntaxhighlight lang="shell">
 $ ci -u filename
 </syntaxhighlight>当你签入一个文件时，你会被要求描述你对它所做的修改。随你怎么说，但请写一些有用的东西。
 ===== 签入之前撤销编辑 =====
-'''<u>如果在编辑完一个文件后，你希望不签入你的修改，恢复到没有你的修改的版本</u>'''，只需运行一个带有解锁的签出，类似于你之前的签出方式：<syntaxhighlight lang="shell" line="1">
+'''<u>如果在编辑完一个文件后，你希望不签入你的修改，恢复到没有你的修改的版本</u>'''，只需运行一个带有解锁的签出，类似于你之前的签出方式：<syntaxhighlight lang="shell">
 $ co -u filename
 </syntaxhighlight>你可能会收到一个警告，询问你是否要删除文件的写入权限---你*需要*，因此输入*yes*。这将把以前版本的文件重新加载到当前文件夹中，并解锁，以便其他人可以再次进行修改。如果你想再试一次，请使用与上述相同的步骤。