cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From d...@cocoon.apache.org
Subject [Cocoon Wiki] Updated: CocoonDocumentationSystem
Date Tue, 18 Jan 2005 09:42:22 GMT
   Date: 2005-01-18T01:42:22
   Editor: ReinhardPoetz
   Wiki: Cocoon Wiki
   Page: CocoonDocumentationSystem
   URL: http://wiki.apache.org/cocoon/CocoonDocumentationSystem

   no comment

Change Log:

------------------------------------------------------------------------------
@@ -41,6 +41,7 @@
                               \     /
                                `---'
 }}}
+
 The center of the new architecture is SVN. SVN contains all Forrest repositores. For the
first, these are[1]:
 
  * 2.1 docs
@@ -57,10 +58,13 @@
 http://cocoon.apache.org/2.2/............... contains the periodically (e.g. every 6 hours)
                                              published docs
 }}}
+
 ----
+
 ''Note that publishing multiple versions is good but can lead to confusion when people search
on the web and get a page from a different release than what they are using. I'd suggest a
note/link on each page, clearly stating to which version of Cocoon this page applies, and
giving access to the version navigation (ideally a link which searches for the same info in
other versions, but that's for a future release ;-)'' - [wiki:BertrandDelacretaz BD]
 
-''After the discussions on dev@cocoon I dropped the idea of publishing patch release docs''
ReinhardPoetz
+''After the discussions on dev@cocoon I dropped the idea of publishing patch release docs.
See the new drawing above that already reflects this. If you're interested in the original
version of it, look into one of the former versions of this wiki page.'' ReinhardPoetz
+
 ----
 
 The "living docs" docs that are periodically published out of the current repositories contain
an "edit" and a "comment" link. This link is redirected to a web application where authors
can write new docs or comments, e.g.
@@ -69,6 +73,7 @@
 
 http://cocoon.apache.org/comment/2.2/23.html --> http://someapacheserver.apache.org/webedit/comment/cocoon/2.2/23.html
 }}}
+
 The web application at http://someapacheserver.apache.org/webedit/ has following features:
 
  * edit a document e.g. document 2.2/23.html (everybody)
@@ -104,6 +109,7 @@
 [1] If 2.2 is coming soon we should concentrate on 2.2 docs 
 
 == Document format ==
+
 I propose the format that the default configuration of the HTMLCleaningConvertor generates.
What is good enough for Daisy should work as well for us ;-)
 Alternativly we can use plain HTML4. This would have the advantage that the document can
be edited using any HTML editor.
 
@@ -123,16 +129,18 @@
 }}}
 
 Splitting up the docs into three parts has the advantage that the structure of each document
is simpler, editors can be used to edit the content only. Also Openoffice goes this way.
+
 ----
+
 ''The SimpleContentModel idea might also be good, it uses a slightly different but interesting
model, where a documents is either a single xml file or a directory containing the main document
and additional files'' - [wiki:BertrandDelacretaz BD]
-----
+
 ''This is what I propose, that does not contain a metadata file. The author and dates infos
are in the source file, while the history is in SVN... no need to replicate stuff. The comments
stuff can be added as a Forrest plugin. Maybe putting the comments in a doc.comments directory,
with each a separate html file would be nice.'' - [wiki:NicolaKenBarozzi NKB]
 
 {{{
  17.html ........................ contains the content
  17.comments.xml ...............  contains user comments
 }}}
-----
+
 ''For the comments stuff, see my proposal in the Cocoon whiteboard. I simply  added it in
a custom pipeline - see http://svn.apache.org/repos/asf/cocoon/whiteboard/doc-repos/2.2/src/documentation/sitemap.xmap.
About skipping the meta infos, I'm not sure. I also want to provide info about status, target
audience, keywords and this for all languages. Putting this information into plain text makes
it hard/inpossible to explicitly use it in the publishing process query it in the future.
Here the structure of a document on the filesystem:'' 
 
 In the repository, each document consists of a directory, which can contain following files:
@@ -149,7 +157,10 @@
 
 ''The changes include the ideas from Bertrand and Nicola. Additionaly I added a location
for mimes (images, attachments like ZIPs) and the option for having the content in multiple
languages available.'' ReinhardPoetz
 
+----
+
 == Document identifiers ==
+
 I think we should move away from speaking names like "custom_components" and use plain numbers
and put all documents into a flat directory. Speaking identifiers are nearly always a problem
in data modelling.
 
 Advantages:
@@ -159,20 +170,27 @@
 
 Note to auto-generated docs: Every process that generates docs automatically, has to use
a unique numbering scheme (namespace) so that IDs can't conflict with existing docs.
 
+----
+
 ''Apart from the very controversial idea of having numbers as IDs, the most important part
is the flat structure (WIKI style) of all documents. (see http://marc.theaimsgroup.com/?l=xml-cocoon-dev&m=110593998230556&w=2
by Stefano). Structuring of content is IMO not a concern of the repository but of the publishing
process. Forrest offers everything we need.'' ReinhardPoetz
 
 ''After reading other's opinions I withdraw my proposal, and will use flat URLs with speaking
identifiers.'' ReinhardPoetz
 
+----
+
 == Forrest repositories ==
+
 See http://svn.apache.org/repos/asf/cocoon/whiteboard/doc-repos/ for two examples that work
with the latest SVN version of Forrest 0.6.
 
 == Published docs ==
+
 The proposal for new global docs and user docs are available at http://apache.org/~reinhard/cocoon/1.html.
Note that the page is generated out of two forrest repositories.
 
 The global repository is responsible for the tabs "Projekt" and "Community". The tabs "Getting
started" and "Documentation" link to the most recent, editable userdocs. Older (frozen) docs
get their links in the second-level pelt in the "Documentation" tab.
 
 = What do we have to do? =
 == Step by Step ==
+
 The good news is that we don't need all the features at once. We can go the path to better
docs and a better documentation system step by step:
 
  * Step1: Setup Forrest Repositories
@@ -200,6 +218,7 @@
  * Upayavira will invest a large amount of his time into writing and updating docs.
 
 = Readers comments =
+
 Please use ''italics'' to add comments above this line, or write more extensive comments
and ideas below.
 
  * Tagging documents with simple free-form keywords, as done for links on [http://del.icio.us/]
or pictures on [http://www.flickr.com/] is a very powerful yet simple way of providing many
useful navigation paths in the documentation. Even if tag-based navigation is not implemented
right away, it would be good to add tags (like "sitemap config FileGenerator Generator 2.1.1"
for example) when revising existing documents, as opposed to having to revisit all documents
later on to tag them. - [wiki:BertrandDelacretaz BD]

Mime
View raw message