cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject [DAISY] Updated: The first pages
Date Thu, 18 Aug 2005 14:08:22 GMT
A document has been updated:

Document ID: 677
Branch: main
Language: default
Name: The first pages (unchanged)
Document Type: Simple Document (unchanged)
Updated on: 8/18/05 2:07:59 PM
Updated by: Helma van der Linden

A new version has been created, state: draft

This part has been updated.
Mime type: text/xml (unchanged)
File name:  (unchanged)
Size: 6935 bytes (previous version: 935 bytes)
Content diff:
--- <p>On your return from a meeting with the <em>HealthyCocoon</em> folks
you got
--- the contents for the first pages:</p>
+++ <p>On your return from a meeting with the <em>HealthyCocoon</em> folks
+++ agreed the contents for the first pages:</p>
    <h3>About HealthyCocoon</h3>
(16 equal lines skipped)
    fax: +31 43 1234568<br/>
+++ <h3>Services</h3>
+++ <p>[TBD]</p>
+++ <h1>Website Revision 1</h1>
+++ <p>Before we can actually start coding, it is good to make some decisions first,
+++ to avoid having to redo everything because you forgot to take some essentials
+++ into account.</p>
+++ <h2>Design decisions</h2>
+++ <p>At first, the text is turned into webpages. The introduction text will be on
+++ the home page, the addres on the contact page. Some decisions have to be made:
+++ </p>
+++ <ul>
+++ <li>How to set up the pages</li>
+++ <li>How to prepare for future multiple languages</li>
+++ <li>How to set up the navigation</li>
+++ </ul>
+++ <h3>Page setup</h3>
+++ <p>If you are not bound to a strict format, you can basically define your own
+++ DTD or XML Schema that your pages have to validate against. You can make up your
+++ page with HTML tags from the start, follow a standard or define your own tag or
+++ any combination of all this. There are some arguments in favor of building your
+++ own tags. First of all, the separation of concerns. This is high on Cocoon's
+++ priority list and applies not only to the code but also to the content: i.e.
+++ separate content from display. This basically rules out using HTML tags for your
+++ content markup, as HTML is very limited in that regard. <br/>
+++ You can follow a standard markup like Docbook, but that might be overkill in
+++ this case. On the other hand, should a transformation to Docbook be required
+++ later on, you can probably transform you home-grown tags into Docbook with a
+++ clever XSLT stylesheet.</p>
+++ <p>So, let's define a set of tags for the current pages.</p>
+++ <p>Here is a definition of a typical page layout with an explanation between the
+++ tags.</p>
+++ <pre>&lt;page&gt; &lt;!-- this is the root element --&gt;
+++   &lt;header&gt; 
+++       &lt;!-- this contains the title of the page, as displayed in the browser title
bar, specific CSS, JS 
+++            and other files that are only used in this page 
+++        --&gt;
+++     &lt;title&gt;Title as it will show up in the title bar of the browser&lt;/title&gt;
+++   &lt;/header&gt;
+++   &lt;content&gt;
+++     &lt;banner&gt;This will be the "name" of the page, the equivalent of the title
of a book chapter&lt;/banner&gt;
+++     &lt;text&gt;This will contain the main content of the page.
+++        In this text regular HTML is used for basic layout such as paragraphs (&lt;p&gt;),

+++        lists (&lt;ul&gt;, &lt;ol&gt; and &lt;li&gt;) and emphasis
(&lt;strong&gt; and &lt;em&gt;). If this is not sufficient
+++        to properly mark the type of the information, more tags will be added.
+++     &lt;/text&gt;
+++   &lt;/content&gt;
+++ &lt;/page&gt;
+++ </pre>
+++ <h3>Multiple languages</h3>
+++ <p>Since we already know the site will be available in three different
+++ languages, we might as well make sure this can be added without much
+++ modification. Cocoon provides the Internationalisation functionality
+++ <strong>i18n</strong>. It comes down to writing different catalogue files,
+++ for each language, that contain key/value pairs of the information that should
+++ be translated. Although this is a great and flexible system, in my personal
+++ opinion there are a few drawbacks:</p>
+++ <ul>
+++ <li>The catalogue files are cumbersome to maintain, i.e. you have to update (in
+++ our case) three separate files when you want to add or modify a key.</li>
+++ <li>If you use this system for all multi-lingual information, you are tucking
+++ away content in files that are more system-related than content-related.</li>
+++ <li>Currently, Cocoon (2.1.7) has a minor bug which requires a restart of Cocoon
+++ to read the updated i18n catalogue files.</li>
+++ </ul>
+++ <p>That said, the i18n system is still useful for fixed concepts and short
+++ messages, like page titles, button names, names of weekdays and months etc. The
+++ "real" content will be entered in the pages as described above. This makes
+++ translation of the actual content easier and all translations will be together
+++ in one page, so there is less of a chance to forget to update a file.</p>
+++ <p>To separate the different language sections, a new set of tags is defined:
+++ </p>
+++ <pre>&lt;langselect&gt;
+++    &lt;select lang="en"&gt;English text here&lt;/select&gt;
+++    &lt;select lang="nl"&gt;Nederlandse tekst komt hier&lt;/select&gt;
+++    &lt;select lang="fr"&gt;Texte francaise est ici&lt;/select&gt;
+++ &lt;/langselect&gt;
+++ </pre>
+++ <p>Later we will devise an XSLT stylesheet that will extract the selected
+++ language and ignore the other. This way, it is possible to not only use these
+++ tags as "toplevel" tags in the &lt;text&gt; section, but also in any lower level
+++ tag. E.g. when a page mostly consists of standardized text, except for the last
+++ paragraph, then it is much more efficient to use i18n tags for the standardized
+++ text and only wrap the last paragraph in &lt;langselect&gt; tags.</p>
+++ <h3>Navigation</h3>
+++ <p>We want users to be able to switch to any language at any time, which means
+++ we need to provide a language switch mechanism at each page.<br/>
+++ We also want a simple lefthand side vertical menu. For now that would be
+++ sufficient, but once the site grows, it is good to add a sitemap, so we want one
+++ file that can be used as input to both the menu and the sitemap.<br/>
+++ Of course the menu and the sitemap should be in three languages as well.</p>
+++ <h3>Output</h3>
+++ <p>We want the final output to be valid XHTML 1.0 Transitional. All CSS used
+++ should be valid as well.</p>
+++ <h3>Directory structure vs URL structure</h3>
+++ <p>Cocoon allows a separation of the directory structure and the URL structure,
+++ i.e. the URL does not have to match the underlying directory structure. It is in
+++ fact even better to separate them, since it allows you to get the best of both
+++ worlds: good looking URLs and an easy to use directory structure.</p>
+++ <p>The website is currently very small and will probably not grow into an
+++ enormous amount of pages. It is therefore a good idea to just keep it into a
+++ flat structure with all pages at the same level. If we add the language to the
+++ URL, it is flexible enough to directly point to the appropriate page.</p>
+++ <h2>Let's get to work</h2>
+++ <p>Now that decisions are made,</p>

no changes

no changes

Custom Fields
no changes

no changes

View raw message