Date: Tue, 20 Aug 2002 05:49:34 -0400 From: Dylan Carlson <absinthe@pobox.com> To: freebsd-java@FreeBSD.ORG Subject: Update to docs (1.1), and some Q&A Message-ID: <200208200549.34990.absinthe@pobox.com>
next in thread | raw e-mail | index | archive | help
Hello, New version of the project docs have been posted. Comments welcome. [ http://home.earthlink.net/~dylancarlson/projects/freebsd/javadoc/ ] Many tweaks and fixes, new TOC, improved the FAQ, plus all things I have addressed below. REQUEST: I need anyone to feed me some open bugs (on a per-port basis) and suggest some FAQ items that regularly come up on the mailing list. What would be ideal is just to create PR's ... or just send me a quick email on the bugs you know about, and I'll create the PRs. Much lower priority are some application notes (esp. on things like JBuilder, Orion, Resin, etc) Bill, Ernst, Greg: Look for your <nametags> below for my answers on your earlier questions/comments. Everyone else can safely tune out the rest of this email. <Greg> 1. Team page will be started and updated with the comments fed from you and Bill (re: the "5.2/5.3" emails). Albeit I need to go back and redo the 17.2 section instead of just pasting in the THANKS file. Didn't have time to do a better job on that. 2. I have linked to Victoria Chan/Hiten Pandya's docs on setting up Tomcat in the Doc section. 3. Let me know what your thoughts are on the thread I am having with Calvin Varney about Java port install locations. </Greg> <Ernst> Let me know what your thoughts are on the thread I am having with Calvin Varney about Java port install locations. > 1) Is "News" more appropriate as a title than "Updates"? Yes, corrected. > 2) On the "Updates" page, the IBM JDK port is named "ibm-jdk13" while it > should be "linux-ibm-jdk13". Fixed. > 3) Section 2.1.3.2. ad 1: Why would someone recompile the kernel? What is > the advantage? Not sure myself. I took this from Nate's original notes in pkg-descr. But I have removed it. > 4) 2.1.3 The 1.1.8 JDK is a FreeBSD JDK, not a Sun JDK. %pkg_info |grep jdk-1.1.8 jdk-1.1.8 Sun's Java Developers Kit It's also got a Sun license in the install directory... > 5) 2.1.3.3 Will the JDK 1.1 port really be removed? It was intended as a support warning mostly -- Sun is EOL that API on the date listed, which is true. I have removed the statement about us dropping the port. > 6) 4.1.4 states that you need to download the JDK 1.1 documentation > manually, while it should be possible to provide MASTER_SITES for this > port, since you don't have to accept any license at > http://java.sun.com/products/jdk/1.1/docs.html so I've changed the port > accordingly... See my last commit. Fixed. > 7) 2.3.1: There are some issues with the Blackdown 1.4.1 JDK for Linux. It > has not been extensively tested. It segfaults when running simple > applications. Same applies to the Sun JDK 1.4 Noted and added into the Release Info for both. > 8) We should use one naming convention for JDK ports. At the moment the > convention is: > > JDK 1.1.8 for FreeBSD > Sun JDK 1.2.2 for Linux > Blackdown JDK 1.4.1 for Linux > > I know, however, that you prefer J2SDK or Java SDK over JDK. So what would > you suggest using as names? Perhaps J2SDK or Java 2 SE SDK or J2SE SDK? A > bit longish :-\ Sun's convention follows (from 1.2.x-1.4.x) "J2SE SDK". On 1.1.x it is "JDK". Blackdown it's all "JDK". My only effort is to make the vocabulary consist with Sun's, even if it is retarded. I have been using "SDK" but I will update to say J2SE SDK throughout to be clear about it. I'm not suggesting changing the port names. </Ernst> <Bill> > If you'd like for me to write up more extensive HotSpot build instructions > I'll do so. My notes are rather scattered, but I can summarize what I know > about each compiler, etc... and what it means in relation to each other. Absolutely. This would be good. Send me your rough notes and I will format them for you. Don't worry about layout or correctness, I will clean up where it's needed. I am also adding a section by which we can introduce experimental patches. But you'll probably need to make a tarball of them and host them somewhere. If not possible on FreeBSD.ORG's ftp servers, then maybe on Greg's site. > HotSpot and company (eventually alexey's 1.4) need to be promoted, but I > don't know when that's appropriate. We also need to publicize this project > so that what has been done is known and FreeBSD's Java abilities aren't > lost in the wash of daily BSD news. It's a significant enough project that > it deserves it's own track outside of FreeBSD mainly because of the > significance of Java and since our group encompasses all the open source > BSDs. This might be outside of the scope of what you're doing though. It probably should be an article on some platform-neutral website. Then I can place a hyperlink to it in our documentation, and it can be listed on the FreeBSD.ORG front page as well. It would be ideal to wait to publish such an article until we have our documentation up to date. It would be nice to reference our new site from that article and have it current. > My personal preference is to group those elements by version more so than > port (Linux emulation, native, etc...), so that I can make a decisions > about what to install *after* finding out which versions of the JVM are > available under various conditions. It's a more natural way of interacting > contextually with that information and would avoid additional navigation. A > chart would be a possibly be a good way of representing that so that it's > clearer, but is also rather confusing since it displays more information > than one would gather at a glance. I agree with you, and I have made those changes in the new version. > In that regard, (and the broadness of this group) I like the lay out of > Kees's page better than the standard FreeBSD's rather static web page look. > There's collapsable top level topics, tree lay out, that allows me to get > at the info very quickly of various ends of the technical spectrum. I like Kee's page too. Initially this is a substance-over-style effort. I'm concerned about supplying accurate and current content first; layout changes will have to be squeezed in when there is time left over. Other notes: 1. DocBook is the best source format for docs available currently; it simplifies writing and maintaining documentation because it separates the user from making layout decisions when creating content. This is a good thing. I expect the size to grow; the TOC/Book structure DocBook uses is extremely well-suited for large technical documents. 1.1. We can tweak the appearance of the HTML output by modifying the DSSSL stuff. It can be as fancy as we want it to be in concept, but that takes some work. The FDP provides some default templates which are used throughout the HandBook, FreeBSD articles and so on. While the appearance of these default HTML templates is spartan, yes, they are quite functional -- and moreover printable. 1.2. If we customize too much, we run the risk of making our documentation somewhat proprietary. I'd like anyone who knows DocBook to quickly pick this up and add content quickly. (which is the general goal of DocBook anyway) It is desireable to keep the HTML design basic, so that it looks consistent cross-browser, cross-platform... and is very printable. 1.3. Later on I/we can tweak the TOC to do collapseable branches, like on Kee's page. I don't see that happening for a little while. I don't know DSSSL, and until the content is mostly complete I'm not going to spend any time on layout. 2. DocBook makes it trivial to output structured documentation to other formats (PDF, RTF, TeX, etc), and the output looks uniform on all types. My next step once the content is 95% will be to make at least PDF format available from the index page, in the event that someone wants to print the whole site out, or large sections of it. Also, let me know what your thoughts are on the thread I am having with Calvin Varney about Java port install locations. </Bill> Cheers -- Dylan Carlson [absinthe@pobox.com] To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-java" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200208200549.34990.absinthe>