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 [EMAIL PROTECTED] http://lists.cocoondev.org/mailman/listinfo/daisy
