RE: javadocs
Keiron Liddle wrote: > I hope you didn't get the idea that I was ignoring the patch. It is just > that it is for the branch and it can be a pain to get things set up. > > Hopefully another committer with the branch can give a look at it. > No, I wasn't worried about that -- I just wanted to make sure I didn't disqualify the patch on a procedural problem. I'll follow the guidelines in the future. Vic - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, email: [EMAIL PROTECTED]
RE: javadocs
Hi Victor, Usually it is a good idea to follow those guidelines. I hope you didn't get the idea that I was ignoring the patch. It is just that it is for the branch and it can be a pain to get things set up. Hopefully another committer with the branch can give a look at it. On Wed, 2002-07-31 at 16:49, Victor Mote wrote: > I think my submission complied with http://xml.apache.org/fop/involved.html, > but I did not follow the link to http://xml.apache.org/source.html#, and I > see now that my submission was deficient in two ways: 1) not adding the > [PATCH] header, and 2) not using "diff -u". Should I resubmit the patch > using those conventions? Also, I see in some other postings use of a > [DOCUMENTATION] header. Is there a page (other than those above) where that > convention and any other relevant ones are discussed? There is no specific information that I am aware of. I can help get things noticed for the appropriate purpose. > Thanks for your patience. > > Victor Mote (mailto:[EMAIL PROTECTED]) > Enterprise Outfitters (www.outfitr.com) > 2025 Eddington Way > Colorado Springs, Colorado 80916 > Voice 719-622-0650, Fax 720-293-0044 - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, email: [EMAIL PROTECTED]
RE: javadocs
I think my submission complied with http://xml.apache.org/fop/involved.html, but I did not follow the link to http://xml.apache.org/source.html#, and I see now that my submission was deficient in two ways: 1) not adding the [PATCH] header, and 2) not using "diff -u". Should I resubmit the patch using those conventions? Also, I see in some other postings use of a [DOCUMENTATION] header. Is there a page (other than those above) where that convention and any other relevant ones are discussed? Thanks for your patience. Victor Mote (mailto:[EMAIL PROTECTED]) Enterprise Outfitters (www.outfitr.com) 2025 Eddington Way Colorado Springs, Colorado 80916 Voice 719-622-0650, Fax 720-293-0044 - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, email: [EMAIL PROTECTED]
RE: javadocs
On Tue, 2002-07-30 at 19:01, Victor Mote wrote: > My goal here is to use the javadocs as an educational tool for getting up to > speed on FOP. As I went along, I thought I would add javadoc comments as I > learned something useful that was not already documented. I realize that > some (perhaps much or all) of this code is "experimental", and I understand > that the main branch is undergoing a redesign. If javadoc comments will be > lost in the merge, or if a large number of classes will be rewritten (ie. > the old versions abandoned), then perhaps I should wait until after the > merge before spending much effort here. As far as I am concerned the only packages in HEAD that are likely to change much are apps.* and layoutmgr.*. The rest should be fairly fixed now (as far as classes and methods). So you might be able to get started in some areas. I have noticed a number of people try to look at the javadocs and get lost trying to find what they want. So work in this area is needed. Keiron. An appropriate quote: "Excuse me, teacher? May I be excused? My brain is full." - Larson - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, email: [EMAIL PROTECTED]
RE: javadocs
Keiron Liddle wrote:
> Are you generating the javadocs from the distribution?
> The problem sounds like a packaging issue. Those files have the line
> endings for the OS they are checked out on.
> As far as I know javadocs has always worked from cvs.
I was generating the javadocs from cvs. However, because of the way my
internet connections are configured at the moment, I was using WinCvs for
interfacing with the repository, and using Linux for the builds. I should
have realized that was the source of the problem. There is no packaging
problem (that I know of), and I will deal with this as a local issue.
> We probably need more javadoc info in general. Much of the javadoc is
> dependant on the stability of the interfaces and classes.
My goal here is to use the javadocs as an educational tool for getting up to
speed on FOP. As I went along, I thought I would add javadoc comments as I
learned something useful that was not already documented. I realize that
some (perhaps much or all) of this code is "experimental", and I understand
that the main branch is undergoing a redesign. If javadoc comments will be
lost in the merge, or if a large number of classes will be rewritten (ie.
the old versions abandoned), then perhaps I should wait until after the
merge before spending much effort here.
I do recommend making the remaining changes, which are in the attached patch
file.
Vic
Index: build.sh
===
RCS file: /home/cvspublic/xml-fop/build.sh,v
retrieving revision 1.15.2.7
diff -w -r1.15.2.7 build.sh
32a33,36
> # antRun must be executable (can't do this in build.xml because Ant uses antRun
> # to do the chmod)
> chmod +rx $LIBDIR/bin/antRun
>
Index: build.xml
===
RCS file: /home/cvspublic/xml-fop/build.xml,v
retrieving revision 1.44.2.21
diff -w -r1.44.2.21 build.xml
402c402
< excludes="**/package.html,
**/${jimi},**/${jai},**/${xsltransform},**/${trax},**/apps/TraxInputHandler.java"/>
---
>
>excludes="**/${jimi},**/${jai},**/${xsltransform},**/${trax},**/apps/TraxInputHandler.java"/>
633,634d632
<
<
651a650,651
> overview="${build.src}/overview.html"
> failonerror="true"
-
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, email: [EMAIL PROTECTED]
RE: javadocs
On Tue, 2002-07-30 at 04:28, Victor Mote wrote: > FOP Committers: > > The underlying problem was that lib/bin/antRun had DOS line endings in it (I > am running on Linux 6.1), causing it to fail when used by javadoc from > within Ant. This cannot be fixed from within the build.xml file using > fixcrlf because the file is recreated, and (depending on umask) has > not-executable file permissions. Also, you can't use Ant's chmod to fix the > file permissions, because chmod itself relies on antRun to perform the > chmod. I moved the logic that attempted to change antRun's permissions from > build.xml to build.sh, and added code to strip out the offending end-of-line > characters to build.sh as well. The remaining changes are related to items 3 > and 4. > > I did not find or create a bug report for this problem. Perhaps I am the > only one experiencing it? Are you generating the javadocs from the distribution? The problem sounds like a packaging issue. Those files have the line endings for the OS they are checked out on. As far as I know javadocs has always worked from cvs. > I noticed that code in the "dist-src" target has javadoc turned off. Perhaps > with the attached fix, it can be turned back on again? The idea was that the src distribution is just the source, generated files are left out. The javadocs can be generated from the source. Of course this is dependant on the above issue being sorted out. > > 3. It is trivial to add the "overview" attribute to build.xml to > > handle the overview file. > > 4. Right now, build.xml is excluding html files during its copy > > from "src" to "build/src", so the package.html files are being > > omitted. To correct this, we need to either a) not exclude the > > html files in the copy, or b) use "src" as the root of the > > javadoc build instead of "build/src". My tentative solution uses > > option "b". There may be other options as well, but I won't > > investigate them unless we need to. We probably need more javadoc info in general. Much of the javadoc is dependant on the stability of the interfaces and classes. - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, email: [EMAIL PROTECTED]
RE: javadocs
FOP Committers: The attached patch contains my proposed changes to get the build for javadocs working. My message earlier today on this topic (included below) had the following errors in it: * With regard to item 1, Ant handles this platform difference automatically, so that proposed change has been removed. * With regard to item 2, Ant 1.4.1 appears to work correctly after all (when the other problems are fixed), so there is no need for a change there. My apologies for the confusion on the above items, caused by using the wrong compiler. With regard to item 4, Peter Kullmann pointed out a problem with option b, so I have implemented option a instead. The underlying problem was that lib/bin/antRun had DOS line endings in it (I am running on Linux 6.1), causing it to fail when used by javadoc from within Ant. This cannot be fixed from within the build.xml file using fixcrlf because the file is recreated, and (depending on umask) has not-executable file permissions. Also, you can't use Ant's chmod to fix the file permissions, because chmod itself relies on antRun to perform the chmod. I moved the logic that attempted to change antRun's permissions from build.xml to build.sh, and added code to strip out the offending end-of-line characters to build.sh as well. The remaining changes are related to items 3 and 4. I did not find or create a bug report for this problem. Perhaps I am the only one experiencing it? I noticed that code in the "dist-src" target has javadoc turned off. Perhaps with the attached fix, it can be turned back on again? javadoc reports numerous errors and warnings as it runs, but I believe those are separate issues. Please let me know if you have any questions. Victor Mote (mailto:[EMAIL PROTECTED]) Enterprise Outfitters (www.outfitr.com) 2025 Eddington Way Colorado Springs, Colorado 80916 Voice 719-622-0650, Fax 720-293-0044 > -Original Message- > From: Victor Mote [mailto:[EMAIL PROTECTED]] > Sent: Monday, July 29, 2002 5:54 AM > To: mailing list fop-dev > Subject: javadocs > > FOP Developers: > > In my continuing efforts to find a place to document things I > learn about FOP, I have wrestled with the build for javadocs. > Until making the following changes, that build failed (for me > anyway), unless I used Java 1.4. However, it is of some benefit > to use the same compiler for class and javadoc builds. The items > that follow are probably old news to most of you, and there may > be good reasons why we don't want to implement them, but here is > what I propose: > > 1. Java 1.2 javadoc cannot handle wildcards in the package names > (this feature was not added until 1.4). I have created a file > called /build-pkg-list.txt that contains a list of the > packages to be built. This file can be used as input to javadoc > either on the command line or from within Ant. There may be other > ways to implement this list within the build.xml file itself. If > there is strong feeling against using the external file, I'll > investigate them (I am unsure whether Ant ensures backwards > compatibility with older releases of java, or whether its > features are mapped to the later releases of java, effectively > ignoring newer features with older java environments). > 2. Ant 1.4.1 appears to have a bug that makes the package list > feature discussed in point 1 above fail. However, the bug is > fixed in the new 1.5 release. The 1.5 release change list > includes a fix for this bug (it is unclear from the release notes > when the bug arose). > > In addition, it would be helpful to have the overview.html and > package.html files included in the builds: > 3. It is trivial to add the "overview" attribute to build.xml to > handle the overview file. > 4. Right now, build.xml is excluding html files during its copy > from "src" to "build/src", so the package.html files are being > omitted. To correct this, we need to either a) not exclude the > html files in the copy, or b) use "src" as the root of the > javadoc build instead of "build/src". My tentative solution uses > option "b". There may be other options as well, but I won't > investigate them unless we need to. > > The big issues are 2 & 4, but please let me know if the others > cause problems as well. If the above proposal meets with general > approval, I'll submit a patch. > > Victor Mote (mailto:[EMAIL PROTECTED]) > Enterprise Outfitters (www.outfitr.com) > 2025 Eddington Way > Colorado Springs, Colorado 80916 > Voice 719-622-0650, Fax 720-293-0044 << File: ATT00039.txt >> <> - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, email: [EMAIL PROTECTED]
RE: javadocs
Sorry folks, it appears that I spoke too soon. My successful builds were being done using Java 1.4, not Java 1.2, which still fails, even with the new Ant. I'll work on it some more. Vic <> - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, email: [EMAIL PROTECTED]
