Added more stuff to the editing howto. Added content for office/.
[www/www.git] / docs / editing-howto.xml
1 <?xml version='1.0'?>
2
3 <!DOCTYPE cscpage SYSTEM "../csc.dtd">
4
5 <cscpage title="CSC Website Editing Howto">
6   <header/>
7   <section title="Getting started">
8     <p>
9       In order to edit the website you will first have to get the CVS
10       repository in which it is stored. To do so, go somewhere in your
11       home directory and type:
12     </p>
13     <code>
14       export CVS_RSH=ssh<br />
15       cvs -d username@peri.uwaterloo.ca:~sjdutoit/cvsroot co www
16     </code>
17     <p>
18       Where <code>username</code> is your CSC user name. You will be
19       prompted for your password (unless you use an SSH key). After a
20       while you should have a new directory, <code>www/</code>, with
21       the CSC pages in it.
22     </p>
23     <p>
24       You will also need <code>libxslt</code> and <code>libxml</code>
25       (including development headers) from Gnome. In debian,
26       <code>apt-get install libxml2-dev libxslt1-dev</code>.
27     </p>
28   </section>
29   <section title="Compiling the website">
30     <p>
31       The CSC website is <i>compiled</i>. This means that when you
32       edit a page, you don't edit the HTML source directly, but
33       instead edit a page describing the page's <i>content</i> (and
34       some formatting) and then run a command to generate the HTML
35       page from these content description pages.
36     </p>
37     <p>
38       To generate the CSC website, make sure you are in the directory
39       into which you checked it out (the <code>www/</code> directory)
40       and enter
41     </p>
42     <code>
43       make
44     </code>
45     <p>
46       This will compile the whole website. After any changes you make
47       you will have to recompile the website in the same manner.
48     </p>
49   </section>
50   <section title="Adding a regular page">
51     <p>
52       Let's now suppose we want to add a page detailing what operating
53       systems the CSC distributes through its CD-burning. First, we go
54       to the appropriate directory, in this case probably
55       <code>www/office</code>. Here we now open a new file called
56       <code>operating-systems.xml</code> in our favourite text editor
57       (emacs, of course). Take note that the filename ends in
58       <code>.xml</code>. All CSC web pages should have this file
59       ending.
60     </p>
61     <p>
62       The next thing to do is to add a few standard XML things to the
63       file. We add the two lines:
64     </p>
65     <code>
66       &lt;xml version='1.0'&gt;<br />
67       &lt;!DOCTYPE cscpage SYSTEM &quot;../csc.dtd&quot;&gt;
68     </code>
69     <p>
70       Note the reference to the file <code>../csc.dtd</code>. This
71       file is located in the <code>www/</code> directory, which is the
72       parent directory of <code>www/office/</code>, therefore we use
73       <code>../</code>. These two lines should appear at the top of
74       every CSC web page.
75     </p>
76     <p>
77       Next we start the actual page. To begin, we open a
78       <code>cscpage</code> tag with the title attribute set to the
79       title of our page. We also want to add a header with the CSC
80       logo, the current section directory and the title of the
81       page. Don't worry though, as you'll see this is really easy. Add
82       the following two lines to the end of the page:
83     </p>
84     <code>
85       &lt;cscpage title=&quot;Operating Systems the CSC
86       distributes&quot;&gt;<br />
87       &lt;header /&gt;
88     </code>
89     <p>
90       That's it! So we can see what our page looks like so far, we
91       also add the footer (with the menu, generation date, and
92       copyright information) and we close the <code>cscpage</code>
93       tag. Add the following lines to the end:
94     </p>
95     <code>
96       &lt;footer /&gt;<br />
97       &lt;/cscpage&gt;
98     </code>
99     <p>
100       Notice how in the case of <code>header</code> and
101       <code>footer</code> we have a <code>/</code> before the
102       <code>&gt;</code>? This is one of the major differences between
103       HTML and XML: tags that don't really have an end tag, such as
104       <code>&lt;br&gt;</code> have to be specified as being
105       <i>empty</i> in XML by adding a <code>/</code> before the
106       <code>&gt;</code>. This is particularily important to remember
107       when you add XHTML (XML's version of HTML) to the page.
108     </p>
109     <p>
110       Now we want to see what the resulting HTML page looks like. But
111       first we have to tell <code>make</code> about our new page. To
112       do so, open up the file <code>www/office/Makefile</code>, find
113       the line beginning with <code>INPUTS = </code> and simply add
114       <code>operating-systems.xml</code> to the end of that line. So
115       the line might look like <code>INPUTS = index.html staff.xml
116       books.xml operating-systems.xml</code>. Save
117       <code>Makefile</code> and close it. Now, in the
118       <code>www/</code> directory, type <code>make</code>. This will
119       build the whole website, (hopefully!) including our little
120       document. Once <code>make</code> is done, have a look at the
121       resulting file,
122       <code>www/office/operating-systems.html</code>. It should look
123       like <a href="editing-example1/operating-systems.html">example
124       1</a> (use your browsers Back button to return to this page
125       after viewing the example).
126     </p>
127     <p>
128       Looking at the generated page, you may have noticed that it does
129       not yet appear in the menu at the top of the page. Opening up
130       the special file <code>www/office/directory.xml</code> you will
131       see several entries, each corresponding to one of the menu
132       items. After the last line beginning with
133       <code>&lt;diritem</code>, add in the following line:
134     </p>
135     <code>
136       &lt;diritem title=&quot;"Operating Systems&quot;
137       href=&quot;operating-systems.html&quot; /&gt;
138     </code>
139     <p>
140       Now recompile the site with <code>make</code>. You should see
141       that the page now looks something like <a
142       href="editing-example2/operating-systems.html">example
143       2</a>. Also note that all the other office pages will now have a
144       reference to the new operating systems page.
145     </p>
146     <p>
147       With that out of the way, it's time to add some content. You may
148       be happy to hear that you can add regular (X)HTML to any CSC web
149       page. So, we'll add the following content between the
150       <code>&lt;header /&gt;</code> and <code>&lt;footer /&gt;</code>
151       of the page:
152     </p>
153     <code>
154       &lt;section title=&quot;List of operating systems&quot;&gt;<br/>
155       &lt;ul&gt;<br/>
156         &lt;li&gt;&lt;a href=&quot;http://www.debian.org/&quot;&gt;Debian GNU/Linux&lt;/a&gt;&lt;/li&gt;<br/>
157         &lt;li&gt;&lt;a href=&quot;http://www.freebsd.org/&quot;&gt;FreeBSD&lt;/a&gt;&lt;/li&gt;<br/>
158       &lt;/ul&gt;<br/>
159       &lt;p&gt;More operating systems may be available.&lt;/p&gt;<br/>
160       &lt;/section&gt;<br/>
161     </code>
162     <p>
163       As usual, compile your changes using <code>make</code> and have
164       a look. The resulting file should look something like <a
165       href="editing-example3/operating-systems.html">example 3</a>. A
166       few things to keep in mind are:
167     </p>
168     <ul>
169       <li>
170         Always use lower-case in your XHTML tags. XML is
171         case-sensitive. For example: <code>&lt;br/&gt;</code> is good
172         whereas <code>&lt;BR/&gt;</code> is bad.
173       </li>
174       <li>
175         Always close your tags. If it's a tag that never encloses
176         anything use the <code>&lt;tag/&gt;</code> syntax. For
177         example: <code>&lt;ul&gt; &lt;li&gt;Item
178         1&lt;br/&gt;Linebreak&lt;/li&gt; &lt;li&gt;Item
179         2&lt;/li&gt;&lt;/ul&gt;</code> is good, whereas
180         <code>&lt;ul&gt; &lt;li&gt;Item
181         1&lt;br&gt;Linebreak &lt;li&gt;Item 2&lt;/ul&gt;</code> is bad.
182       </li>
183       <li>
184         You must place HTML code inside <code>&lt;section&gt;</code>
185         tags. You can have as many section as you want on the page.
186       </li>
187     </ul>
188   </section>
189   <footer />
190 </cscpage>