Webmastering

The Web team maintain and develop the FSFE's websites — ranging from fsfe.org to project and campaign sites. Webmasters are volunteers working to enhance the organization's face to the world, and to improve the technical solutions of our web efforts.

Introduction

The technologies and programs used to maintain the FSFE web page should already be familiar to many developers and authors and might be of interest to those that have not yet discovered them.

Translators and occasional volunteers will most likely only get in touch with

XHTML – from which the web pages are generated
Subversion – for version control of web page sources
Trac – for access permission management, issue tracking and other related services.

Volunteers interested in getting deeper into the maintenance should also be familiar with

Perl – for the maintenance and page creation scripts
Apache – as the web server

Understanding how the web pages are built

The web pages of fsfe.org are maintaned as a set of XML files. The web server generates the HTML pages from these XML files automatically every ten minutes. Consequently, all editing of the pages is done in the XML files, and the HTML is never edited directly.

Every page on fsfe.org is named pagename.language.html (language being the two-letter ISO-639 code of the language, like "en" for English or "de" for German). The source files are named pagename.language.xhtml.

Some pages have a dynamic part: apart from the fixed texts taken from the XHTML file, they include information from one or several XML files. Whenever such a page is built, the build system takes the translated XML files where available, and falls back to the English version of those XML files that have not yet been translated. This way, such pages can end up with parts of the text being translated and other parts still showing in English. Examples of such pages include the start page, the news page, and the events page.

Getting access to the web pages

The source files for the web pages are stored on the fsfe-web subversion repository, hosted on the FSFE subversion server. Other services are available on the related trac instance.

To have access to these tools, just follow these instructions:

If you are a Fellow of the FSFE you already have read access to subversion and trac, just log in with your usual Fellowship username and password.

To have write access to the subversion repository, and the trac wiki and ticket system, just write to system-hackers@fsfeurope.org
Everyone else can register a guest account for the subversion and trac, using the web form at https://trac.fsfe.org/fsfe-web/register. As soon as you register, you'll have read access to the subversion repository and you can log into the trac site (please note that a guest- prefix will be added to the username you choose). A notification message will be automatically sent to the repository admin, that will enable write access as soon as possible.

Checking out a SVN branch to work on

The subversion repository has two main code bases for the FSFE website, the SVN trunk, which is used to build the production instance of the website at http://fsfe.org/, and the test branch, which is used to build http://test.fsfe.org/.

For day-to-day work, like adding news items, translating pages (or even developing small changes to the website) you will need to check out the SVN trunk:

svn --username YOURNAME co https://svn.fsfe.org/fsfe-web/trunk

To work on major changes to the website, including debugging new features that could potentially break the site, you are encouraged to check out the test branch of the SVN repository:

svn --username YOURNAME co https://svn.fsfe.org/fsfe-web/branches/test

Please note that a full working copy will require about 160M; if you only plan to work on part of the website, you can check out only the directories that you are interested in. You can browse the SVN tree online to find out what you are interested in.

Working with the repository

After you checked out the repository the first time, you should execute

$ svn update

every time before you work on a specific file.

If you want to add new files or directories to the repository you have to execute

$ svn add filename

To post your changes to the server, no matter be it a new file or a modification in an existing file, execute

$ svn commit filename

and your default editor will open to allow for some description of your changes.

In subversion, keyword substitution must be enabled explicitely on every file. Since we use some keywords on .xml and .xhtml files (for example the $Author$ keyword on the page footer), you can automate enabling keywords adding the following snippet to your ~/.subversion/config file:

enable-auto-props = yes

[auto-props]
*.xml = svn:keywords=Date Author Id Revision;svn:mime-type=text/xml;svn:eol-style=native
*.xhtml = svn:keywords=Date Author Id Revision;svn:mime-type=text/xhtml;svn:eol-style=native

If you are used to work with CVS, you will easily start working with SVN; as you have noticed, the basic commands are very similar. To learn more, you can see an overview of the differences between CVS and SVN at Subversion for CVS Users, and a quick reference comparison of CVS and SVN commands at CVS to SVN Crossover Guide

You can download a detailed manual for SVN at the Subversion book page (we are using the 1.5 release of SVN).

Coordination tools

The work on the website pages is coordinated on the Webmasters mailing list.

The fsfe-web trac instance provides some further tools to help coordination: a SVN repository web browser, an issue tracking system and a wiki.

You can find out more about using trac at the TracGuide wiki page.

If you want to keep track with all commits that are done to the web page sources, you can also subscribe to the commit notification mailing list and you will get a mail for every change posted to the source tree.

Responsible handling of write access

If you have write access to the web pages, please subscribe to the Webmasters mailing list.

Please bear in mind that all your changes will become effective and visible automatically, without any further action of anybody. Consequently, there are a few things we would request you to do whenever you commit changes or new files:

The FSFE is held responsible for the content of the web pages. Please do not commit modifications that change the meaning of the text without approval from a core team member of the FSFE. (This is not necessary for translations of already existing content.)
If you are posting translations, and there is any chance that others can proofread it, use that chance. You can use the Translators mailing list to ask for proofreading. Whether you are translating files or proofreading them, you are encouraged to spell-check files using some automated tools, such as GNU aspell, ispell, or your favourite spell-checker. For example, to use GNU aspell on a Debian GNU/Linux system, just install the packages aspell and aspell-XX (where "XX" is your language code), then run the command

aspell -H -d language -c file.xhtml

where "language" is the name of the dictionary for your language; the -d option can be omitted if your UNIX locale is the same as the language of the dictionary).
Make sure that all files are proper XML. By default, the SVN server will check the XML syntax of files with .xml and .xhtml extensions, and will forbid the commit if XML errors are found. To avoid this, you can check your files before committing them, in one of the following ways.

There is a script named /trunk/tools/validate.pl that helps finding errors in the markup. Improper XML breaks the automatic build process of the web pages and blocks updates for the complete FSFE website. If you suspect the build process to broken, you can view the log of the last build run on our status pages.

The validate.pl script requires the XML::LibXML Perl module; if this is not installed on your system, you can validate files using your favourite XML validator. For example you can use the command line xmllint utility from the libxml2 project.

If you are using the Debian GNU/Linux distribution, install the libxml2-utils package; run the command

xmllint --noout file.xhtml

where file specifies the file you want checked, and watch for possible error messages.
Make sure the encoding of the file is consistent with the content of the "encoding" attribute declared in the first line of the file. For example, if your file is encoded as "iso-8859-1" (also known as "latin-1" encoding), the first line of the file should read

<?xml version="1.0" encoding="iso-8859-1" ?>

Another valid encoding is the unicode, or "UTF-8" encoding. If you want to change the encoding of a file, you can use the standard iconv utility, as in the following example (which converts a file from the "latin1" to the "utf-8" encoding):

iconv -f LATIN1 -t UTF8 inputfile > outputfile

Please coordinate with other people who also have SVN commit access to make sure that translations and fixes contributed by people without commit access are committed properly after they have been proofread. Of course, please check these files before you commit them like you check your own files.

Further information

Given that the FSFE webpage has a European/global level and user-chosen local levels that supplement them for information that is country-specific, the layout has a certain complexity that is hidden entirely from the user of the page.

Unless you only wish to translate pages (see below), please make sure you have taken a look at the structural reference.

Also, there is a Texinfo documentation file Webmastering FSF Europe by Jonas Öberg, who implemented the build system for the page. Please read it to know more about how the web pages work.

To top