documentation/torproject.tex (2a9aaa802) - tor-webwml.git

torproject.tex

\documentclass[11pt]{article}
\begin{document}

\section{introduction}
This document (which may be found in /documentation) explains the wml code used to generate the Tor Project website. The original Tor Project documentation in /include/README gives a brief overview of Tor Project's use of wml. Some additional embedded perl was added to generate static content, namely navigation bars and a language selection dropdown in the footer of the page. Adding new content to the site is done by adding the new wml source files and an entry in the relavent navigation bar. Section \ref{side-navigation} outlines the syntax for the menu structure and section.

%\section{/}
%   home.wml 
%
%\section{/about}
%   about.wml
%   board.wml
%   contact.wml
%   contributors.wml
%   future.wml
%   gsoc.wml
%   overview.wml
%   people.wml
%   sidenav.wmi
%   sponsors.wml
%   staying.wml
%   torusers.wml
%   translators.wml
%   volunteers.wml
%   why.wml
%
%\section{/docs}
%   android.wml
%   bridges.wml
%   debian-vidalia.wml
%   debian.wml
%   documentation.wml
%   faq-abuse.wml
%   faq.wml
%   gloassary.wml
%   hidden-services.wml
%   installguide.wml
%   manual.wml
%   N900.wml
%   rpms.wml
%   running-a-mirror.wml
%   sidenav.wmi
%   tor-doc-osx.wml
%   tor-doc-relay.wml
%   tor-doc-unix.wml
%   tor-doc-web.wml
%   tor-doc-windows.wml
%   tor-hidden-service.wml
%   tor-manual-dev.wml
%   tor-manual.wml
%   trademark-faq.wml
%   verifying-signatures.wml
%
%\section{/download}
%   download.wml
%   easy-download.wml
%   thankyou.wml
%
%\section{/getinvolved}
%   developers.wml
%   everyone.wml
%   getinvolved.wml
%   mirrors.wml
%   open-positions.wml
%   sidenav.wmi
%   technical.wml
%   translation-overview.wml
%   translation-portal.wml
%   translation-status.wml
%   translation.wml
%   tshirt.wml
%   volunteer.wml
%
%\section{/press}
%   2008-12-19-roadmap-press-release.wml
%   2009-03-12-performance-roadmap-press-release.wml
%   2010-03-25-tor-store-press-release.wml
%   index.wml
%   info.wmi
%   inthemedia.wml
%   pressreleases.wml
%   press.wml
%   sidenav.wmi
%
%\section{/projects}
%   clientside.wml
%   google.wml
%   hidserv.wml
%   index.wml
%   lowbandwidth.wml
%   projects.wml
%   sampleproject.wml
%   sidenav.wmi
%   torbutton-faq.wml
%   torbutton-options.wml
%   torbutton.wml

\section{/include}
Files present:\\
foot.wmi - document footer\\
functions.wmi - translation functions\\
head.wmi - document head\\
info.wmi - info snippet\\
links.wmi - functions to generate links\\
mirrors-table.wmi - mirror list\\
navigation.wmi - input to head.wmi navigation menu\\
perl-globals.wmi - global variables\\
side.wmi - side menu navigation\\
versions.wmi - version number macros\\

\subsection{head.wmi}
  This is the main header for all site documents. The main navigation bar is generated at build time here by referencing a language-specific file (navigation.wmi) which contains a list of URLs and the link text to display.
  
\begin{verbatim}
   example path: /en/navigation.wmi
   example path: /de/navigation.wmi
\end{verbatim}
  
  Translators can create a language-specific version in order to generate the top navbar.

The second navigation element, 'calltoaction' is generated similarly from the second list in navigation.wmi
  
\subsection{foot.wmi}
   This is the footer for all site documents. There are quick links to site content as well as a translation selection menu.
   Translation selection:
  At build time, available languages are detected by the presence of a language subdirectory:

example:

