Date: 2005-01-18T01:33:56
Editor: ReinhardPoetz
Wiki: Cocoon Wiki
Page: CocoonDocumentationSystem
URL: http://wiki.apache.org/cocoon/CocoonDocumentationSystem
update
Change Log:
------------------------------------------------------------------------------
@@ -19,12 +19,12 @@
| +--------------+ |period. update| +--------------+ | |
| |2.3 docs |-+--------------+>|/2.3 |-|----+
| +--------------+ | | +--------------+ | |
- | +--------------+ | (frozen) | +--------------+ | |
- | |2.2 docs |++--------------+>|/2.2.2 | | |
- | +--------------+ |'-._ | +--------------+ | |
- +->| +--------------+ | `-.. | +--------------+ | |
- | | |... | | (per. `-----+>|/2.2 |-|----+
- | | +--------------+ | update) | +--------------+ | |
+ | +--------------+ | | +--------------+ | |
+ | |2.2 docs |-+--------------+>|/2.3 |-|----+
+ | +--------------+ | | +--------------+ | |
+ +->| +--------------+ | | | |
+ | | |... | | | |----+
+ | | +--------------+ | | | |
| +------------------+ +------------------+ |
| |
| |
@@ -50,21 +50,19 @@
There are two ways how the docs of these repositores are published:
* periodicially using some kind of automatism (cron, forrestbot)
- * when a new Cocoon version is released, the docs are released too
Let's look at the structure of the website:
{{{
http://cocoon.apache.org ................... contains the global docs
-http://cocoon.apache.org/2.2.0/............. contains the docs that were (will
be) published
- when Cocoon 2.2.0 was released
- *** These docs will ever never
change! ***
-http://cocoon.apache.org/2.3.4/............. same as above but for the 2.3.4
release
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 [EMAIL PROTECTED] I dropped the idea of publishing
patch release docs'' 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.
{{{
http://cocoon.apache.org/edit/2.2/23.html -->
http://someapacheserver.apache.org/webedit/edit/cocoon/2.2/23.html
@@ -85,17 +83,38 @@
* make site.xml editable using a nested list of <ul> (committers only)
* user management (committers only)
* report: list of all modified/new docs and comments available
-
+
+The implementation of this mini CMS could be done based on
+
+ * Daisy
+ * Hippo CMS (if it is OS licensed in the meantime)
+ * Apache Lenya
+ * Forrest
+ * Gianugo's little
[http://www.rabellino.it/blog/index.php?title=writing_stuff_for_with_cocoon&more=1&c=1&tb=1&pb=1
CMS]
+ * write my own
+
+----
+
+''Look at http://wiki.apache.org/cocoon/CocoonDocumentationSystem and find all
my requirements. I'm sure that all six options are good enough but as *I* have
to do it, I'll take the road that's the fastest for *me*. Don't forget that
learning where I have to add extensions to an enterprise level CMS like Daisy,
Hippo or Lenya would take *a lot* of time. And as I have the (maybe
illusionary) view, that I would be rather fast in implementing it on my own,
I'll probably go the Forrest, Gianugo or "write my own" way. That's it.
+
+Once again, nothing speaks against taking one of the enterprise level CMS and
if one of the communities around them does the implementation and takes all
requirements listed at http://wiki.apache.org/cocoon/CocoonDocumentationSystem
into consideration, I'm the last one who stops them. One thing to add: I want
to see a prototyp of the webapp running in 6-8 weeks from now; whoever writes
it.'' ReinhardPoetz (a
[http://marc.theaimsgroup.com/?l=xml-cocoon-dev&m=110603879312083&w=2 reply] to
a [http://marc.theaimsgroup.com/?l=xml-cocoon-dev&m=110603716728538&w=2 mail]
of Andreas Kuckartz who asked what would speak against Apache Lenya)
+
+----
+
[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.
+----
+
''I propose HTML as a base format. Forrest is able to render it without
problems, and the Incubator website uses it as a source format.'' -
[wiki:NicolaKenBarozzi NKB]
''Currently I think of supporting both, HTML (17.html) and "default
HTMLCleaningConvertor XML" (17.html). Only one can be available, which is
checked by Forrest. I think that after the online scenario is running,
everybody will use it. Also if you like to write a first version with Mozilla
Compose because you can copy the text into the HTMLArea form field afterwards.
But for the time until the online sceanrio is running, we need an alternative,
and here HTML comes in.'' ReinhardPoetz
+----
+
In the repository, each document contains of 3 files:
{{{
17.xml ........................ contains the content
@@ -141,6 +160,8 @@
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.
