$author: Ryan Rix <phrkonaleash@gmail.com>
$cdate: 3Dec2009
$mdate: 

Fedora-Tour

This document describes the backend of fedora-tour in detail. Care should be
taken to keep this document in sync with any development done on the project
to aide future contributors and maintainers.

1. File System Layout

/usr/bin/fedora-tour                 : This is the main executable for
                                     : Fedora-tour.

/usr/share/fedora-tour               :

/usr/share/fedora-tour/packages      : tourContentDescriptorsDir. The location
                                     : of Content Descriptors defining content 
				     : for Fedora-tour
				     
/usr/share/fedora-tour/content-enUS/ : tourContentDirectoryLocalized. This is
                                     : the location of the actual content, used
/usr/share/fedora-tour/content-enGB/ : in generating a full DocRoot for a 
...etc...                            : particular Package in cooperation with
                                     : the Locale entry of the Package.

2. Content Descriptors

Content Descriptors are the files in tourContentDescriptorsDir which describe
the content of a particular Fedora Tour package. These are XML descriptions of
each page and are used to generate the menues. When the application loads the
menu, it will search tourContentDescriptorsDir for a list of .xml files, parse
each one

A rough outline of the typical Content Descriptor, with explanation follows.

<!-- This is a Content Descriptor for Fedora-tour -->
<Package>
  <DisplayName>What is the Fedora Project?</DisplayName>
  <Icon>fedora-logo-sprite</Icon>
  <Comment>Fedora is a Linux based operating system that provides users with
access to the latest free and open source software, in a  stable,  secure and
easy to manage form</Comment>
  <DocRoot>what-is-fedora</DocRoot>
  <Locale>enUS</Locale>
  <Priority>1</Priority>
  <Page>
    <DisplayName>Overview</DisplayName>
    <Comment>This section provides a brief overview of the Fedora Project
             Community and Fedora Linux.</Comment>
    <File>overview.html</File>
    <Type>HTML</Type>
  </Page>
  <Page>
    <DisplayName>Our Mission and Goals</DisplayName>
    <File>mission-and-goals.html</File>
    <Type>HTML</Type>
    <Page>
       <DisplayName>Foundation 1: Freedom</DisplayName>
       <File>mission-and-goals/freedom.html</File>
       <Type>HTML</Type>
    </Page>
  </Page>
</Package>

DisplayName: This is the name that will appear on either the TreeView or
MenuView. It should be short, as the length of the visible column will be
variable.

Icon: The name of the icon to be displayed in TreeView and MenuView. Fedora-Tour
will poll standard application icon directories (/usr/share/pixmaps,
/usr/share/icons and /usr/share/icons/hicolor) for this icon. Only file's
basename is required, but if extension is provided, it will be used as first
priority, in the case of multiple icons.
* This entry is only valid as a direct child of Package.

Comment: This will be displayed as a tooltip when a user mouses over the leaf in
TreeView or the entry in MenuView.

DocRoot: The folder underneath tourContentDirectoryLocalized in which the
content resides.
* This entry is only valid as a direct child of Package.

Priority: This entry defines how Fedora-tour will sort the top menu levels, when
generating a list from many XML files. In the case of multiple packages sharing
the same priority, alphabetical order will be used.
* This entry is only valid as a direct child of Package. The order of child
pages is ascertained from the order of <Page> entities in the XML file.

Locale: The Locale of the package for i18n support. Used to generate the proper
DocRoot

Page: This entry opens a new page.

File: Where in DocRoot this Page entry resides

Type: The content type. What will be supported will be defined at some later
time than now. Currently, only HTML. TODO