cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ross Gardler <rgard...@apache.org>
Subject Re: [daisy] Re: Forrest & Daisy integration scenarios
Date Sun, 15 May 2005 10:21:05 GMT
[Originally sent pnly to Daisy list in error, did,'t realise the 
original mail had been cross posted]

Stefano Mazzocchi wrote:
> Steven Noels wrote:
> 

...

> 
> In perfect do-ocracy, who makes it work first, gets my vote. :-)

I'm not sure it's enough to get your vote as there is still more to do,
but I promised something tonight so here it is.

I just created a simple site demo of Daisy + Forrest. It only works in
dynamic mode at present so no published version. There are a few other
limitations (see end of this mail for known problems).

"All" it does is so how an XDoc and a document from a daisy repo can be
seemlessly integrated into a single site. More discussion below for
those of you who don't want to start up the site:

To see the site:

be sure you are running the latest SVN head of Forrest

cd FORREST_HOME/whiteboard/plugins/org.apache.forrest.plugin.input.Daisy

ant local-deploy

(this deploys the experimental daisy plugin to your local version of
Forrest, this step is needed as the plugin has not been released yet so
there is no download site for it)

cd tmp

(or wherever)

unzip the zip at
http://people.apache.org/~rgardler/testingGround/cocoonDocsDemo/daisyForrestDemo.zip

forrest run

http://localhost:8888

----

For those who don't want to start the site up I've copied the discussion
on the indes page below.page (incidentally this nicely formatted version
is generated by the Forrest Text output plugin).

                        Quick demo of Daisy + Forrest

Table Of Contents
=================
Daisy + Forrest = Workflow Controlled Publication of "Free For All"
Documentation
Why does this "site" exist?
Some Further Advantages of this Approach
   Multiple Sites
   Order From Chaos
   Sorting the Wheat from the Chaff
   Existing Content Integration
   Third Party Content Integration
Problems

