adding new developers guide

diff --git a/ChangeLog b/ChangeLog
index 8ace0aa..96b44c5 100755 (executable)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,6 +1,7 @@
-2005-08-10  Grok  <grok@no-log.org>
-       * doc/diagrams:
-       adding a few diagrams to help document mir
+2005-09-10  Grok  <grok@no-log.org>
+       * doc/diagrams, doc/developpers-guide:
+       writing a developpers guide with  diagrams to help 
+       document mir
        
 2005-08-07  Grok  <grok@no-log.org>
        * templates/admin/FUNCTIONS.template:

diff --git a/doc/developers-guide/developers-guide.xml b/doc/developers-guide/developers-guide.xml
new file mode 100755 (executable)
index 0000000..cabc2c7
--- /dev/null
+++ b/doc/developers-guide/developers-guide.xml
@@ -0,0 +1,51 @@
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+         "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+  [
+    <!ENTITY MIR_VERSION   "1.1">
+    <!ENTITY introduction SYSTEM "introduction.xml">
+    <!ENTITY producers    SYSTEM "producers.xml">
+  ]
+>
+<book>
+  <title>Mir CMS 1.1, developpers guide</title>
+  <bookinfo>
+    <revhistory>
+      <revision>
+        <revnumber>0.0.0</revnumber>
+
+        <date>August 2005</date>
+
+        <revremark>First steps</revremark>
+      </revision>
+    </revhistory>
+
+    <authorgroup>
+      <author>
+        <firstname>Grok</firstname>
+        <affiliation>Mir coders
+                 <email>grok wants no spam _at_ no-log.org</email>
+               </affiliation>
+      </author>
+    </authorgroup>
+       <keywordset>
+       <keyword>Mir</keyword>
+       <keyword>indymedia</keyword>
+       </keywordset>
+
+  </bookinfo>
+
+  <preface> 
+      <abstract>
+          This document is meant for helping mir developpers. It is assumed that
+          you have allready installed mir and have some basic knowledge
+          on how to use it. However, reading the introduction chapter might
+          also be worthwhile for sysadmins and template designers.
+      </abstract>
+  </preface>
+
+<!-- Chapters -->
+&introduction;
+&producers;
+
+</book>
\ No newline at end of file

