How to create QuickReference Guides
a guide to writing a guide
If you have a topic for which you think a QuickReference Guide would
be useful, please talk to one of the staff to get it okayed. We
would like to see a wide assortment of handy guides available.
- Obtain a copy of the html file to edit. This is most conveniently done from your public_html directory, so that you can easily look at the effect as you work on it and/or show others.
- If you are creating a new qref, get the template file, which contains the SSI that qrefs should contain:
%cp /mnt/web/www/qref/template.html ./subject.html
- If you are editing an existing an existing qref, make yourself a copy of that:
%cp /mnt/web/www/qref/specific_file.html .
If you don't know exactly where to find the qref in question, find it in a webbrowser; everything after the qref/ is what you should replace the specific qref file with.
- If necessary, change the permissions of the file so that you can edit it:
%chmod 744 filename.html
- Edit the html file with the editor of your choice:
% {emacs,vi} document.html
You should refer to documentation of html on the actual formating
of the text, but it should contain things like a title, header and
an introductory paragraph. We currently use HTML 4.0 as the standard for all
department webpages. See
www.w3.org
for more information. Be sure to run the page throught the
validator before posting on the web.
- There should begin a step-by-step walk through the subject of your
qref. The steps should be indented and numbered: To do this use
<OL> to begin a numbered list and <LI> to indicate an
element of it. While writing these steps please follow the font standards
listed bellow.
-
When the entire recipe has been cooked up, you may wish to conclude with
comments, notes, tips, bugs, tricks, ideas, or a summary. Simply enter
those after the final comment. You should also refer the reader to manual
pages that will be helpful.
-
To see how the final product looks, use Netscape to view
it. If it's in your public_html directory, then go to http://www.cs.hmc.edu/~yourname/filename.html. If not, you can open the file by selecting File and then
Open File. This will put you in your home directory. Choose the
file or directory containing the file.
Once the qref is installed by a
staff member it will be accessible in the same location as all the others.
-
Remit the final version of your guide to the friendly staff who okayed it.
Thank you very much!
Notes:
There is a standard for fonts to be used in writing QuickReferences:
System prompts and responses
will be in Courier, enclosed with <SAMP> and
</SAMP>
user input to the system
will be in Bold Courier, using <strong> and </strong> ;
Key Names
from the keyboard will use <B> and </B> ;
Names
including
filenames,
system names
and
usernames
will be in Italics, using <I> and </I> ;
Manual pages should be referred to with the name in italics and the
section number in roman, i.e.
rogue(6).
This may be done with the line:
<I>rogue</I>(6)
Printing a sample command line should be done as follows:
<b>%</b> <samp>input from user<I>(comments from the
author)</I> </samp>
which will produce
% input from user (comments from the author)
Note that to get < and > to show up as symbols, type < and >. & is typed &. If you want to follow either of these by further letters without a space, use a semicolon in place of the space, like so: &amp, which is the html I used to produce &.
Copyright (c) HMC Computer Science Department.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1
or any later version published by the Free Software Foundation;
with the no Invariant Sections, with no
Front-Cover Texts, and with no Back-Cover Texts.
A copy of the license is included in the section entitled ``GNU Free Documentation License.''
|