Daisy + Forrest = Workflow Controlled Publication of "Free For All"
Documentation
=================================================================================

   For some background on why this was created see this mail[Link to:
   http://marc.theaimsgroup.com/?l=xml-cocoon-dev&m=111591833106339&w=2]in
   the Cocoon Dev Mail Archives.

   This simple little site is a Forrest site built with content from two
   different sources:

   1. Local files that could be under SVN control (this one)
   2. A remote file from the CocoonHandbook
      * The original file can be found on Daisy at cocoondev


   Since we are usng Forrest as the publication engine there is a very
   wide range of input formts supported by this solution. See the Forrest
   project[Link to: http://forrest.apache.org/]for more information.

Why does this "site" exist?
===========================

   This site is a simple demonstration of the second part of the solution
   described in the mail above.

   The first part of that mail refers to Daisy being used to lower the
   barrier to entry for Cocoon document authors. Daisy provides the first
   part of the workflow system controlling the publication of edits.

   The second part of that mail refers to Forrest being used to collate
   the materials found in (inevitably) chaotic documentation found in the
   Wiki. This site only presents a portion of the content in the wiki,
   that is it presents the portion that is considered to be of suitable
   quality for the released documents.

   The second part talks about a staging server. This site is the staging
   server. That is, install Forrest and run forrest run inside the docs
   directory of the cocoon distribution and you see this site.

   This means that all committers have access at all times to the current
   "offical" documentation. Editing of the structure of that content is
   done through tools familar to Cocoon developers, i.e. SVN and their
   preferred editors. Editing of the actual content is done via the Daisy
   Wiki installation. Although it is not included in this demo it would be
   trivial to provide a link from the staging server back to the page to
   edit the content.

   The third phase is already in place. It is is the hosting of this
   documentation on a web server. However, unlike the current system the
   snapshots taken at release time will contain all the documentation
   current for that release. No longer will the hapless user be expected
   to search the multiple documention sets to try and find their answer,
   nor will they have to traul through lots of false hits from incomplete
   or innacurate documents.

Some Further Advantages of this Approach
========================================

   Multiple Sites
   --------------

     The structure of the site generated using Forrest need bear no
     relation to the structure of the documents in the source
     repositories. This means that the final documentation can be
     designed with a navigation structure that suits the reader. In fact
     we can have the same content appearing in different places in
     different sites, for example, we can have sites for newbies, for
     technical folk, for marketing purposes, for press folk etc.

   Order From Chaos
   ----------------

     In addition to being able to have multiple site structures, this
     also enables us to bring order to the chaos of "free for all"
     Content Management Systems. That is, even in a CMS with a tightly
     controlled publishing workflow things become chatic quite quickly.
     This approach of having separate "views" on the materials enables
     the CMS to be freed up to serve the content creators, rather than
     the content consumers. That is the CMS can structured in a way that
     is convenient to editors, for example presenting menus of items
     requiring review rather than logical groupings of documents into
     topic areas.

     Of course, if the CMS has an adequate navigation editor, this can
     be used for creating both the reader and editor views of the
     repository. Forrest can be made to use those documents as either
     complete site structure documents, or sub-sites to be imported into
     other sites.

   Sorting the Wheat from the Chaff
   --------------------------------

     In a "free for all" content management system it is important to
     balance quality control measures against a low barrier to entry for
     potential contributors. This two phased approach allows a two
     points of quality control. The first is when a contribution is
     accepted for publication into the "in development" documentation.
     The second is when a contribution is accepted into the published
     doucmentation.

     The goals of this system are to make it very easy for people to
     contribute to the "in development" content. Self registration is
     allowed, thus anyone can edit, whilst a select number of trusted
     editors are given the task of publishing edits into the CMS. These
     "free" editing will result in a number of incomplete or possibly
     innacurate documentation. Thus we have the second phase, which is
     the Forrest site publication. This is managed by key members of the
     community who decide what content will be used in the next
     published set of documentation.

     This allows a wide range of documents to be accepted into the CMS
     whilst minimising the work involved with moving those documents
     into the final documentation collection.

   Existing Content Integration
   ----------------------------

     It is recognised that there is considerable amount of documentation
     in other forms, for example there are a large number of XDoc files
     in Cocoons SVN, java code is annotated with tagged comments, and
     the Wiki has lots of valuable content too. Since Forrest can work
     with a large number of input formats it can seemlessly integrate
     this content into the Cocoon documentation site.

     The new plugin system in the 0.7 version of Forrest allows extra
     input formats to be easily supporte. When the prposed edit link on
     a page is clicked it will take the user to the relevant edit
     interface for that document. Clearly it would be in the best
     interests of Cocoon to bring all documentation together "under the
     on roof". However this is a very big job and this mechanism can be
     used to quickly integrate the existing documetnation systems whilst
     gradually migrating documents to the chosen editing platform.

   Third Party Content Integration
   -------------------------------

     Where a third party develops content that is appropriate to the
     Cocoon docs it is possible to include such content (when suitably
     licensed) directly within the published docs.

Problems
========

   If the staging server discussed in the mail above is the local users
   machine as described in this document then the user must be online to
   see the complete set of documentation since the system will download
   the latest version of the data when a page is requested.

   This demo is based on a whiteboard plugin for Forrest to import
   documents from a Daisy repository. This plugin is experimental,
   discussions are ongoing with the Daisy and Forrest communities about
   how best to implement it. It is pre-alpha at this stage and may not
   work as expected. Known issues are:

   * pdf and text generation does not work yet (simple URL rewrite
required in
     Forrest skins)
   * binary data does not work yet (need to add readers to Daisy plugin)
   * no form of caching is implemented (make quick requesst to Daisy
Repo. to
     get last update timestamp)
   * menu selection does not work corectly (tweak to Forrest XSL needed)
   * static publishing from Forrest does not currently work (need
     locationmap in Forrest to work to enable this)

   The construction of URLs for retrieving data from remote repositories
   is quite cumbersome. There is a future enhancement to Forrest that will
   greatly simplify this, there is also a GUI editor for content objects
   under development.
_______________________________________________
daisy mailing list
daisy@lists.cocoondev.org
http://lists.cocoondev.org/mailman/listinfo/daisy




Mime
View raw message