Added clubs reference and updated cvsroot in editing howto

[mspang/www.git] / docs / editing-howto.xml

<?xml version='1.0'?>

<!DOCTYPE cscpage SYSTEM "../csc.dtd">

<cscpage title="CSC Website Editing Howto">
  <header/>
  <section title="Getting started">
    <p>
      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:
    </p>
    <code>
      export CVS_RSH=ssh<br />
      cvs -d username@peri.uwaterloo.ca:~www/cvsroot co www
    </code>
    <p>
      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.
    </p>
    <p>
      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>.
    </p>
  </section>
  <section title="Compiling the website">
    <p>
      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.
    </p>
    <p>
      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
    </p>
    <code>
      make
    </code>
    <p>
      This will compile the whole website. After any changes you make
      you will have to recompile the website in the same manner.
    </p>
  </section>
  <section title="Adding a regular page">
    <p>
      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
      ending.
    </p>
    <p>
      The next thing to do is to add a few standard XML things to the
      file. We add the two lines:
    </p>
    <code>
      &lt;xml version='1.0'&gt;<br />
      &lt;!DOCTYPE cscpage SYSTEM &quot;../csc.dtd&quot;&gt;
    </code>
    <p>
      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.
    </p>
    <p>
      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:
    </p>
    <code>
      &lt;cscpage title=&quot;Operating Systems the CSC
      distributes&quot;&gt;<br />
      &lt;header /&gt;
    </code>
    <p>
      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:
    </p>
    <code>
      &lt;footer /&gt;<br />
      &lt;/cscpage&gt;
    </code>
    <p>
      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.
    </p>
    <p>
      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).
    </p>
    <p>
      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:
    </p>
    <code>
      &lt;diritem title=&quot;"Operating Systems&quot;
      href=&quot;operating-systems.html&quot; /&gt;
    </code>
    <p>
      Now recompile the site with <code>make</code>. You should see
      that the page now looks something like <a
      href="editing-example2/operating-systems.html">example
      2</a>. Also note that all the other office pages will now have a
      reference to the new operating systems page.
    </p>
    <p>
      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:
    </p>
    <code>
      &lt;section title=&quot;List of operating systems&quot;&gt;<br/>
      &lt;ul&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;/ul&gt;<br/>
      &lt;p&gt;More operating systems may be available.&lt;/p&gt;<br/>
      &lt;/section&gt;<br/>
    </code>
    <p>
      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:
    </p>
    <ul>
      <li>
        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.
      </li>
      <li>
        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.
      </li>
      <li>
        You must place HTML code inside <code>&lt;section&gt;</code>
        tags. You can have as many section as you want on the page.
      </li>
    </ul>
  </section>
  <footer />
</cscpage>