/about/en/about.wml contains valid translations for nl, and de if files /about/nl/about.wml and /about/de/about.wml exist. For each translated language a <select> <option> is created. Javascript onClick is used to direct clients that support javascript, but if the client does not support javascript a simple perl cgi trampoline may be used to redirect the client to the selected page on form submit. (see: \ref{cgi-trampoline})
\begin{verbatim}
<form action="../cgi-bin/languageswitch.cgi">
   <select name="Language" id="lang">
      <option value="docs/tor-doc-relay.html.de"
          onclick="window.location='tor-doc-relay.html.de'">Deutsch</option>
      <option value="docs/tor-doc-relay.html.it"
          onclick="window.location='tor-doc-relay.html.it'">Italiano</option>
   </select>
   <input class="go" type="submit" name="submit" value="Go">
</form>
\end{verbatim}

\label{side-navigation}
\subsection{side.wmi}
This is the side navbar generator for documents that utilize a side navbar. A language-specific sidenav.wmi file contains a hierarchical structure of menu elements.

\begin{verbatim}
example path: /about/en/sidenav.wmi
example path: /docs/de/sidenav.wmi
\end{verbatim}

Each element contains url and txt fields and may also contain a list of subelements. At build time the navbar is rendered for each page so that nested elements are expanded/collapsed and css styles are set. Untranslated pages default to the english version. External links (e.g. http://check.torproject.org) are inserted without modification.

example structure:

\begin{verbatim}

$sidenav = [
      {'url'  => 'about/about',
       'txt'  => 'Tor Overview',
       'subelements' => [
          {'url'  => 'about/why',
           'txt'  => 'Why We Need Tor',
          },
          {'url'  => 'about/staying',
           'txt'  => 'Staying Anonymous',
          },
          {'url'  => 'about/future',
           'txt'  => 'Future of Tor',
          }]
      }
  ];

\end{verbatim}

\subsection{functions.wmi}
An additional function pageToURL(\$\$) performs the same conversion as <page> tags, but may be called from within eperl statements (such as those used to generate the navigation structure). The arguments to the function are \$page, \$lang, where \$page is the document path (e.g. /docs/tor-doc-osx) and \$lang is the language (e.g. en, de, it).

\subsection{perl-globals.wmi}
An additional global variable (\$WML\_SRC\_DIRNAME) was added for use in determining the input file path.

\label{cgi-trampoline}
\section{languageswitch.cgi}
   The language selection dropdown (see document footer: foot.wmi) requires javascript support or a server-side script to handle a form submit. languageswitch.cgi is a perl cgi script that returns a URL passed by GET as a redirect.
\begin{verbatim}
#!/usr/bin/env perl

use CGI qw(:standard);
my $lang = param('Language');
print "Status: 302 Moved\nLocation: /$lang\n\n";
\end{verbatim}

\section{building the site}
\subsection{build prerequisites}
The ubuntu package wml has these dependencies:

eperl, iselect, libbit-vector-perl, libcarp-clan-perl,
libgetopt-argvfile-perl, libhtml-clean-perl,
libimage-size-perl, libperl5.10, libtidy-0.99-0,
libyaml-syck-perl, linklint, m4, mp4h, slice, tidy, txt2html, wml

Make sure that you have checked out the translation project: \\
https://svn.torproject.org/svn/translation/ \\
as well as the website project: \\
https://svn.torproject.org/svn/website/

In addition to the translation project, you must also check out stable and development branches of tor, which are used to generate the online version of the manpages. The path to these repositories must be set the Makefile as follows:

\begin{verbatim}
TORSVNSTABLE = PATH_TO_TOR_STABLE  # the path to stable branch
TORGIT = PATH_TO_TOR_DEVELOPMENT   # the path to development branch
STABLETAG = CURRENT_STABLE_TAG     # stable tag
DEVTAG = CURRENT_DEV_TAG           # dev tag
\end{verbatim}

\subsection{build translation po files}
\begin{verbatim}
./wml2po.sh
\end{verbatim}

This script parses the english wml and generates po files for use with pootle
\subsection{import translated pages}
\begin{verbatim}
make translations
\end{verbatim}

This commands calls the script po2wml.sh, which converts translated po files to language-specific wml which will then build translated pages.
\subsection{build}
\begin{verbatim}
make
\end{verbatim}
\end{document}

tor-webwml.git

first cut of the new, shiny tor website as wml.