Re: Location of API docs
Marcus Better wrote: Matthias Klose wrote: Assuming that the doc is installed in /usr/share/doc/libfoo-java/api, a reference to a class Bar should point to ../../libbar-java/api. Not yet sure how to find the location for this reference I seem to remember that javadoc can be given a command line parameter giving the location of the javadocs for a certain Java package? I've hit a problem with the Javadoc generation - it seems I am falling over bug 379088[1]. This is a bug in gjdoc where hyperlinks are not generated correctly to methods in classpath-doc. (Sun's Javadoc will correctly generate these links). [1]http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=379088 Regards, Paul -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Re: Location of API docs
Hi, Mark Wielaard said: You can use the -link option to do this. It works very well with Sun's Javadoc, but I have not tried it with gjdoc. I can't remember the details, but it's integrated with ant's javadoc target. For Debian packages we need -linkoffline to link to the locally installed javadocs of dependant packages. I havent tried yet if one or both of these options work in gjdoc or not. They both work for gjdoc. so to summarize (and give my personal conclusion of) the discussion: one needs to give explicitly the location of the referred-to javadoc in ones call to ant, and it doesn't make any difference if it's under $package-doc/api or $package/api, so better respect the expectations of the Debian policy. No!? Eric -- You don't need to CC me on debian-java, debian-mentors and pkg-java-maintainers. Please CC me on other Debian lists. -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Re: Location of API docs
On Sun, 2007-01-14 at 01:12 +0100, Michael Koch wrote: On Sat, Jan 13, 2007 at 09:19:31PM +, Paul Cager wrote: Marcus Better wrote: Matthias Klose wrote: Assuming that the doc is installed in /usr/share/doc/libfoo-java/api, a reference to a class Bar should point to ../../libbar-java/api. Not yet sure how to find the location for this reference I seem to remember that javadoc can be given a command line parameter giving the location of the javadocs for a certain Java package? You can use the -link option to do this. It works very well with Sun's Javadoc, but I have not tried it with gjdoc. I can't remember the details, but it's integrated with ant's javadoc target. For Debian packages we need -linkoffline to link to the locally installed javadocs of dependant packages. I havent tried yet if one or both of these options work in gjdoc or not. They both work for gjdoc. Cheers, Mark signature.asc Description: This is a digitally signed message part
Re: Location of API docs
Michael Koch wrote: On Sat, Jan 13, 2007 at 09:19:31PM +, Paul Cager wrote: Marcus Better wrote: Matthias Klose wrote: Assuming that the doc is installed in /usr/share/doc/libfoo-java/api, a reference to a class Bar should point to ../../libbar-java/api. Not yet sure how to find the location for this reference I seem to remember that javadoc can be given a command line parameter giving the location of the javadocs for a certain Java package? You can use the -link option to do this. It works very well with Sun's Javadoc, but I have not tried it with gjdoc. I can't remember the details, but it's integrated with ant's javadoc target. Thanks for the reminder - I'll put this in for the BCEL and checkstyle packages. For Debian packages we need -linkoffline to link to the locally installed javadocs of dependant packages. I havent tried yet if one or both of these options work in gjdoc or not. Michael It's probably worth pointing out that -linkoffline still generates links to the *remote* site; it just uses the local documents during the generation of your javadocs. I use it at work, for example, where the internet is hidden behind a slow-ish proxy. I think either link or linkoffline would work, although linkoffline would require the linked-to packages to be build dependencies. In either case we would have to use a file:// URL link to our /usr/share/doc/*/api directories (should work, but I haven't tried it yet). Another question: Where th package uses a standard API (e.g. java.util.Map), should I link to http://java.sun.com/j2se/1.5.0/docs/api/ or what? -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Re: Location of API docs
On Sat, Jan 13, 2007 at 11:54:14PM +, Paul Cager wrote: Michael Koch wrote: On Sat, Jan 13, 2007 at 09:19:31PM +, Paul Cager wrote: Marcus Better wrote: Matthias Klose wrote: Assuming that the doc is installed in /usr/share/doc/libfoo-java/api, a reference to a class Bar should point to ../../libbar-java/api. Not yet sure how to find the location for this reference I seem to remember that javadoc can be given a command line parameter giving the location of the javadocs for a certain Java package? You can use the -link option to do this. It works very well with Sun's Javadoc, but I have not tried it with gjdoc. I can't remember the details, but it's integrated with ant's javadoc target. Thanks for the reminder - I'll put this in for the BCEL and checkstyle packages. For Debian packages we need -linkoffline to link to the locally installed javadocs of dependant packages. I havent tried yet if one or both of these options work in gjdoc or not. Michael It's probably worth pointing out that -linkoffline still generates links to the *remote* site; it just uses the local documents during the generation of your javadocs. I use it at work, for example, where the internet is hidden behind a slow-ish proxy. I think either link or linkoffline would work, although linkoffline would require the linked-to packages to be build dependencies. In either case we would have to use a file:// URL link to our /usr/share/doc/*/api directories (should work, but I haven't tried it yet). Another question: Where th package uses a standard API (e.g. java.util.Map), should I link to http://java.sun.com/j2se/1.5.0/docs/api/ or what? No, please depend on classpath-doc and use these. We dont wanna link to resources on the net. The idea is to have all on your hard disk when you install the *-doc packages. Michael -- .''`. | Michael Koch [EMAIL PROTECTED] : :' : | Free Java Developer http://www.classpath.org `. `' | `-| 1024D/BAC5 4B28 D436 95E6 F2E0 BD11 5923 A008 2763 483B -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Re: Location of API docs
On Sun, Jan 14, 2007 at 12:31:11AM +, Matthew Johnson wrote: Another question: Where th package uses a standard API (e.g. java.util.Map), should I link to http://java.sun.com/j2se/1.5.0/docs/api/ or what? No, please depend on classpath-doc and use these. We dont wanna link to resources on the net. The idea is to have all on your hard disk when you install the *-doc packages. These aren't quite equivalent. For packages in contrib which depend on the sun compiler, VM and classes they can't really depend on the classpath docs when they don't match the API you are actually using. Thats right currently. GNU classpath has merged its generics branch to HEAD lately. The next release will be 1.5 compatible/comparable. Then this will be a non-issue. There will always (?) be differences. If you find one please report to the GNU classpath project. Michael -- .''`. | Michael Koch [EMAIL PROTECTED] : :' : | Free Java Developer http://www.classpath.org `. `' | `-| 1024D/BAC5 4B28 D436 95E6 F2E0 BD11 5923 A008 2763 483B -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Re: Location of API docs
Another question: Where th package uses a standard API (e.g. java.util.Map), should I link to http://java.sun.com/j2se/1.5.0/docs/api/ or what? No, please depend on classpath-doc and use these. We dont wanna link to resources on the net. The idea is to have all on your hard disk when you install the *-doc packages. These aren't quite equivalent. For packages in contrib which depend on the sun compiler, VM and classes they can't really depend on the classpath docs when they don't match the API you are actually using. Matt -- Matthew Johnson http://www.matthew.ath.cx/ -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Re: Location of API docs
Matthias Klose wrote:
How come? I thought we put api docs in the -doc package, if there is
one.
exactly, but into the /usr/share/doc/$package/api directory, not into
the /usr/share/doc/$package-doc/api directory.
Oh, I wasn't aware of that. I've been doing it the other way around. But it
seems I'm not the only one, I have for example:
/usr/share/doc/ant-doc/javadocs
/usr/share/doc/classpath-doc/api
/usr/share/doc/libdom4j-java-doc/apidocs
/usr/share/doc/libxalan2-java-doc/api
Is it really better to put the docs in /usr/share/doc/$package? Note that
${package-doc} should not depend on $package, and installing only the -doc
package would still create both directories under /usr/share/doc.
Guess we should decide on some policy and start filing wishlist bugs.
Marcus
--
To UNSUBSCRIBE, email to [EMAIL PROTECTED]
with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Re: Location of API docs
Hi,
Marcus Better said:
Matthias Klose wrote:
How come? I thought we put api docs in the -doc package, if there is
one.
exactly, but into the /usr/share/doc/$package/api directory, not into
the /usr/share/doc/$package-doc/api directory.
[...]
Is it really better to put the docs in /usr/share/doc/$package? Note that
${package-doc} should not depend on $package, and installing only the -doc
package would still create both directories under /usr/share/doc.
I do second this comment: I don't understand the advantage to have the api
under /usr/share/doc/$package/api but I surely know that it's confusing if
it's part of $package-doc package, and keeps us from using dh_installdocs.
The Debian policy uses a lot of should in the Documentation section (12)
but 12.3 says /usr/share/doc/package may be a symbolic link to another
directory in /usr/share/doc only if the two packages both come from the
same source and the first package Depends on the second.. I translate
this into it's OK to share documentation if one package depends on the
other, i.e. $package-doc depends on $package, which is generally not the
case.
Eric
Guess we should decide on some policy and start filing wishlist bugs.
Let's see :-)
Marcus
--
You don't need to CC me on debian-java, debian-mentors and
pkg-java-maintainers.
Please CC me on other Debian lists.
--
To UNSUBSCRIBE, email to [EMAIL PROTECTED]
with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Re: Location of API docs
Hi Matthias, On Thu, 2007-01-11 at 21:11 +0100, Matthias Klose wrote: The idea was to make the -doc packages depend on other -doc packages so that references to other packages can be resolved; unfortunately gjdoc doesn't support that yet. What would you need from gjdoc to support 'that'? Could you give an example, I am afraid I was unable to follow the discussion to see what is really needed here. Thanks, Mark signature.asc Description: This is a digitally signed message part
Re: Location of API docs
Paul Cager wrote: which seems more sensible to me. Should I change it to /usr/share/doc/$package/api? I assume I should also create a doc-base. Yes, sounds reasonable. The draft policy [1] suggests /usr/share/doc/package/api. Check this thread [2] about how to write the doc-base file. Marcus [1] http://wiki.debian.org/Java/Draft [2] http://lists.debian.org/debian-java/2006/03/msg00031.html -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Re: Location of API docs
Paul Cager writes: I am updating the BCEL library to the new upstream version. The old version installed the Javadocs into: /usr/share/doc/$package/doc/api Daniel Baumann queried this last night on IRC, and it seems that other (newer) packages (e.g. libxalan2-java-doc) install into /usr/share/doc/$package/api which seems more sensible to me. Should I change it to /usr/share/doc/$package/api? I assume I should also create a doc-base. Any comments? where $package is the name of the library package, not the name of the doc package (if there exists an extra -doc package). The idea was to make the -doc packages depend on other -doc packages so that references to other packages can be resolved; unfortunately gjdoc doesn't support that yet. Matthias -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Location of API docs
I am updating the BCEL library to the new upstream version. The old version installed the Javadocs into: /usr/share/doc/$package/doc/api Daniel Baumann queried this last night on IRC, and it seems that other (newer) packages (e.g. libxalan2-java-doc) install into /usr/share/doc/$package/api which seems more sensible to me. Should I change it to /usr/share/doc/$package/api? I assume I should also create a doc-base. Any comments? Thanks, Paul -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