diff --git a/doc/developers-guide/introduction.xml b/doc/developers-guide/introduction.xml
new file mode 100755 (executable)
index 0000000..142b564
--- /dev/null
+++ b/doc/developers-guide/introduction.xml
@@ -0,0 +1,176 @@
+<chapter id="introduction">
+<title>Introduction</title>
+
+<section><title>Architecture overview</title>
+<para>
+       Mir is a fairly large piece of software (over 50.000 lines) written in java.
+It relies on the tomcat servlet framework for administration and open publishing
+tasks. However, unlike many other CMS's that generate html on the fly 
+(usually using a cache), Mir writes html pages into a static site. 
+Normally, users that visit the mir site, will only see the static site.
+Users that want to publish content (open publishing) will contact
+the dynamic site. Administrators will also contact 
+the dynamic site  (see figure).
+</para>
+
+<figure><title>mir architecture (single host)</title>
+<mediaobject>
+<imageobject>
+<imagedata fileref="../diagrams/mir-architecture-singlehost.eps" format="EPS"></imagedata></imageobject>
+<imageobject>
+<imagedata fileref="../diagrams/mir-architecture-singlehost.png" format="PNG"></imagedata></imageobject>
+<textobject>
+</textobject>
+</mediaobject>
+</figure>
+
+<para>
+This architecture is interesting because most page requests will be done
+on the static site. Static pages are efficiently handled by the web server.
+It is also interesting because it permits easy mirroring of the static
+site. Mirrors are simple to set up, since only static pages are involved
+(see figure).
+</para>
+
+<figure><title>mir architecture (mirrored)</title>
+<mediaobject>
+<imageobject>
+<imagedata fileref="../diagrams/mir-architecture-mirrored.eps" format="EPS"></imagedata></imageobject>
+<imageobject>
+<imagedata fileref="../diagrams/mir-architecture-mirrored.png" format="PNG"></imagedata></imageobject>
+<textobject>
+</textobject>
+</mediaobject>
+</figure>
+
+</section>
+
+<section><title>Concepts used by Mir</title>
+<para>Here's a list of important terms and concepts used by Mir. 
+Many of these concepts will be further detailed latter on in this guide.
+</para>
+<glossentry id="producers">
+  <glossterm>producer</glossterm>
+    <glossdef>
+         <para>As mentioned in the architecture overview, mir
+generates a set of static html pages called the static site.
+Generating these pages involves using a template engine to
+replace variables (representing data) in template files. Template files 
+are written by web designers. 
+In many CMS systems, the available variables (data) are hard-coded into the 
+software. In practice, this is often not flexible enough
+for web designers.
+Mir allows designers to request the data they need by using
+the producer framework, configured in the "producers.xml" file.
+</para>
+<para>Originally producers were
+mostly used  to generate  pages, but  they are now used  for a  lot of
+other  tasks. In fact, the producers.xml file provides a 
+simple, xml-based, programing (scripting) language, so that  
+site administrators can script their own custom tasks without
+changing the java code.
+For example, on indymedia.org, producers are used to pull rss  
+feeds  for the  global wire. 
+</para>
+<figure><title>An example of article generation with the producers framework</title>
+<mediaobject>
+<imageobject>
+<imagedata fileref="../diagrams/article-generation-example.eps" format="EPS"></imagedata></imageobject>
+<imageobject>
+<imagedata fileref="../diagrams/article-generation-example.png" format="PNG"></imagedata></imageobject>
+<textobject>
+</textobject>
+</mediaobject>
+</figure>
+<para>
+Further information on producers may be found at XXX and in the javadoc 
+(classes Producer, NodedProducer, roducerNode...).
+</para>
+       </glossdef>
+</glossentry>
+
+<glossentry id="database">
+  <glossterm>database</glossterm>
+    <glossdef>
+         <para>
+Mir uses a postgres database to store it's data. 
+Currently, the mir.storage, mircoders.storage, mir.entity, and 
+mir.entity.adapter 
+packages
+are used to acces  the database in Mir. However, these packages 
+are obsolete and will be replaced by the 
+<ulink url="http://www.hibernate.org">hibernate</ulink>
+object/relational persistence system. 
+</para>
+       </glossdef>
+</glossentry>
+
+
+<glossentry id="localizer">
+  <glossterm>localizer</glossterm>
+    <glossdef>
+         <para>
+FIXME localizers are to allow mir installations to add code seperate from the
+main code. A lot of things can be changed in an installation (and are
+by various mir sites). Think of custom open posting mechanism, open
+posting validation, data model enhancements. 
+</para>
+       </glossdef>
+</glossentry>
+
+<glossentry id="generator">
+  <glossterm>generator</glossterm>
+    <glossdef>
+         <para>
+A generator is an abstraction for a template engine. 
+Different template engines are
+supported right now: 
+<ulink href="http://freemarker.sourceforge.net">freemarker</ulink> 
+(used most often), tal (used by some
+sites) and velocity (not used at all but supported anyway).
+</para>
+       </glossdef>
+</glossentry>
+
+
+<glossentry id="logger">
+  <glossterm>logger</glossterm>
+    <glossdef>
+         <para>
+Logging is understood here as "sytem logs" : information written
+out to files that may be used to track what is going on in Mir,
+especially errors and warnings. Mir uses the <ulink href="http://logging.apache.org/log4j/docs">log4j</ulink> logging system.
+This alows us to split logs into different files, making them
+easier to understand.
+</para>
+       </glossdef>
+</glossentry>
+
+<glossentry id="mircoders">
+  <glossterm>mircoders packages</glossterm>
+    <glossdef>
+         <para>
+Originally, the mircoders packages were meant for local developpements,
+as opposed to the core Mir code. This distinction is now obsolete
+and these packages will probably be reorganized in future releases.
+</para>
+       </glossdef>
+</glossentry>
+
+<glossentry id="bundle">
+  <glossterm>bundles</glossterm>
+    <glossdef>
+         <para>
+bundles are key/value pairs in a text file, used for configuration
+and internationalization
+</para>
+       </glossdef>
+</glossentry>
+
+
+
+</section>
+
+
+
+</chapter>

diff --git a/doc/developers-guide/producers.xml b/doc/developers-guide/producers.xml
new file mode 100755 (executable)
index 0000000..3a49c86
--- /dev/null
+++ b/doc/developers-guide/producers.xml
@@ -0,0 +1,9 @@
+<chapter id="introduction">
+<title>Producers framework</title>
+
+<section><title>qsdqs</title>
+<para>
+sdfqsdf
+</para>
+</section>
+</chapter>

diff --git a/doc/diagrams/article-generation-example.sxd b/doc/diagrams/article-generation-example.sxd
index 8a1bc6f..983926d 100755 (executable)
Binary files a/doc/diagrams/article-generation-example.sxd and b/doc/diagrams/article-generation-example.sxd differ

diff --git a/doc/diagrams/mir-architecture-mirrored.sxd b/doc/diagrams/mir-architecture-mirrored.sxd
index 2f8d20a..ba9a170 100755 (executable)
Binary files a/doc/diagrams/mir-architecture-mirrored.sxd and b/doc/diagrams/mir-architecture-mirrored.sxd differ

diff --git a/doc/diagrams/mir-architecture-singlehost.sxd b/doc/diagrams/mir-architecture-singlehost.sxd
index 5bf0d72..a0e01ad 100755 (executable)
Binary files a/doc/diagrams/mir-architecture-singlehost.sxd and b/doc/diagrams/mir-architecture-singlehost.sxd differ