1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
|
<?xml version="1.0" standalone="no"?>
<!--
Copyright 1999-2004 The Apache Software Foundation
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!-- $Id$ -->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/core/context/resources/schema/dtd/document-v12.dtd">
<document>
<header>
<title>FOP Development: Managing Documentation</title>
<version>$Revision$</version>
</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="design">
<title>Design Principles</title>
<p>These principles are not written in stone, but reflect the current philosophy, and are documented here primarily to help achieve consistency. These principles should be changed if better or more practical ones are found, but they should probably be discussed and changed by common consent.</p>
<section id="where">
<title>Where</title>
<ul>
<li>To the extent possible, keep user content separate from developer content, primarily so the user doesn't have to filter out technical information.</li>
<li>To the extent possible, try to document a topic exactly once, in the place the user is most likely to look for it, then link to that from other locations as appropriate. This is somewhat contrary to the principle above, which should be applied as a higher priority.</li>
</ul>
</section>
<section id="design-when">
<title>When</title>
<p>The documentation and the product are in a constant state of change, and there is some difficulty in deciding what product state the website content should reflect. The current thinking is that the website should reflect the current state of the repository code branch from which releases are made. Features or other documentation that applies to unreleased code should be marked in such a way within the content that the user can determine whether and how it applies to the version they are using. For example, "Feature xyz is first available in Release n.nn.n".</p>
<p>Other approaches were considered, but all seemed to have significantly higher costs both to the users and the developers. From the user's standpoint, the choice is either that they potentially have to look multiple places to get the information they need (which was rejected), or they have to filter out an occasional feature that is in code available subsequent to their release (which was accepted).</p>
</section>
</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>Process</th>
<th>Output</th>
<th>State</th>
<th>View(s)</th>
</tr>
<tr>
<td>Developer commits code to FOP repository.</td>
<td>FOP repository (cvs) at cvs.apache.org/home/cvs/xml-fop</td>
<td>Raw XML and other content</td>
<td><link href="http://cvs.apache.org/viewcvs.cgi/xml-fop/src/documentation/content/xdocs/">ViewCVS</link></td>
</tr>
<tr>
<td>Developer builds documentation and commits it to xml-site.</td>
<td>xml-site repository (cvs) at cvs.apache.org/home/cvs/xml-site</td>
<td>web-ready</td>
<td><link href="http://cvs.apache.org/viewcvs.cgi/xml-site/targets/fop/">ViewCVS</link></td>
</tr>
<tr>
<td>Developer publishes website.</td>
<td>FOP live web site, /www/xml.apache.org/fop on www.apache.org</td>
<td>web-ready</td>
<td><link href="http://xml.apache.org/fop">FOP Web Site</link></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><link href="#forrestbot-publish">Forrestbot "publish"</link>. 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><link href="http://cvs.apache.org/viewcvs.cgi/xml-site/targets/fop/">ViewCVS</link></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><link href="http://xml.apache.org/fop">FOP Web Site</link></td>
</tr>
-->
</table>
<note>Forrestbot is currently not available for website publishing.</note>
</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><link href="http://forrest.apache.org/mirrors.cgi#closest">download</link> latest the Forrest release</li>
<li>checkout the xml-site/targets/fop module (same repository as xml-fop)</li>
<li>set environment variable FORREST_HOME=~/apache-forrest-0.6/src/core where ~ is the directory where Forrest is installed
(see <link href="http://forrest.apache.org/docs/your-project.html">http://forrest.apache.org/docs/your-project.html</link> 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</title>
<!--
<warning>The steps in this section should not ordinarily be used. They are documented here for historical reasons, and for emergencies.
See <link href="#delete">manually deleting retired files</link> for an exception to this rule.</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 id="delete">
<title>Deleting Documentation Files</title>
<p>The one place where manual updates of the web cvs repository are required is when a document is retired. At this point, it will no longer be generated. However, it will still exist in the web cvs repository. You will need to use a cvs client to remove the files, then commit the changes to keep them from continuing to exist on the live site.</p>
</section>
<section id="publish">
<title>Publish the Website</title>
<ul>
<li>ssh to www.apache.org</li>
<li>cd /www/xml.apache.org/fop</li>
<li>make sure your umask is 0002 (to make the files group writeable)</li>
<li>cvs up -Pd</li>
</ul>
</section>
</section>
</body>
</document>
|
