A document has been updated:
http://cocoon.zones.apache.org/daisy/cocooninaction/677.html
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
Parts
=====
Content
-------
This part has been updated.
Mime type: text/xml (unchanged)
File name: (unchanged)
Size: 6935 bytes (previous version: 935 bytes)
Content diff:
<html>
<body>
--- <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 you
+++ agreed the contents for the first pages:</p>
<h3>About HealthyCocoon</h3>
(16 equal lines skipped)
fax: +31 43 1234568<br/>
email: [EMAIL PROTECTED]</p>
+++ <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><page> <!-- this is the root element -->
+++ <header>
+++ <!-- 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
+++ -->
+++ <title>Title as it will show up in the title bar of the
browser</title>
+++ </header>
+++ <content>
+++ <banner>This will be the "name" of the page, the equivalent of
the title of a book chapter</banner>
+++ <text>This will contain the main content of the page.
+++ In this text regular HTML is used for basic layout such as
paragraphs (<p>),
+++ lists (<ul>, <ol> and <li>) and emphasis
(<strong> and <em>). If this is not sufficient
+++ to properly mark the type of the information, more tags will be
added.
+++ </text>
+++ </content>
+++ </page>
+++ </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,
one
+++ 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><langselect>
+++ <select lang="en">English text here</select>
+++ <select lang="nl">Nederlandse tekst komt hier</select>
+++ <select lang="fr">Texte francaise est ici</select>
+++ </langselect>
+++ </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 <text> 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 <langselect> 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>
+++
</body>
</html>
Fields
======
no changes
Links
=====
no changes
Custom Fields
=============
no changes
Collections
===========
no changes
