191 lines
7.6 KiB
Executable File

<?xml version='1.0'?>
<!DOCTYPE cscpage SYSTEM "../csc.dtd">
<cscpage title="CSC Website Editing Howto">
<section title="Getting started">
In order to edit the website you will first have to get the CVS
repository in which it is stored. To do so, go somewhere in your
home directory and type:
export CVS_RSH=ssh<br />
cvs -d username@peri.uwaterloo.ca:~www/cvsroot co www
Where <code>username</code> is your CSC user name. You will be
prompted for your password (unless you use an SSH key). After a
while you should have a new directory, <code>www/</code>, with
the CSC pages in it.
You will also need <code>libxslt</code> and <code>libxml</code>
(including development headers) from Gnome. In debian,
<code>apt-get install libxml2-dev libxslt1-dev</code>.
<section title="Compiling the website">
The CSC website is <i>compiled</i>. This means that when you
edit a page, you don't edit the HTML source directly, but
instead edit a page describing the page's <i>content</i> (and
some formatting) and then run a command to generate the HTML
page from these content description pages.
To generate the CSC website, make sure you are in the directory
into which you checked it out (the <code>www/</code> directory)
and enter
This will compile the whole website. After any changes you make
you will have to recompile the website in the same manner.
<section title="Adding a regular page">
Let's now suppose we want to add a page detailing what operating
systems the CSC distributes through its CD-burning. First, we go
to the appropriate directory, in this case probably
<code>www/office</code>. Here we now open a new file called
<code>operating-systems.xml</code> in our favourite text editor
(emacs, of course). Take note that the filename ends in
<code>.xml</code>. All CSC web pages should have this file
The next thing to do is to add a few standard XML things to the
file. We add the two lines:
&lt;&#143;xml version='1.0'&#143;&gt;<br />
&lt;!DOCTYPE cscpage SYSTEM &quot;../csc.dtd&quot;&gt;
Note the reference to the file <code>../csc.dtd</code>. This
file is located in the <code>www/</code> directory, which is the
parent directory of <code>www/office/</code>, therefore we use
<code>../</code>. These two lines should appear at the top of
every CSC web page.
Next we start the actual page. To begin, we open a
<code>cscpage</code> tag with the title attribute set to the
title of our page. We also want to add a header with the CSC
logo, the current section directory and the title of the
page. Don't worry though, as you'll see this is really easy. Add
the following two lines to the end of the page:
&lt;cscpage title=&quot;Operating Systems the CSC
distributes&quot;&gt;<br />
&lt;header /&gt;
That's it! So we can see what our page looks like so far, we
also add the footer (with the menu, generation date, and
copyright information) and we close the <code>cscpage</code>
tag. Add the following lines to the end:
&lt;footer /&gt;<br />
Notice how in the case of <code>header</code> and
<code>footer</code> we have a <code>/</code> before the
<code>&gt;</code>? This is one of the major differences between
HTML and XML: tags that don't really have an end tag, such as
<code>&lt;br&gt;</code> have to be specified as being
<i>empty</i> in XML by adding a <code>/</code> before the
<code>&gt;</code>. This is particularily important to remember
when you add XHTML (XML's version of HTML) to the page.
Now we want to see what the resulting HTML page looks like. But
first we have to tell <code>make</code> about our new page. To
do so, open up the file <code>www/office/Makefile</code>, find
the line beginning with <code>INPUTS = </code> and simply add
<code>operating-systems.xml</code> to the end of that line. So
the line might look like <code>INPUTS = index.html staff.xml
books.xml operating-systems.xml</code>. Save
<code>Makefile</code> and close it. Now, in the
<code>www/</code> directory, type <code>make</code>. This will
build the whole website, (hopefully!) including our little
document. Once <code>make</code> is done, have a look at the
resulting file,
<code>www/office/operating-systems.html</code>. It should look
like <a href="editing-example1/operating-systems.html">example
1</a> (use your browsers Back button to return to this page
after viewing the example).
Looking at the generated page, you may have noticed that it does
not yet appear in the menu at the top of the page. Opening up
the special file <code>www/office/directory.xml</code> you will
see several entries, each corresponding to one of the menu
items. After the last line beginning with
<code>&lt;diritem</code>, add in the following line:
&lt;diritem title=&quot;"Operating Systems&quot;
href=&quot;operating-systems.html&quot; /&gt;
Now recompile the site with <code>make</code>. You should see
that the page now looks something like <a
2</a>. Also note that all the other office pages will now have a
reference to the new operating systems page.
With that out of the way, it's time to add some content. You may
be happy to hear that you can add regular (X)HTML to any CSC web
page. So, we'll add the following content between the
<code>&lt;header /&gt;</code> and <code>&lt;footer /&gt;</code>
of the page:
&lt;section title=&quot;List of operating systems&quot;&gt;<br/>
&lt;li&gt;&lt;a href=&quot;http://www.debian.org/&quot;&gt;Debian GNU/Linux&lt;/a&gt;&lt;/li&gt;<br/>
&lt;li&gt;&lt;a href=&quot;http://www.freebsd.org/&quot;&gt;FreeBSD&lt;/a&gt;&lt;/li&gt;<br/>
&lt;p&gt;More operating systems may be available.&lt;/p&gt;<br/>
As usual, compile your changes using <code>make</code> and have
a look. The resulting file should look something like <a
href="editing-example3/operating-systems.html">example 3</a>. A
few things to keep in mind are:
Always use lower-case in your XHTML tags. XML is
case-sensitive. For example: <code>&lt;br/&gt;</code> is good
whereas <code>&lt;BR/&gt;</code> is bad.
Always close your tags. If it's a tag that never encloses
anything use the <code>&lt;tag/&gt;</code> syntax. For
example: <code>&lt;ul&gt; &lt;li&gt;Item
1&lt;br/&gt;Linebreak&lt;/li&gt; &lt;li&gt;Item
2&lt;/li&gt;&lt;/ul&gt;</code> is good, whereas
<code>&lt;ul&gt; &lt;li&gt;Item
1&lt;br&gt;Linebreak &lt;li&gt;Item 2&lt;/ul&gt;</code> is bad.
You must place HTML code inside <code>&lt;section&gt;</code>
tags. You can have as many section as you want on the page.
<footer />