You are viewing a plain text version of this content. The canonical link for it is here.
Posted to fop-commits@xmlgraphics.apache.org by vm...@apache.org on 2003/04/21 21:48:03 UTC
cvs commit: xml-fop/src/documentation/content/xdocs/dev doc.xml
vmote 2003/04/21 12:48:03
Added: src/documentation/content/xdocs/dev doc.xml
Log:
Move documentation README to a web page.
Revision Changes Path
1.1 xml-fop/src/documentation/content/xdocs/dev/doc.xml
Index: doc.xml
===================================================================
<?xml version="1.0" standalone="no"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.dtd">
<document>
<header>
<title>Managing FOP Documentation</title>
</header>
<body>
<section id="general">
<title>General Information</title>
<p>All raw documentation content is managed in the FOP CVS repository.
Updates should be committed to the repository, then the repository files are used to generate usable output.
The remaining discussions on this page assume that the CVS repository is the starting place for processing.
The path to the documentation is xml-fop/src/documentation/content/xdocs.</p>
<note>All documentation is maintained on the trunk.
Although we are currently maintaining two sets of code (trunk and maintenance), there is only one set of documentation.
Most of the user and developer doc is common to the two environments, and differences are highlighted where necessary.
The major exception to this rule is the design doc, which currently exclusively pertains to the trunk (redesign).
Maintenance branch releases either copy the trunk content to the maintenance branch or use the trunk content directly for doc builds.</note>
<p>Basic documents are stored in XML files, and use DTDs provided by Apache Forrest.</p>
</section>
<section id="web">
<title>Website</title>
<section id="web-background">
<title>Background</title>
<p>The FOP web site and documentation are generated using <link href="http://xml.apache.org/forrest">Apache Forrest</link>.</p>
<p>The following table summarizes the flow of data to the FOP website in chronological order:</p>
<table>
<tr>
<th>Processes</th>
<th>Files</th>
<th>State</th>
<th>Views</th>
</tr>
<tr>
<td>.</td>
<td>FOP source repository (cvs) at icarus.apache.org/home/cvs/xml-fop</td>
<td>Raw XML and other content</td>
<td>ViewCVS</td>
</tr>
<tr>
<td>
<link href="#forrestbot-refresh">Forrestbot "refresh"</link>. Automatically done every six hours. Can be manually refreshed by authorized users at <link href="http://forrestbot.cocoondev.org">the Forrestbot Web Interface</link>.
</td>
<td>Physical location unknown and unimportant to us</td>
<td>web-ready</td>
<td>Content can be viewed <link href="http://forrestbot.cocoondev.org/sites/xml-fop">here</link>.</td>
</tr>
<tr>
<td>Forrestbot "publish". Always done manually at <link href="http://forrestbot.cocoondev.org">the Forrestbot Web Interface</link>.</td>
<td>FOP web repository (cvs) at icarus.apache.org/home/cvs/xml-site/targets/fop</td>
<td>web-ready</td>
<td/>
</tr>
<tr>
<td>Automatic Live Site Update every six hours (midnight, 6am, noon, 6pm Pacific time).</td>
<td>FOP live web site, somewhere on daedalus.apache.org</td>
<td>web-ready</td>
<td/>
</tr>
</table>
</section>
<section id="web-forrestbot-refresh">
<title>Forrestbot "refresh" Step-by-Step</title>
<note>The Forrestbot "refresh" is automatically run on the server every six hours. Only follow the steps below if you need to check the results more promptly than that allows, or if you need to "refresh" in preparation for a "publish".</note>
<p>To manually use the Forrestbot "refresh", simply follow these steps:</p>
<ul>
<li>Make sure your changes are committed to the FOP source repository.</li>
<li>Open http://forrestbot.cocoondev.org in your browser.</li>
<li>Login.</li>
<li>In the "Select a module" box, select "xml-fop".</li>
<li>Click the "refresh" button to have the interim site built.
On-screen instructions tell you how to view the log as the build progresses.</li>
</ul>
</section>
<section id="web-forrestbot-publish">
<title>Forrestbot "publish" Step-by-Step</title>
<p>To "publish" the Forrestbot output to the FOP Web repository:</p>
<ul>
<li>Make sure you are satisfied with the "refreshed" site.</li>
<li>Open http://forrestbot.cocoondev.org in your browser.</li>
<li>Login.</li>
<li>In the "Select a module" box, select "xml-fop".</li>
<li>Click the "publish" button.
On-screen instructions tell you how to view the log as the build progresses.</li>
<li>Wait for the next 6-hour live-site update cycle and check your changes.</li>
</ul>
</section>
<section id="web-live-update">
<title>Live Site Update</title>
<p>If there are problems with the live site update (the process of copying the web site contents from the FOP web repository to the live site:</p>
<ul>
<li>The CVS update logs can be viewed at http://www.apache.org/~rubys/updatesite.logx, where "x" is a number from 1-4, these four files being the updates done over the past 24 hours.
Review the most recent log file for clues.</li>
<li>The script is maintained by Sam Ruby (rubys@apache.org).
Contact him for further help.</li>
</ul>
</section>
<section id="web-local-forrest">
<title>Using a Local Forrest</title>
<note>Most documentation content changes do not require a local copy of Forrest.
In general, use the Forrestbot instead. Forrestbot is easy to use, always uses the "approved" methodology, and has fewer error-prone manual steps.</note>
<p>There are some situations where you may want to have a local Forrest installation. For example, you do not want to tie up server resources testing major changes, such as sitemap building, that may require many edit/build/test/debug cycles. After you are done testing, use the forrestbot to "refresh" and "publish" the site.</p>
<note>Forrest needs to be run on a machine with a graphical environment.
It will fail in a headless environment when it tries to use FOP to generate the PDF files.</note>
<p>To use a local Forrest:</p>
<ul>
<li>checkout the xml-forrest module (same repository as xml-fop)</li>
<li>checkout the xml-site/targets/fop module (same repository as xml-fop)</li>
<li>you will also need access to a current xml-fop sandbox (you probably already
have one)</li>
<li>cd to xml-forrest</li>
<li>run: build.sh(bat) dist to build forrest</li>
<li>set environment variable FORREST_HOME=~/xml-forrest/build/dist/shbat where ~ is the directory in which xml-forrest is installed (see http://xml.apache.org/forrest/your-project.html for details)</li>
<li>set environment variable PATH=$PATH:$FORREST_HOME/bin</li>
<li>cd to xml-fop directory</li>
<li>run forrest(.bat), which will build the web-site documents in xml-fop/build/site.</li>
</ul>
</section>
<section id="web-manual">
<title>Updating the FOP Web Repository Manually (Deprecated)</title>
<warning>The steps in this section should not ordinarily be used. They are documented here for historical reasons, and for emergencies.</warning>
<ul>
<li>Copy (or sym-link) the documents generated by Forrest (in xml-fop/build/site) to xml-site/targets/fop on your local machine.</li>
<li>Commit xml-site/targets/fop.</li>
</ul>
</section>
</section>
</body>
</document>
---------------------------------------------------------------------
To unsubscribe, e-mail: fop-cvs-unsubscribe@xml.apache.org
For additional commands, e-mail: fop-cvs-help@xml.apache.org