Difference between revisions of "Website"

From CSCWiki
Jump to navigation Jump to search
m
 
(38 intermediate revisions by 9 users not shown)
Line 1: Line 1:
= Checking out the website =
+
'''''<big>NOTE: THIS IS FOR THE OLD WEBSITE, THE NEW ONE IS HOSTED AT https://git.csclub.uwaterloo.ca/www/www-new</big>'''''
  
The website is managed in a [http://git.or.cz/ git] repository.
+
== Dependencies ==
  
Anyone can checkout the website using git-clone:
+
You'll need to install a few dependencies to build the website; the following command will install all dependencies if you're using a Debian-based system:
git-clone caffeine:/users/www/www/.git
 
  
This creates a directory called 'www' that contains the entire website and repository. If you want to make changes to the website, you'll need to ask someone on the [[Systems Committee]] to add you to the 'www' group and to the 'git' mailing list. The easiest way to see your changes without committing them is to create a symlink into your public 'www' directory. For example, say your local copy of the website lives in '/users/dtbartle/csc/www'. You could symlink '/users/dtbartle/csc/www' to '/users/dtbartle/www/csc':
+
sudo aptitude install python python-libxslt1 python-libxml2 python-tz git-core python-ldap
ln -s /users/dtbartle/csc/www /users/dtbartle/www/csc
 
  
Then you could see your copy of the website at this URL:
+
== Checking out the website ==
  http://csclub.uwaterloo.ca/~dtbartle/csc/
+
 
 +
The website is managed in a [http://git.csclub.uwaterloo.ca/?p=www/www.git git repository].
 +
 
 +
Any member can checkout the website using git clone:
 +
git clone /users/www/www
 +
 
 +
This creates a directory called "www" that contains the entire website and its history. If you want to make changes to the website, you'll need to ask someone on the [[Systems Committee]] to add you to the "www" group. You should also subscribe to our [http://csclub.uwaterloo.ca/mailman/listinfo/git git mailing list].
 +
 
 +
== Testing your changes ==
 +
 
 +
You should test any changes you make before pushing them out for all the world to see. The easiest way to see your changes without committing them is to create a symlink into your public "www/build" directory. For example, say your local copy of the website lives in "/users/$USER/csc/www". You could symlink "/users/$USER/csc/www/build" to "/users/$USER/www/csc". Do this by typing:
 +
 
 +
ln -s /users/$USER/csc/www/build /users/$USER/www/csc
 +
 
 +
Type make in the directory. Now you can see your copy of the website at this URL:
 +
 
 +
  http://csclub.uwaterloo.ca/~USERNAME/csc/
  
 
= Committing changes to the website =
 
= Committing changes to the website =
  
 
If you add a new file to the website, you can add it to git:
 
If you add a new file to the website, you can add it to git:
  git-add file
+
  git add file
  
 
To delete a file type:
 
To delete a file type:
  git-rm file
+
  git rm file
  
 
And to rename or move a file type:
 
And to rename or move a file type:
  git-mv old-file new-file
+
  git mv old-file new-file
  
 
Once you're done modifying the website you can commit your changes:
 
Once you're done modifying the website you can commit your changes:
  git-commit -a
+
  git commit -a
  
 
The above command only commits the change to your local repository; you need to push the changes out to the master repository:
 
The above command only commits the change to your local repository; you need to push the changes out to the master repository:
  git-push
+
  git push
  
The above command will also automatically rebuild the website and send out an email to the git mailing list with the details of your change.
+
The above command will also automatically rebuild the website and send out an email to the git mailing list with the details of your change, as long as you are on caffeine when you push.
  
 
= Building the website =
 
= Building the website =
Line 36: Line 50:
 
  make
 
  make
  
This will build the website into the build directory. When git-pushing, the website will be built into /var/www-csc.
+
This will build the website into the build directory. When git-pushing, the website will be built into /srv/www-csc.
  
 
You can remove the generated files by running:
 
You can remove the generated files by running:
Line 51: Line 65:
 
* news.xml - past and upcoming items
 
* news.xml - past and upcoming items
 
* media/index.xml - media items (e.g. talks)
 
* media/index.xml - media items (e.g. talks)
* about/exec.xml - the current club exec
 
  
 
XML should be fairly easy to work with. Some important things to remember:
 
XML should be fairly easy to work with. Some important things to remember:
 
* All opening tags must be closed.
 
* All opening tags must be closed.
* All tags should generally be in lowercase.
+
* All tags should be in lowercase.
* Tag and attribute names and case-sensitive.
+
* Tag and attribute names are case-sensitive.
  
 
If you want more information on XML, the following are good resources:
 
If you want more information on XML, the following are good resources:
Line 64: Line 77:
 
== XSLT ==
 
== XSLT ==
  
If you want to change the HTML layout you'll want to modify 'default.css'. or the XSLT files. Almost all XSLT files are located in the 'xsl' directory. We are using XSLT 2.0, which is generally backwards compatible with XSLT 1.0.
+
If you want to change the HTML layout you'll want to modify the XSLT files. Almost all XSLT files are located in the 'xsl' directory. We are using XSLT 1.0 and a python front-end (xmlproc.py) to libxslt.
 +
 
 +
== CSS ==
 +
 
 +
If you want to change the style of the HTML you'll want to modify default.css. We primarily target Firefox 2.0 but every effort should be made to use CSS that renders correctly in Internet Explorer 6.0 and other browsers. You can test various Internet Explorer versions from Linux by installing [http://www.tatanka.com.br/ ies4linux]. There's also [http://browsershots.org/ browsershots.org], which will take screenshots of a page in various browsers.
 +
 
 +
== Data files ==
 +
 
 +
Data files, such as PDF's, should be copied to /srv/www-csc-misc. These files are accessible via http://csclub.uwaterloo.ca/misc/.
 +
 
 +
== Media ==
 +
 
 +
To change media files, you need to update the /media/index.xml file. The format of new entries should be fairly self evident based on the pre-existing entries.
 +
 
 +
Once you have a bunch of MTS data from a talk, you need to run it through the scripts in ~git/public/csc-media to compress it and generate thumbnails (check them out, and read the readme). The scripts generate a fairly large amount of output. If you happen to be near the member quota you will want to create symlinks for encodes and timings into /scratch.
 +
 
 +
The scripts should get run on a beefy machine (ie, high-fructose-corn-syrup).
 +
 
 +
Once the video files have been encoded, the encoded files need to get uploaded to mirror. The website automagically links the <*file /> tags to "mirror.csclub.../csclub/TALK_FILE". Contact syscom to do this.
  
 
= Website vs Wiki =
 
= Website vs Wiki =
Line 82: Line 113:
 
* Information that changes frequently
 
* Information that changes frequently
 
* Information that any club member should be able to add to or modify
 
* Information that any club member should be able to add to or modify
* Information on creating talks and posting them
+
* Exec and office staff guides/manuals
 +
* System and hardware documentation
 
* Past funding opportunities and advice (assuming this can be publicly posted)
 
* Past funding opportunities and advice (assuming this can be publicly posted)
 
* Contacts (e.g. CSCF, SCS) (assuming this can be publicly posted)
 
* Contacts (e.g. CSCF, SCS) (assuming this can be publicly posted)
Line 92: Line 124:
 
== Email Addresses ==
 
== Email Addresses ==
  
Email addresses should be wrapped in <email> tags. For example, if you want to include the email president@csclub.uwaterloo.ca you should include the following xml snippet:
+
'''Note''': this convention is not currently used and is not recommended for now.
  <email>president@csclub.uwaterloo.ca</email>
+
 
Make sure that this is on a single line; i.e. don't do this:
+
Email addresses should be wrapped in <email> tags. For example, if you want to include the email example@csclub.uwaterloo.ca you should include the following xml snippet:
 +
  <email>example@csclub.uwaterloo.ca</email>
 +
Leading and trailing whitespace will be stripped so it is safe to do this:
 
  <email>
 
  <email>
   president@csclub.uwaterloo.ca
+
   example@csclub.uwaterloo.ca
 
  </email>
 
  </email>
Currently this just generates an standard mailto link. In the future it may generate an image containing the address, to avoid spam.
+
Currently this just generates an standard mailto link. In order to prevent spammers from harvesting address, I want to generate an image that contains the address.
  
My current plan is to generate the email images while running make. I would need to somehow call an external command from within the xslt processor. The program would be passed the email address and would generate a file of the form user@domain.png. The email images would be stored in http://csclub.uwaterloo.ca/emails/.
+
My current plan is to generate the email images while running make. This would be accomplished by creating a csc:email function that generates and saves the image to http://csclub.uwaterloo.ca/images/. The image name would be generated from HMAC(email, key), where key is some secret key/phrase.
  
 
= Feature Requests and Ideas =
 
= Feature Requests and Ideas =
  
* Replace webapps with debian packages
 
 
* Possibly move club list onto wiki.
 
* Possibly move club list onto wiki.
* Auto-generate exec page; this requires putting exec positions in LDAP.
 
 
* Convert cellspacing and cellpadding to CSS equivalents.
 
* Convert cellspacing and cellpadding to CSS equivalents.
 
* Make RSS and ICS feeds more prominent.
 
* Make RSS and ICS feeds more prominent.
 
* Replace or compliment /events with a web-based calendar?
 
* Replace or compliment /events with a web-based calendar?
* Replace all email addresses with generated graphics?
+
* Replace all email addresses with generated graphics or javascript obfuscation?
* On media pages, get rid of trailing comma.
 
 
* Replace &lt;br&gt;'s with &lt;p&gt;'s wherever it makes sense.
 
* Replace &lt;br&gt;'s with &lt;p&gt;'s wherever it makes sense.
 
* Replace &lt;strong&gt;, &lt;b&gt;, &lt;i&gt;, etc... tags with CSS.
 
* Replace &lt;strong&gt;, &lt;b&gt;, &lt;i&gt;, etc... tags with CSS.
 
* Highlight (e.g. make left bar green) current page in directory header
 
* Highlight (e.g. make left bar green) current page in directory header
  
= Bandwidth Limiting =
+
[[Category:Software]]
 
+
[[Category:Guides]]
Due to recent increases in bandwidth usage a bandwidth module may be nice to install for our web-servers.
+
[[Category:Policy]]
 
+
[[Category:Projects]]
Debian package name: "libapache2-mod-cband"
 
 
 
Lots of configuration allowed.
 

Latest revision as of 14:54, 19 October 2022

NOTE: THIS IS FOR THE OLD WEBSITE, THE NEW ONE IS HOSTED AT https://git.csclub.uwaterloo.ca/www/www-new

Dependencies

You'll need to install a few dependencies to build the website; the following command will install all dependencies if you're using a Debian-based system:

sudo aptitude install python python-libxslt1 python-libxml2 python-tz git-core python-ldap

Checking out the website

The website is managed in a git repository.

Any member can checkout the website using git clone:

git clone /users/www/www

This creates a directory called "www" that contains the entire website and its history. If you want to make changes to the website, you'll need to ask someone on the Systems Committee to add you to the "www" group. You should also subscribe to our git mailing list.

Testing your changes

You should test any changes you make before pushing them out for all the world to see. The easiest way to see your changes without committing them is to create a symlink into your public "www/build" directory. For example, say your local copy of the website lives in "/users/$USER/csc/www". You could symlink "/users/$USER/csc/www/build" to "/users/$USER/www/csc". Do this by typing:

ln -s /users/$USER/csc/www/build /users/$USER/www/csc

Type make in the directory. Now you can see your copy of the website at this URL:

http://csclub.uwaterloo.ca/~USERNAME/csc/

Committing changes to the website

If you add a new file to the website, you can add it to git:

git add file

To delete a file type:

git rm file

And to rename or move a file type:

git mv old-file new-file

Once you're done modifying the website you can commit your changes:

git commit -a

The above command only commits the change to your local repository; you need to push the changes out to the master repository:

git push

The above command will also automatically rebuild the website and send out an email to the git mailing list with the details of your change, as long as you are on caffeine when you push.

Building the website

Once you've checked out the website, you can build the website by running:

make

This will build the website into the build directory. When git-pushing, the website will be built into /srv/www-csc.

You can remove the generated files by running:

make clean

Modifying the website

XML

The website's data is contained in a series of XML files. A series of XSLT files are used to transform the XML data into HTML files. If you want to add new information to the website you'll want to modify the XML files.

Some notable XML files:

  • events.xml - past and upcoming events
  • news.xml - past and upcoming items
  • media/index.xml - media items (e.g. talks)

XML should be fairly easy to work with. Some important things to remember:

  • All opening tags must be closed.
  • All tags should be in lowercase.
  • Tag and attribute names are case-sensitive.

If you want more information on XML, the following are good resources:

XSLT

If you want to change the HTML layout you'll want to modify the XSLT files. Almost all XSLT files are located in the 'xsl' directory. We are using XSLT 1.0 and a python front-end (xmlproc.py) to libxslt.

CSS

If you want to change the style of the HTML you'll want to modify default.css. We primarily target Firefox 2.0 but every effort should be made to use CSS that renders correctly in Internet Explorer 6.0 and other browsers. You can test various Internet Explorer versions from Linux by installing ies4linux. There's also browsershots.org, which will take screenshots of a page in various browsers.

Data files

Data files, such as PDF's, should be copied to /srv/www-csc-misc. These files are accessible via http://csclub.uwaterloo.ca/misc/.

Media

To change media files, you need to update the /media/index.xml file. The format of new entries should be fairly self evident based on the pre-existing entries.

Once you have a bunch of MTS data from a talk, you need to run it through the scripts in ~git/public/csc-media to compress it and generate thumbnails (check them out, and read the readme). The scripts generate a fairly large amount of output. If you happen to be near the member quota you will want to create symlinks for encodes and timings into /scratch.

The scripts should get run on a beefy machine (ie, high-fructose-corn-syrup).

Once the video files have been encoded, the encoded files need to get uploaded to mirror. The website automagically links the <*file /> tags to "mirror.csclub.../csclub/TALK_FILE". Contact syscom to do this.

Website vs Wiki

In order to keep things organized, the following guidelines should be followed.

Website:

  • Information not likely to change frequently (e.g. services, general information)
  • Information that should only be modifiable by the exec
  • Official documents (e.g. constitution, policies)
  • Current and past executive
  • User and club lists
  • News, events, and media items
  • Anything we want non-members to see when they first encounter our site

Wiki:

  • Information that changes frequently
  • Information that any club member should be able to add to or modify
  • Exec and office staff guides/manuals
  • System and hardware documentation
  • Past funding opportunities and advice (assuming this can be publicly posted)
  • Contacts (e.g. CSCF, SCS) (assuming this can be publicly posted)

Also note that we can protect various pages if they shouldn't be edited in general.

Conventions

Email Addresses

Note: this convention is not currently used and is not recommended for now.

Email addresses should be wrapped in <email> tags. For example, if you want to include the email example@csclub.uwaterloo.ca you should include the following xml snippet:

<email>example@csclub.uwaterloo.ca</email>

Leading and trailing whitespace will be stripped so it is safe to do this:

<email>
  example@csclub.uwaterloo.ca
</email>

Currently this just generates an standard mailto link. In order to prevent spammers from harvesting address, I want to generate an image that contains the address.

My current plan is to generate the email images while running make. This would be accomplished by creating a csc:email function that generates and saves the image to http://csclub.uwaterloo.ca/images/. The image name would be generated from HMAC(email, key), where key is some secret key/phrase.

Feature Requests and Ideas

  • Possibly move club list onto wiki.
  • Convert cellspacing and cellpadding to CSS equivalents.
  • Make RSS and ICS feeds more prominent.
  • Replace or compliment /events with a web-based calendar?
  • Replace all email addresses with generated graphics or javascript obfuscation?
  • Replace <br>'s with <p>'s wherever it makes sense.
  • Replace <strong>, <b>, <i>, etc... tags with CSS.
  • Highlight (e.g. make left bar green) current page in directory header