442 lines
15 KiB
HTML
442 lines
15 KiB
HTML
<?xml version="1.0" encoding="UTF-8" ?>
|
||
<html>
|
||
<head>
|
||
<title>Information for Webmasters - FSFE</title>
|
||
</head>
|
||
<body>
|
||
|
||
<p id="category"><a href="/contribute/">Contribute</a></p>
|
||
<h1>Webmastering</h1>
|
||
|
||
<p id="introduction">
|
||
The <em>Web team </em> maintain and develop the FSFE's websites —
|
||
ranging from <a href="/">fsfe.org</a> 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.
|
||
</p>
|
||
|
||
|
||
<h2>Introduction</h2>
|
||
|
||
<p>
|
||
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.
|
||
</p>
|
||
|
||
<p>
|
||
Translators and occasional volunteers will most likely only get in touch
|
||
with
|
||
</p>
|
||
|
||
<ul>
|
||
<li>
|
||
<a href="http://en.wikipedia.org/wiki/XHTML">XHTML</a> – from
|
||
which the web pages are generated
|
||
</li>
|
||
<li>
|
||
<a href="http://subversion.tigris.org/">Subversion</a> – for
|
||
version control of web page sources
|
||
</li>
|
||
<li>
|
||
<a href="http://trac.edgewall.org/">Trac</a> – for access
|
||
permission management, issue tracking and other related
|
||
services.
|
||
</li>
|
||
</ul>
|
||
|
||
<p>
|
||
Volunteers interested in getting deeper into the maintenance should also
|
||
be familiar with
|
||
</p>
|
||
|
||
<ul>
|
||
<li>
|
||
<a href="http://www.perl.org/">Perl</a> – for the maintenance
|
||
and page creation scripts
|
||
</li>
|
||
<li>
|
||
<a href="http://www.apache.org/">Apache</a> – as the web server
|
||
</li>
|
||
</ul>
|
||
|
||
|
||
<h2>Understanding how the web pages are built</h2>
|
||
|
||
<p>
|
||
The web pages of <var>fsfe.org</var> 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.
|
||
</p>
|
||
|
||
<p>
|
||
Every page on fsfe.org is named
|
||
<var><em>pagename</em>.<em>language</em>.html</var>
|
||
(<em>language</em> being the two-letter <a
|
||
href="http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes">ISO-639
|
||
code</a> of the language, like "en" for English or "de" for German).
|
||
The source files are named
|
||
<var><em>pagename</em>.<em>language</em>.xhtml</var>.
|
||
</p>
|
||
|
||
<p>
|
||
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 <a href="/">start page</a>, the
|
||
<a href="/news/">news page</a>, and the <a href="/events/">events
|
||
page</a>.
|
||
</p>
|
||
|
||
|
||
<h2>Getting access to the web pages</h2>
|
||
|
||
<p>
|
||
The source files for the web pages are stored on the <a
|
||
href="https://trac.fsfe.org/fsfe-web/browser">fsfe-web subversion
|
||
repository</a>, hosted on the FSFE subversion server. Other
|
||
services are available on the related <a
|
||
href="https://trac.fsfe.org/fsfe-web">trac instance</a>.
|
||
</p>
|
||
|
||
<p>
|
||
To have access to these tools, just follow these instructions:
|
||
</p>
|
||
|
||
<ul>
|
||
<li>
|
||
<p>
|
||
If you are a <a href="http://fellowship.fsfe.org">Fellow of
|
||
the FSFE</a> you already have read access to subversion and
|
||
trac, just log in with your usual Fellowship username and
|
||
password.
|
||
</p>
|
||
|
||
<p>
|
||
To have write access to the subversion repository, and the
|
||
trac wiki and ticket system, just write to
|
||
<a
|
||
href="mailto:system-hackers@fsfeurope.org">system-hackers@fsfeurope.org</a>
|
||
</p>
|
||
</li>
|
||
|
||
<li>
|
||
<p>
|
||
Everyone else can register a guest account for the subversion
|
||
and trac, using the web form at <a
|
||
href="https://trac.fsfe.org/fsfe-web/register">https://trac.fsfe.org/fsfe-web/register</a>.
|
||
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 <var>guest-</var> 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.
|
||
</p>
|
||
</li>
|
||
</ul>
|
||
|
||
|
||
<h3>Checking out a SVN branch to work on</h3>
|
||
|
||
<p>
|
||
The subversion repository has two main code bases for the FSFE
|
||
website, the <a
|
||
href="https://trac.fsfe.org/fsfe-web/browser/trunk">SVN
|
||
<em>trunk</em></a>, which is used to build the production instance
|
||
of the website at <a href="http://fsfe.org/">http://fsfe.org/</a>, and
|
||
the <a
|
||
href="https://trac.fsfe.org/fsfe-web/browser/branches/test"><em>test</em>
|
||
branch</a>, which is used to build <a
|
||
href="http://test.fsfe.org/">http://test.fsfe.org/</a>.
|
||
</p>
|
||
|
||
<p>
|
||
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:
|
||
</p>
|
||
|
||
<p class="terminal">svn --username <var>YOURNAME</var> co https://svn.fsfe.org/fsfe-web/trunk</p>
|
||
|
||
<p>
|
||
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 <em>test</em> branch of the SVN repository:
|
||
</p>
|
||
|
||
<p class="terminal">svn --username <var>YOURNAME</var> co https://svn.fsfe.org/fsfe-web/branches/test</p>
|
||
|
||
<p>
|
||
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 <a
|
||
href="https://trac.fsfe.org/fsfe-web/browser">browse the SVN
|
||
tree</a> online to find out what you are interested in.
|
||
</p>
|
||
|
||
|
||
<h2>Working with the repository</h2>
|
||
|
||
<p>
|
||
After you checked out the repository the first time, you should
|
||
execute
|
||
</p>
|
||
|
||
<p class="terminal">$ svn update</p>
|
||
|
||
<p>
|
||
every time before you work on a specific file.
|
||
</p>
|
||
|
||
<p>
|
||
If you want to add new files or directories to the repository you have to
|
||
execute
|
||
</p>
|
||
|
||
<p class="terminal">$ svn add <em>filename</em></p>
|
||
|
||
<p>
|
||
To post your changes to the server, no matter be it a new file or a
|
||
modification in an existing file, execute
|
||
</p>
|
||
|
||
<p class="terminal">$ svn commit <em>filename</em></p>
|
||
|
||
<p>
|
||
and your default editor will open to allow for some description of your
|
||
changes.
|
||
</p>
|
||
|
||
<p>
|
||
In subversion, <a
|
||
href="http://svnbook.red-bean.com/en/1.5/svn.advanced.props.special.keywords.html">keyword
|
||
substitution</a> must be enabled explicitely on every file. Since we
|
||
use some keywords on <var>.xml</var> and <var>.xhtml</var> files (for
|
||
example the <var>$</var><var>Author</var><var>$</var> keyword on the
|
||
page footer), you can automate enabling keywords adding
|
||
the following snippet to your <var>~/.subversion/config</var>
|
||
file:
|
||
</p>
|
||
|
||
<pre class="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
|
||
</pre>
|
||
|
||
<p>
|
||
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
|
||
<a href="http://svnbook.red-bean.com/en/1.5/svn.forcvs.html">Subversion for
|
||
CVS Users</a>, and a quick reference comparison of CVS and SVN commands at
|
||
<a
|
||
href="http://svn.apache.org/repos/asf/subversion/trunk/doc/user/cvs-crossover-guide.html">CVS to SVN Crossover Guide</a>
|
||
</p>
|
||
|
||
<p>
|
||
You can download a detailed manual for SVN at the <a
|
||
href="http://svnbook.red-bean.com/">Subversion book</a> page
|
||
(we are using the 1.5 release of SVN).
|
||
</p>
|
||
|
||
|
||
<h2>Coordination tools</h2>
|
||
|
||
<p>
|
||
The work on the website pages is coordinated on the <a
|
||
href="http://mail.fsfeurope.org/mailman/listinfo/web">Webmasters mailing
|
||
list</a>.
|
||
</p>
|
||
|
||
<p>
|
||
The <a href="https://trac.fsfe.org/fsfe-web">fsfe-web trac instance</a>
|
||
provides some further tools to help coordination: a SVN repository web
|
||
browser, an issue tracking system and a wiki.
|
||
</p>
|
||
|
||
<p>
|
||
You can find out more about using trac at the <a
|
||
href="https://trac.fsfe.org/fsfe-web/wiki/TracGuide">TracGuide</a> wiki
|
||
page.
|
||
</p>
|
||
|
||
<p>
|
||
If you want to keep track with all commits that are done to the web page
|
||
sources, you can also subscribe to the <a
|
||
href="http://mail.fsfeurope.org/mailman/listinfo/web-cvs-notify">commit
|
||
notification mailing list</a> and you will get a mail for every change
|
||
posted to the source tree.
|
||
</p>
|
||
|
||
|
||
<h2>Responsible handling of write access</h2>
|
||
|
||
<p>
|
||
If you have write access to the web pages, please subscribe to the <a
|
||
href="http://mail.fsfeurope.org/mailman/listinfo/web">Webmasters mailing
|
||
list</a>.
|
||
</p>
|
||
|
||
<p>
|
||
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:
|
||
</p>
|
||
|
||
<ul>
|
||
<li>
|
||
<p>
|
||
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 <a href="/about/members.html">core team
|
||
member of the FSFE</a>. (This is not necessary for translations of
|
||
already existing content.)
|
||
</p>
|
||
</li>
|
||
|
||
<li>
|
||
|
||
<p>
|
||
If you are posting translations, and there is any chance that others
|
||
can proofread it, use that chance. You can use the <a
|
||
href="http://mail.fsfeurope.org/mailman/listinfo/translators">Translators
|
||
mailing list</a> 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 <a
|
||
href="http://aspell.net/">GNU aspell</a> on a Debian GNU/Linux
|
||
system, just install the packages <em>aspell</em> and
|
||
<em>aspell-<strong>XX</strong></em> (where "XX" is your language
|
||
code), then run the command
|
||
</p>
|
||
|
||
<p class="terminal">
|
||
aspell -H -d <em>language</em> -c file.xhtml
|
||
</p>
|
||
|
||
<p>
|
||
where "language" is the name of the dictionary for your language; the
|
||
<var>-d</var> option can be omitted if your UNIX locale is the same
|
||
as the language of the dictionary).
|
||
</p>
|
||
|
||
</li>
|
||
|
||
<li>
|
||
|
||
<p>
|
||
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.
|
||
</p>
|
||
<p>
|
||
There is a script named
|
||
<var>/trunk/tools/validate.pl</var> 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 <a
|
||
href="http://status.fsfe.org/">view the log of the last build
|
||
run</a> on our <a href="http://status.fsfe.org/">status
|
||
pages</a>.
|
||
</p>
|
||
|
||
<p>
|
||
The <var>validate.pl</var> script requires the <em>XML::LibXML</em>
|
||
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 <em>xmllint</em> utility from the <a
|
||
href="http://xmlsoft.org/"><em>libxml2</em> project</a>.
|
||
</p>
|
||
|
||
<p>
|
||
If you are using the Debian GNU/Linux distribution, install the
|
||
<em>libxml2-utils</em> package; run the command
|
||
</p>
|
||
|
||
<p class="terminal">xmllint --noout <em>file</em>.xhtml</p>
|
||
|
||
<p>
|
||
where <em>file</em> specifies the file you want checked, and watch
|
||
for possible error messages.
|
||
</p>
|
||
|
||
</li>
|
||
|
||
<li>
|
||
|
||
<p>
|
||
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
|
||
</p>
|
||
|
||
<p class="file"><?xml version="1.0" encoding="iso-8859-1" ?></p>
|
||
|
||
<p>
|
||
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
|
||
<em>iconv</em> utility, as in the following example (which converts a
|
||
file from the "latin1" to the "utf-8" encoding):
|
||
</p>
|
||
|
||
<p class="terminal">iconv -f LATIN1 -t UTF8 <em>inputfile</em> > <em>outputfile</em></p>
|
||
|
||
</li>
|
||
</ul>
|
||
|
||
<p>
|
||
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.
|
||
</p>
|
||
|
||
|
||
<h2>Fetch tagged news and events, implement a country page</h2>
|
||
|
||
<p>
|
||
Please see <a href="/contribute/web/tagging.html">the dedicated howto</a> for this purpose.
|
||
</p>
|
||
|
||
|
||
<h2>Further information</h2>
|
||
|
||
<p>
|
||
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.
|
||
</p>
|
||
|
||
<p>
|
||
Also, there is a <a href="http://www.texinfo.org"
|
||
target="_blank">Texinfo</a> documentation file <em><a href="/README.texi"
|
||
target="_blank">Webmastering FSF Europe</a></em> by <a
|
||
href="mailto:oberg@fsfeurope.org">Jonas Öberg</a>, who implemented the
|
||
build system for the page. Please read it to know more about how the web
|
||
pages work.
|
||
</p>
|
||
|
||
</body>
|
||
|
||
<timestamp>$Date$ $Author$</timestamp>
|
||
</html>
|
||
<!--
|
||
Local Variables: ***
|
||
mode: xml ***
|
||
End: ***
|
||
-->
|