crossley 2004/09/10 23:19:02
Modified: . README.txt
site site.xml howtoparticipate.xml
site/incubation Incubation_Policy.cwiki
Log:
Enhance the website production instructions.
Revision Changes Path
1.6 +9 -16 incubator/README.txt
Index: README.txt
===================================================================
RCS file: /home/cvs/incubator/README.txt,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- README.txt 10 Sep 2004 08:16:28 -0000 1.5
+++ README.txt 11 Sep 2004 06:19:02 -0000 1.6
@@ -21,25 +21,18 @@
Website Howto
=============
-To generate the website one needs to install Apache Forrest
-http://forrest.apache.org/ (use the current development version from SVN).
+The top-level Incubator website is currently generated by Apache Forrest
+http://forrest.apache.org/ (using the current development version from SVN).
-Editors can edit the pages without generating the site, and just validate the
-xml with a validating editor before committing. For the wiki pages it's plain
-text, so it's easier. People with Forrest installed can build and update
-the website. (Later the Forrestbot will take care of doing builds.)
-
-Anyway, do this ...
+The source documents are in the "incubator" CVS module. Most documents are
+in site/*.xml format. The status reports for each project are in
+site/project/*.cwiki (this is the simple JSPWiki format).
- Follow the Forrest instructions to build it
- and set the environment variables FORREST_HOME and PATH
+Editors can edit the pages without generating the site, and just validate the
+xml with a validating editor before committing. For the wiki pages it is
plain
+text (therefore no validation, so be careful).
- Get or update "incubator" from CVS
- cd into the local "incubator" top-level CVS dir
- Do 'forrest run'
- Point the browser to http://localhost:8888/ to see the site
- Edit the docs *in place* and see changes in the browser by reloading.
- To generate the full website use the command-line mode 'forrest'.
+See the document http://incubator.apache.org/howtoparticipate.html#website
Subproject Website Howto
========================
1.43 +3 -3 incubator/site/site.xml
Index: site.xml
===================================================================
RCS file: /home/cvs/incubator/site/site.xml,v
retrieving revision 1.42
retrieving revision 1.43
diff -u -r1.42 -r1.43
--- site.xml 11 Sep 2004 01:30:15 -0000 1.42
+++ site.xml 11 Sep 2004 06:19:02 -0000 1.43
@@ -94,9 +94,9 @@
<grants href="#grants"/>
</licenses>
<projects>
- <xml>
- <forrest href="http://xml.apache.org/forrest/"/>
- </xml>
+ <forrest href="http://forrest.apache.org/";>
+ <build href="build.html"/>
+ </forrest>
</projects>
<cvs>
<incubator>
1.4 +150 -108 incubator/site/howtoparticipate.xml
Index: howtoparticipate.xml
===================================================================
RCS file: /home/cvs/incubator/site/howtoparticipate.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- howtoparticipate.xml 10 Sep 2004 11:08:12 -0000 1.3
+++ howtoparticipate.xml 11 Sep 2004 06:19:02 -0000 1.4
@@ -79,123 +79,165 @@
</ul>
</section>
</section>
- <section>
- <title>Updating the site</title>
-
- <p>To generate the website one needs to get
- <link href="ext:apache/projects/xml/forrest">Apache
Forrest</link> and install it.</p>
-
- <p>Editors can edit the pages without generating the site, and
just validate the
- xml with a validating editor before committing. For the wiki
pages it's plain
- text, so it's easier. Ones with Forrest installed (currently
nicolaken) and
- after the Forrestbot will take care of doing builds, fixing
eventual errors
- and updating the site.
- </p>
-
- <p>In any case, if someone wants to check the look of the pages, do
this:</p>
-
- <section>
- <title>Download Forrest</title>
- <!-- nicolaken: currently (20031112) CVS version os needed -->
- <!--<p>Download
- <link href="Apache
Forrest!http://xml.apache.org/forrest/.html";>Apache
Forrest!http://xml.apache.org/forrest/</link>-->
- <p>Download and install CVS <link
href="ext:apache/projects/xml/forrest">Apache Forrest</link>.</p>
- <ul>
- <li>get or update xml-forrest from CVS</li>
- <li>run the build script</li>
- <li>set FORREST_HOME to point to the build/dist/shbat</li>
- <li>add build/dist/shbat/bin to the PATH</li>
- </ul>
- <p>Example:</p>
-<source><![CDATA[
- export CVSROOT=:pserver:[EMAIL PROTECTED]:/home/cvspublic
-
- cvs login
- (press enter)
- cvs checkout xml-forrest
-
- cd xml-forrest
- ./build.sh
-
- export FORREST_HOME=`pwd`/build/dist/shbat:$PATH
- export PATH=`pwd`/build/dist/shbat/bin:$PATH]]>
- </source>
- </section>
- <section>
- <title>Download incubator</title>
-
- <p>Download the
- <code>incubator</code> CVS module. <code>incubator</code>
contains the main Incubator site sources,
- the incubator-site the final site contents.</p>
-
- <ul>
- <li>get or update "incubator" from CVS</li>
- </ul>
-
- <p>Continuing from the previous example:</p>
-
-<source><![CDATA[
- cd ..
- cvs checkout incubator
- cvs checkout incubator-site
-]]>
-</source>
- </section>
-
- <section>
- <title>Make your changes</title>
-
- <p>Edit the XML docs in <code>incubator/site/</code>. If you
are not familiar with DTDs,
- the syntax is best learned
- <link
href="http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/documentation/content/xdocs/document-v11.xml?rev=HEAD&amp;content-type=text/xml.html";>
- by example</link>.</p>
-
- <p>From the Forrest site,
- <link
href="http://xml.apache.org/forrest/document-v12.html";>here is quite a complete
example of the xml format</link>
- , and
- <link
href="http://xml.apache.org/forrest/wiki-sample.html";>here of the wiki
format</link>.</p>
+ <section id="website">
+ <title>Updating the site</title>
+ <p>This section describes how to maintain the top-level Incubator
+ website (including the project status reports).
+ For actual project websites see the
+ <link href="#project-website">Project Website Howto</link> below.
+ However, this section is still relevant for projects.
+ </p>
+
+ <section id="website-overview">
+ <title>Overview</title>
+ <p>The top-level Incubator website is currently generated by
+ <link href="ext:apache/projects/forrest">Apache Forrest</link>.
+ </p>
+ <p>The source documents are kept in the "incubator" CVS module.
+ Most documents are in site/*.xml format. The status reports for
+ each project are in site/project/*.cwiki (this is the simple
JSPWiki
+ format).
+ </p>
+ <p>
+ The production documents are kept in the "incubator-site" CVS
module.
+ That module is then checked-out on the server to re-create the
website.
+ </p>
+ </section>
+
+ <section id="website-edit">
+ <title>Edit the content</title>
+ <p>People with commit access to the "incubator" CVS can edit the
+ source documents in the "site/" directory. Anyone else can send
+ patches to those documents.</p>
+ <p>When editing the xml source, please ensure xml validation.
+ When editing the simple JSPWiki source, please take care to use
+ the correct syntax.
+ Here are examples of the document structures:
+ <link
href="http://forrest.apache.org/docs/document-v12.html";>xml format</link>
+ and
+ <link
href="http://forrest.apache.org/docs/wiki-sample.html";>JSPWiki
format</link>.</p>
+ <p>You can just commit the source changes and leave it to someone
+ else to generate the website.
+ </p>
+ </section>
+
+ <section id="website-generate">
+ <title>Generate the production documents</title>
+ <p>Either install Apache Forrest locally so that you can edit and
+ review documents immediately, or use the production system on
+ the server to generate and copy to a staging site to view them.
+ In the future there will be automated generation and staging
systems.
+ </p>
+ <p>Lets explain the server-side method first, then go on to
explain
+ how to set up a local Forrest system.
+ </p>
+ <p>People with access to the server can use an installation of
+ Forrest on minotaur ...
+ </p>
+<source><![CDATA[ssh www.apache.org
+cd ~crossley/incubator-site
+bash
+bin/stage incubator
+... This will do 'cvs checkout' of "incubator" CVS and build docs with
Forrest.
+
+cp -R staging/incubator.apache.org ~/public_html
+... This will copy the production to your committer webspace for viewing.
+
+diff -rq staging/incubator.apache.org modules/incubator-site/build/site \
+ | grep -v CVS > diff
+vi diff
+... Ensure that the differences are what you expect.
+
+cvs -q update -Pd modules/incubator-site
+cp -Rf staging/incubator.apache.org/* modules/incubator-site/build/site
+... Now do the usual CVS stuff: 'cvs update' 'cvs add' 'cvs diff' cvs commit'
+
+cd /www/incubator.apache.org
+cvs update -Pd
+]]></source>
+ </section>
+
+ <section id="forrest">
+ <title>Using a local Forrest installation</title>
+ <p>
+ Install the current development version of Forrest from SVN.
+ Follow the
+ <link
href="ext:apache/projects/forrest/build">installation</link>
+ instructions to build it and set the environment variables
+ $FORREST_HOME and $PATH.
+ </p>
+ <p>
+ Checkout the incubator CVS modules. The site source files are
kept
+ in the "incubator" CVS at "site/". The final website contents
are
+ kept in the "incubator-site" CVS at "build/site/".
+ </p>
+
+ <p>Edit the docs in the <code>incubator/site/</code>
directory.</p>
+
+ <p>Here are examples of the document structures:
+ <link
href="http://forrest.apache.org/docs/document-v12.html";>xml format</link>
+ and
+ <link
href="http://forrest.apache.org/docs/wiki-sample.html";>JSPWiki
format</link>.</p>
<p>If you add a new page or change a page's name, update
- <code>site.xml</code>, from which the menu is generated. More
details can be found
- <link
href="http://xml.apache.org/forrest/your-project.html";>in Forrest's
documentation</link>.</p>
+ <code>site/site.xml</code> from which the menu is generated.
+ More details can be found in the
+ <link href="http://forrest.apache.org/docs/";>Forrest
documentation</link>.</p>
- <p>In essence:</p>
+ <p>Here is a quick tour:</p>
<ul>
- <li>cd into the local "incubator" CVS dir</li>
- <li>execute "forrest run"</li>
- <li>point the browser to http://localhost:8888/ to see the
site</li>
- <li>edit the docs <strong>in place</strong> and see changes
in the browser by reloading the page</li>
- </ul>
- </section>
-
- <section>
- <title>Render the site</title>
- <p>In the <code>incubator</code>; directory, type 'forrest' to
render the HTML and PDF
- files in <code>build/site</code>. Forrest validates the XML,
so will catch any syntax errors.</p>
- <p>Do this only if you are going to update the site yourself.
If not, sumple use a validating
- parser and commit the changes or send the patch.</p>
- <p>You can also simply validate docs without rendering doing
a</p>
- <source> forrest validate</source>
-
-
- </section>
-
- <section>
- <title>Submit or commit the change</title>
- <p>If the site built without errors, you have to synch the
<code>incubator/build/site</code>
- dir with <code>incubator-site/build/site</code>. To do this
you can use the <code>build.xml</code>
- script by invoking Ant</p>
- <source> ant </source>
+ <li>cd into the local "incubator" CVS dir.</li>
+ <li>Do 'forrest run'.</li>
+ <li>Browser http://localhost:8888/ to review the site.</li>
+ <li>Edit the docs <strong>in place</strong> at
<code>site/*.*</code>
+ and see changes in the browser by re-loading the page.</li>
+ </ul>
+
+ <p>When you are satisifed, you will rebuild the whole site and
+ add the changed documents to the "incubator-site" CVS.
+ </p>
+
+ <p>In the "<code>incubator</code>" directory, do 'forrest' to
+ render the HTML and PDF files into "<code>build/site</code>".
+ Forrest validates the XML, so will catch any syntax errors.
+ You can also simply validate the source xdocs without rendering
+ by doing 'forrest validate'.</p>
+
+ <p>If the site built without errors, you now need to synch the
+ <code>incubator/build/site</code> directory with the
+ <code>incubator-site/build/site</code> directory.</p>
+ <source>
+diff -rq incubator/build/site incubator-site/build/site
+... Ensure that the differences are what you expect.
+cp -Rf incubator/build/site/* incubator-site/build/site
+... Now do the usual CVS stuff: 'cvs update' 'cvs add' 'cvs diff' cvs commit'
+ </source>
+
+ <p>Another way to do this is to use the <code>build.xml</code>
+ script by invoking Ant "syncsite" task. Do 'ant' in the
top-level
+ "incubator" directory.</p>
- <p>You can now make a patch with the command
- <code>cvs diff -u > incubator-site.diff</code> in the
<code>incubator-site/</code>
- directory, and submit it to the mailing list, starting with
'<code>[PATCH]</code>' in the email subject.</p>
-
- <p>Incubator committers can just commit the contents of
<code>build/site</code> (after checking it is okay!).</p>
+ <p>If you are not an Incubator committer, then you can now
make a
+ patch with the command
+ '<code>cvs diff -u > incubator-site.diff</code>' in the
+ "<code>incubator-site/</code>" directory, and submit it to the
+ mailing list, starting with '<code>[PATCH]</code>' in the email
+ subject.</p>
+
+ <p>Incubator committers can just commit the contents of
+ <code>incubator-site/build/site</code> (after checking it is
okay!).
+ Then publish the website on the server.
+ </p>
+ <source>
+ssh www.apache.org
+cd /www/incubator.apache.org
+cvs update -Pd
+ </source>
</section>
</section>
</section>
+
<section id="project">
<title>Project-specific resources</title>
<p>Some <link href="site:projects">projects</link> under incubation
have their own mailing lists,
1.10 +6 -5 incubator/site/incubation/Incubation_Policy.cwiki
Index: Incubation_Policy.cwiki
===================================================================
RCS file: /home/cvs/incubator/site/incubation/Incubation_Policy.cwiki,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- Incubation_Policy.cwiki 21 Jun 2004 09:29:09 -0000 1.9
+++ Incubation_Policy.cwiki 11 Sep 2004 06:19:02 -0000 1.10
@@ -182,17 +182,18 @@
{{{ /www/incubator.apache.org/projectname
}}}
-{{/www/incubator.apache.org/projectname}} has to be checked out of CVS. We
don't care how it gets into CVS, or which CVS module it lives in, but it had
better be there.
+To create the website, the directory
{{/www/incubator.apache.org/projectname}} is checked out of CVS. We don't care
how it gets into CVS, or which CVS module it lives in, but it had better be
there.
-People using Maven, ForrestBot, or any other tool still have to address the
CVS publishing requirement that the infrastructure team has laid out. If that
is done, then we just run cvs up in that directory to load the site from CVS.
+People using Maven, ForrestBot, or any other tool still have to address the
CVS publishing requirement that the infrastructure team has laid out. If that
is done, then we just run "cvs update" in that directory to load the site from
CVS.
-The Mentors MUST add the information about the CVS module and dir where the
published site is, in the project incubation status file.
+The Mentors MUST add the information to the project incubation status file,
to
+descibe the CVS module and the directory which holds the published site.
-If the project does not want to host the published site in their CVS, it has
a space under:
+If the project does not want to host the published site in their project
CVS, it has a space under:
{{{ incubator-site/build/site/projectname/**
}}}
-The site is automatically updated from there once a day.
+The site is automatically updated from CVS once a day.
!!!Exitting the Incubator
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
