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/05/03 08:16:36 UTC
cvs commit: xml-fop/src/documentation/content/xdocs book.xml compiling.xml download.xml
vmote 2003/05/02 23:16:35
Modified: src/documentation/content/xdocs book.xml compiling.xml
download.xml
Log:
Add content for the build process.
Change terminology from "compile" to "build".
Add building javadocs as a reason to download source.
Revision Changes Path
1.20 +1 -1 xml-fop/src/documentation/content/xdocs/book.xml
Index: book.xml
===================================================================
RCS file: /home/cvs/xml-fop/src/documentation/content/xdocs/book.xml,v
retrieving revision 1.19
retrieving revision 1.20
diff -u -r1.19 -r1.20
--- book.xml 22 Apr 2003 18:11:44 -0000 1.19
+++ book.xml 3 May 2003 06:16:35 -0000 1.20
@@ -23,7 +23,7 @@
<menu label="Using FOP">
<menu-item label="Release Notes" href="relnotes.html"/>
<menu-item label="Download" href="download.html"/>
- <menu-item label="Compile" href="compiling.html"/>
+ <menu-item label="Build" href="compiling.html"/>
<menu-item label="Configure" href="configuration.html"/>
<menu-item label="Run" href="running.html"/>
<menu-item label="Embed" href="embedding.html"/>
1.6 +24 -7 xml-fop/src/documentation/content/xdocs/compiling.xml
Index: compiling.xml
===================================================================
RCS file: /home/cvs/xml-fop/src/documentation/content/xdocs/compiling.xml,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- compiling.xml 14 Apr 2003 22:28:26 -0000 1.5
+++ compiling.xml 3 May 2003 06:16:35 -0000 1.6
@@ -4,13 +4,13 @@
<document>
<header>
- <title>Compiling FOP</title>
+ <title>FOP: Building from Source Code</title>
</header>
<body>
<section>
- <title>Do You Need To Compile?</title>
+ <title>Do You Need To Build?</title>
<p>FOP distributions are either pre-compiled binary or source.
-If you are using a binary distribution, it is already compiled and there is no need to compile it again. See the <link href="download.html">Download Instructions</link> for information about whether a binary or source distribution is best for your needs.
+If you are using a binary distribution, it is already built and there is no need to build it again. See the <link href="download.html">Download Instructions</link> for information about whether a binary or source distribution is best for your needs.
</p>
</section>
<section>
@@ -29,18 +29,35 @@
</section>
<section>
<title>JAVA_HOME</title>
- <p>Ant, which is used by the build script, requires that the enviroment variable JAVA_HOME point to your local JDK root directory.
+ <p>Ant, which is used by the build script, requires that the environment variable JAVA_HOME point to your local JDK root directory.
This is true even if you use JDK 1.2 or above, which normally don't need this setting.</p>
</section>
</section>
<section>
<title>Run the "build" Script</title>
<p>Build FOP by executing the "build" script, which is located in the FOP root directory.
-The Windows batch file is build.bat, and the Unix shell script is build.sh.</p>
+The Windows batch file is build.bat, and the Unix shell script is build.sh.
+The examples below are for running the shell script, but except for the build file extension, the syntax is identical.</p>
<p>The build script uses <link href="http://jakarta.apache.org/ant/">Ant</link>, a popular java-based build tool.
The file build.xml in the FOP root directory is the blueprint that Ant uses for the build.
-Consult its contents for detailed information on the build process and the various build targets.</p>
- <p>A help screen is shown by calling "build usage".</p>
+It contains information for numerous build targets, many of which are building blocks to more useful target, and others which are primarily used by the FOP developers.
+You may benefit from looking through this file to learn more about the various build targets.
+To obtain a complete list of useful build targets:</p>
+ <source>build.sh -projecthelp</source>
+ <p>The most useful targets are:</p>
+ <ul>
+ <li><strong>package</strong>: Generates the jar files (default). This is the normal build that produces a jar file usable for running FOP.</li>
+ <li><strong>clean </strong>: Cleans the build directory. This is useful for making sure that any build errors are cleaned up before starting a new build. It should not ordinarily be needed, but may be helpful if you are having problems with the build process itself.</li>
+ <li><strong>javadocs</strong>: Generates javadocs. This creates the FOP API documentation.</li>
+ </ul>
+ <p>To run the build:</p>
+ <source>build.sh [target ...]</source>
+ <p>For example to do a normal build for the package target (which is the default):</p>
+ <source>build.sh</source>
+ <p>OR</p>
+ <source>build.sh package</source>
+ <p>To clean the build directory first:</p>
+ <source>build.sh clean package</source>
</section>
<section>
<title>Troubleshooting</title>
1.8 +2 -1 xml-fop/src/documentation/content/xdocs/download.xml
Index: download.xml
===================================================================
RCS file: /home/cvs/xml-fop/src/documentation/content/xdocs/download.xml,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- download.xml 29 Apr 2003 05:19:13 -0000 1.7
+++ download.xml 3 May 2003 06:16:35 -0000 1.8
@@ -4,7 +4,7 @@
<document>
<header>
- <title>Downloading FOP</title>
+ <title>FOP: Downloading A Distribution</title>
</header>
<body>
<section id="dist-type">
@@ -14,6 +14,7 @@
<ul>
<li>You wish to modify FOP.</li>
<li>You wish to use a version more recent than the latest release. For example, if you have read on the user mailing list that a bug has been fixed or a feature added that you are eager to try, you might download a source distribution from the CVS repository so that you don't have to wait for the next release.</li>
+ <li>You wish to build a local copy of the API documentation (javadocs).</li>
</ul>
</section>
<section id="binary">
---------------------------------------------------------------------
To unsubscribe, e-mail: fop-cvs-unsubscribe@xml.apache.org
For additional commands, e-mail: fop-cvs-help@xml.apache.org
RE: book.xml
Posted by Victor Mote <vi...@outfitr.com>.
Jeremias Maerki wrote:
> After adding some additional links to
> resources.xml I think we should factor out the mailing lists (separate
> page). That would make them more visible. What do you think?
That thought has crossed my mind several times, especially since they are
now buried on a page called "Other". I'll work on that.
Victor Mote
---------------------------------------------------------------------
To unsubscribe, e-mail: fop-dev-unsubscribe@xml.apache.org
For additional commands, email: fop-dev-help@xml.apache.org
Re: book.xml
Posted by Jeremias Maerki <de...@greenmail.ch>.
You're doing fine, Victor. After adding some additional links to
resources.xml I think we should factor out the mailing lists (separate
page). That would make them more visible. What do you think?
On 14.05.2003 17:38:45 Victor Mote wrote:
> I didn't see any further feedback on this topic. I went ahead and moved the
> "Project" stuff down to the bottom (in CVS), which now makes "Download" very
> near the top. That covers some, but not nearly all of what Joerg suggested.
> There is some cleanup work to be done still in the "Project" section, but I
> am still trying to grasp how the Forrest dtds all play into Changes & Status
> & the related documents.
>
> If we asked 20 developers (or users) what the menu should look like, we
> would get at least 21 different answers. I took the liberty of implementing
> mine, but am quite happy for anyone else to do so as well.
Jeremias Maerki
---------------------------------------------------------------------
To unsubscribe, e-mail: fop-dev-unsubscribe@xml.apache.org
For additional commands, email: fop-dev-help@xml.apache.org
RE: book.xml
Posted by Victor Mote <vi...@outfitr.com>.
Victor Mote wrote:
> J.Pietschmann wrote:
...
> > > Please feel free to change it if you wish.
> > Some discussion shouldn't hurt.
>
> I agree & I'm glad for the feedback. Perhaps I should have discussed it
> before changing it. I went through numerous iterations to get it where it
> is, and as you can tell from some of my comments above, I am not sure I am
> through. I'm not sure I could have put forth a complete proposal
> to discuss.
I didn't see any further feedback on this topic. I went ahead and moved the
"Project" stuff down to the bottom (in CVS), which now makes "Download" very
near the top. That covers some, but not nearly all of what Joerg suggested.
There is some cleanup work to be done still in the "Project" section, but I
am still trying to grasp how the Forrest dtds all play into Changes & Status
& the related documents.
If we asked 20 developers (or users) what the menu should look like, we
would get at least 21 different answers. I took the liberty of implementing
mine, but am quite happy for anyone else to do so as well.
Victor Mote
---------------------------------------------------------------------
To unsubscribe, e-mail: fop-dev-unsubscribe@xml.apache.org
For additional commands, email: fop-dev-help@xml.apache.org
RE: book.xml
Posted by Victor Mote <vi...@outfitr.com>.
J.Pietschmann wrote:
> > The other issue you address is that "Configure", and it seems
> very awkward
> > to tell people to run the thing first, then configure it.
>
> Again, "configuring" means "adding user fonts" for most people,
> and again almost all start with no user fonts (except the DocBook
> folks which seems to be very attached to ArialUni and Verdana,
> and they can get a pre-customized FOP).
That may be true for the moment, but I expect that to change significantly
in the future. I will say that I think we should beef up the configure
documentation quite a bit, and maybe say something at the top like "if you
are a new user, you can skip this for now & just use the defaults".
> My concerns are more about usability of the web site: will
> untrained users find out what they can do and how to do
> it before they loose patience? Can corporate developers
> check whether they can use FOP for their task quickly enough
> so that their boss wont order them to use AntennaHouse (the
> license is important for this too).
> I don't think people should use the menu as some sort of
> check list.
I actually thought the changes made it more usable -- again that is an
opinion, with no good way to prove. Even if they don't use it as a
checklist, there needs to be some logic to the order of the items, and
chronological seemed to me to be the best. If you try to do it in order of
importance, you really have no opportunity to use the menu groupings, and I
think order of importance is in the eye of the beholder. You are correct
that some will think the license is most important, others will never look
at it, either because they don't care or already know the Apache license.
> Perhaps we should have the following categories and menu points
> - Project
One change I have seriously considered making is to move everything
currently in "About" and "Project", except "Home", down to the bottom, in
one section called "Project". This stuff is probably the least important and
least interesting. Under the current system, that would put "Using" right
after "Home", which makes sense to me.
> Home (traditionally at the top)
> Download (by far the most interesting point)
Yes, but to my mind has much more to do with "Using" than "Project". I don't
think people looking at the menu are going to have a hard time finding
Download where it is.
> Using (dispatch to: running the CLI, embedding, user fonts,
> building)
This gives us "Using" in two places (??!!)
> getting help (dispatch to: FAQ, mailing list, bugzilla
> FAQ (should be more prominent)
I don't mind moving the whole resources section to the top or nearer the
top, but I really think both of these belong with Resources.
> release notes
> license
> - Using
> getting source (*bg*, include more details about how to access
> the *maintenance* branch in CVS)
Now you have "Download" in two places. With regard to the instructions on
how to get to the maintenance branch, I might have removed those in favor of
a link to the topic instead. Part of what I was trying to do is eliminate
the need to document things multiple times. Your approach may be better.
> building
> configure (include better dispatch to user fonts)
> running
Did you decide that configure before running is OK?
> embedding
> ant task
> dispatch to cocoon serializer
> dispatch to batik for svg renderer
> - features
> (unchanged)
> - ressources
> project status
> project changes (quite outdated -> remove?)
+1
> project todo (outdated and superceded by status -> remove?)
+1 (at least move this stuff to the dev area)
> fo sample code (now: XSL-FO)
There is more than sample code here.
> java sample code (for embedding)
You don't think it is better on the "Embedding" page?
> specs, literature & misc
>
> > Please feel free to change it if you wish.
> Some discussion shouldn't hurt.
I agree & I'm glad for the feedback. Perhaps I should have discussed it
before changing it. I went through numerous iterations to get it where it
is, and as you can tell from some of my comments above, I am not sure I am
through. I'm not sure I could have put forth a complete proposal to discuss.
Victor Mote
---------------------------------------------------------------------
To unsubscribe, e-mail: fop-dev-unsubscribe@xml.apache.org
For additional commands, email: fop-dev-help@xml.apache.org
Re: book.xml
Posted by "J.Pietschmann" <j3...@yahoo.de>.
Victor Mote wrote:
> I wanted the checklist to be a general checklist that covered both binary
> and source downloaders.
Granted. The vast majority of people seem to prefer getting
the binary first and dive right into running some examples.
> The other issue you address is that "Configure", and it seems very awkward
> to tell people to run the thing first, then configure it.
Again, "configuring" means "adding user fonts" for most people,
and again almost all start with no user fonts (except the DocBook
folks which seems to be very attached to ArialUni and Verdana,
and they can get a pre-customized FOP).
> You're right -- no one is going to follow the checklist, but it represents
> our (my) idealized view of how the process should work. If the user skips a
> step or two, at least the checklist gives them some idea of where they
> should look to get back on track.
My concerns are more about usability of the web site: will
untrained users find out what they can do and how to do
it before they loose patience? Can corporate developers
check whether they can use FOP for their task quickly enough
so that their boss wont order them to use AntennaHouse (the
license is important for this too).
I don't think people should use the menu as some sort of
check list.
Perhaps we should have the following categories and menu points
- Project
Home (traditionally at the top)
Download (by far the most interesting point)
Using (dispatch to: running the CLI, embedding, user fonts,
building)
getting help (dispatch to: FAQ, mailing list, bugzilla
FAQ (should be more prominent)
release notes
license
- Using
getting source (*bg*, include more details about how to access
the *maintenance* branch in CVS)
building
configure (include better dispatch to user fonts)
running
embedding
ant task
dispatch to cocoon serializer
dispatch to batik for svg renderer
- features
(unchanged)
- ressources
project status
project changes (quite outdated -> remove?)
project todo (outdated and superceded by status -> remove?)
fo sample code (now: XSL-FO)
java sample code (for embedding)
specs, literature & misc
> Please feel free to change it if you wish.
Some discussion shouldn't hurt.
Well, let's face it: I'm lazy :-)
Still, what are the opinions of other devs and assorted fop-dev lurkers?
J.Pietschmann
---------------------------------------------------------------------
To unsubscribe, e-mail: fop-dev-unsubscribe@xml.apache.org
For additional commands, email: fop-dev-help@xml.apache.org
RE: book.xml
Posted by Victor Mote <vi...@outfitr.com>.
J.Pietschmann wrote:
> vmote@apache.org wrote:
> > <menu label="Using FOP">
> > <menu-item label="Release Notes" href="relnotes.html"/>
> > <menu-item label="Download" href="download.html"/>
> > - <menu-item label="Compile" href="compiling.html"/>
> > + <menu-item label="Build" href="compiling.html"/>
> > <menu-item label="Configure" href="configuration.html"/>
> > <menu-item label="Run" href="running.html"/>
> > <menu-item label="Embed" href="embedding.html"/>
>
> I'd think the user preferences are
> 1. download
> 2. run
> 3. curse
> 4. read release notes
> 5. curse again
> 6. get CVS source
> 7. build
> 8. heavy swearing
> 9. configure
> 10. more cursing
> 11. embedding
>
> I'ts probably a good idea to keep the release notes at the top
> but shouldn't the "Run" topic moved to right after "Download"?
> I had taken a bet it was there....
I think it used to be -- I did change this around a couple of weeks ago. I
don't feel strongly about this, but here is why I did it this way:
I wanted the checklist to be a general checklist that covered both binary
and source downloaders. The alternative, IMO, was to have separate download
instructions for the two groups, basically the #1 & #6 in your (no doubt
accurate) story. To document it that way seemed awkward and confusing. The
download instructions cover both downloading binary and source
distributions, with a section at the top that helps them figure out which
one they need. If they choose binary, then when they get to the build page,
it basically tells them they don't need to do a build.
The other issue you address is that "Configure", and it seems very awkward
to tell people to run the thing first, then configure it. I don't remember
where it was before, but you really can't put it before Download or after
Run, can you? Where else would you put it than where it is?
You're right -- no one is going to follow the checklist, but it represents
our (my) idealized view of how the process should work. If the user skips a
step or two, at least the checklist gives them some idea of where they
should look to get back on track.
Please feel free to change it if you wish. What is essentially there right
now was my best guess as to what it should look like. I have no doubt that
it can be improved.
Victor Mote
---------------------------------------------------------------------
To unsubscribe, e-mail: fop-dev-unsubscribe@xml.apache.org
For additional commands, email: fop-dev-help@xml.apache.org
book.xml
Posted by "J.Pietschmann" <j3...@yahoo.de>.
vmote@apache.org wrote:
> <menu label="Using FOP">
> <menu-item label="Release Notes" href="relnotes.html"/>
> <menu-item label="Download" href="download.html"/>
> - <menu-item label="Compile" href="compiling.html"/>
> + <menu-item label="Build" href="compiling.html"/>
> <menu-item label="Configure" href="configuration.html"/>
> <menu-item label="Run" href="running.html"/>
> <menu-item label="Embed" href="embedding.html"/>
I'd think the user preferences are
1. download
2. run
3. curse
4. read release notes
5. curse again
6. get CVS source
7. build
8. heavy swearing
9. configure
10. more cursing
11. embedding
I'ts probably a good idea to keep the release notes at the top
but shouldn't the "Run" topic moved to right after "Download"?
I had taken a bet it was there....
J.Pietschmann
---------------------------------------------------------------------
To unsubscribe, e-mail: fop-dev-unsubscribe@xml.apache.org
For additional commands, email: fop-dev-help@xml.apache.org