This file contains documentation regarding maintenance of the
gtk-gnutella homepage at http://gtk-gnutella.sourceforge.net/.

1. SVN 

  Most of the homepage content is maintained with SVN.

  You can checkout the tree as follows:
  $ svn co https://gtk-gnutella.svn.sourceforge.net/svnroot/gtk-gnutella/trunk/htdocs htdocs

2. Structure

  The SVN repository (modulo uninteresting files) looks as follows:

    htdocs/.htaccess                # Apache htaccess
    htdocs/default.css              # Common CSS file
    htdocs/files/common.php         # Used by index.php
    htdocs/files/.htaccess          # Apache htaccess
    htdocs/files/<ISO 639 code>/    # Translated sub-documents

  The homepage repository on the webserver has additional directories
  which are not SVN-managed:

    htdocs/doxygen/                 # Doxygen source code documentation

  All text files are strictly UTF-8 encoded. The PHP script index.php
  is the core of the homepage. The default language code is "en"
  (English). If a file is missing from "files/<ISO 639 code>/", the
  script will fall back to the file from "files/en/". This allows
  partial translations of the homepage. The symlinks on the webserver
  in "htdocs/<ISO 639 code>/" make sure that files can be accessed at
  <URL>/en/, <URL>/nl/ etc.


3. Translation

  After you have checked out "htdocs" from SVN, create a new directory
  below "files/" with the ISO 639 code of the target language as name.
  The files to translate are in "files/en/". The files "intro" and
  "sidenav" should be translated first because these are what a visitor
  sees immediately when he enters the homepage. You don't need to
  translate the news_<number> files because they cover mostly old news.
  If you translate them nonetheless, translate the newest first. Some
  files contain information that is only interesting for developers. As
  developers are required to understand English, these files should be
  translate at last - if at all. Information that is interesting for the
  common user has priority.

  Copy only those files from "files/en/" that you actually translate.
  You can translate single files and submit them, the script falls back
  to the original English file if the translation is missing. You may
  make some changes to the HTML code if required for the language (due
  to very long lines or whatever) but in general the document structure
  should be kept as-is. The translation does not have to be 1:1, it
  should capture the intention and spirit of the original English text.
  Sometimes translation shows that the original text is sub-optimal. In
  such a case you should also modify the original text instead of
  translating it as-is. All documents must be UTF-8 encoded. If your
  editor does not support UTF-8 properly convert the files manually:

    $ mv file file.bak
    $ iconv -f <Your charset> -t UTF-8 file.bak > file

  To submit translations, use the SF interface:

    https://sf.net/tracker/?atid=304467&group_id=4467&func=browse

  This requires a SF account. As an alternative, simply send a mail to
  the developers' mailing list:

    gtk-gnutella-devel at lists.sourceforge.net

  If you're not subscribed to this list, your mail has to be approved
  by a list moderator which may cause some delay. You can view the archive
  and subscribe here:

      https://lists.sf.net/mailman/listinfo/gtk-gnutella-devel

  If your translated files are larger than a few kilobyte, don't send
  them directly to the list. Provide a URL to the files or ask to whom
  to send the files. Send them to the developer that answers you.

  The homepage admin has to perform the following to add a new
  translation:

    $ mkdir htdocs/<ISO 639 code>
    $ cd htdocs/<ISO 639 code>
    $ ln -s ../files
    $ ln -s ../index.php
    # Generate rss.xml or create a symlink to English version:
    $ ln -s ../en/rss.xml

  Next you have to modify index.php to add the new language option:

  Look for the following code:

        <option
           <?php if ('en' === LANG) echo 'selected' ?>
            value="en">English</option>
  
  Add a new item with 'en', "en" and English replaced appropriately.
  The equivalent of "English" should be translated to the target
  language so that native speakers of that language can easily recognize
  it.

  Further look for this:

    <link rel="alternate"
          type="text/html"
          href="/en/?page=<?php echo PAGE ?>"
          hreflang="en"
          title="English version">

  Add a new item with 'en', "en", /en/ and "English version" replaced
  appropriately. The equivalent of "English version" should be
  translated to the target language so that native speakers of that
  language can easily recognize it.

  If you reload the homepage in your browser now, the new language
  option should be available and you should see all translated content
  in the selected language.


4. Updating

  After modifying files in the SVN repository, it is required to update
  the homepage contents to make the changes effective:

    $ ssh developername@shell.sf.net
    $ /home/groups/g/gt/gtk-gnutella/update_homepage.sh


5. Language Multiplexing

  The PHP script index.php selects the language as follows:

  First it looks if the request URI matches "/<ISO 639>/". If that's
  not the case it checks for a previously stored cookie with a language
  option. If there's no cookie either, it looks at the HTTP
  Accept-Language header. At last, it looks if the selected language
  directory contains an "index.php" file. If that fails it falls back to
  "en". If the homepage was accessed through "/" instead of e.g., "/fr/"
  it stores the selected language in a cookie. So cookies override the
  Accept-Language header.

  The above is only the rough scheme, look at the code for details.
  

/* Author: Christian Biere */
/* Last-Edited: $Id$ */
/* vi: set tw=72 ts=4 et: */
