Please review: new Java Project docs

Please review: new Java Project docs

Post by Dylan Carls » Sun, 18 Aug 2002 23:00:10



Hello,

I have finished a 1st-pass at rewriting the FreeBSD Java Project documentation
into DocBook/SGML source format.  I have transformed the preview version into
HTML.   I would like volunteers to do basic fact-checking and give me their
opinions on where the docs can use improvement.

Specifically, contributions are needed in the following areas, in order of
importance:

1.  Adding items to the FAQ (I know I missed some).

2.  Filling out the "Known Issues" portion of the Release Info sections ... I
know there are open issues currently.

3.  Authors for the following articles:
        3a.  Basics of setting up a Java environment
        3b.  Basics of running and troubleshooting Java applications
        3c.  Benchmarks (ones that we can legally publish)

4.  Artists needed for a logo and other decorations.  Primarily, it would be
nice to have a Project logo for the index page.   Probably nothing bigger
than 300 x 300, royalty-free.  Vector graphics need to be in EPS format, and
bitmaps in PNG.

[ http://home.earthlink.net/~dylancarlson/projects/freebsd/javadoc/ ]

Looking forward to your feedback.   Cheers,
--


with "unsubscribe freebsd-java" in the body of the message

 
 
 

Please review: new Java Project docs

Post by Calvin Varn » Tue, 20 Aug 2002 08:36:58


Although you haven't asked for feedback on the documentation section
I'd like to comment on "4.4. Proposal for Porting Java Applications
and Tools"

1. If JAVALIBNAME is defined as ${PORTNAME}-${PORTVERSION} a symlink
   for ${PORTNAME} would be useful for managing dependencies.

2. Why should Javadocs be treated differently from ordinary
   documentation and placed anywhere other than ${DOCSDIR}? Javadocs
   are just another form of documentation and should be excluded when
   installing ports with NOPORTDOCS.

3. Regarding placing all library JAR files are in
   ${JAVAPREFIX}/classes/${JAVALIBNAME}/

   a. Everything java involves classes. As this is a directory for
      just library classes would "lib" or "import" be a more
      appropriate directory name?

   b. Placing each library jar under its own ${JAVALIBNAME} directory
      will create many subdirectories with just one jar file (or few
      if different versions are installed). I'd suggest just placing
      them in ${JAVAPREFIX}/classes (or lib or import...). If a
      library includes more than one class file and isn't packaged
      within a jar a ${JAVALIBNAME} subdirectory could be appropriate
      or they could be jared during installation.

   c. Is there a need for ${JAVAPREFIX} at all? Why not install
      libraries in ${PREFIX}/share/javalib or
      ${PREFIX}/share/javaimport.

      I'm not sure of the intentions behind the additional java in the
      ${PREFIX}/share/java/classes hierarchy. I don't think
      ${PREFIX}/share/java is the right place for docs or examples and
      applications should reside in ${PREFIX}/share or ${PREFIX}. Are
      any other ports installed under a subdirectory denoting their
      implementation language?

4. Is there a need to break away from the existing standard of placing
   examples in ${EXAMPLESDIR} (default:
   ${PREFIX}/share/examples/${PORTNAME})?

Just my thoughts.

--
Calvin Varney


with "unsubscribe freebsd-java" in the body of the message

 
 
 

Please review: new Java Project docs

Post by Dylan Carls » Tue, 20 Aug 2002 18:08:46



Quote:> Although you haven't asked for feedback on the documentation section
> I'd like to comment on "4.4. Proposal for Porting Java Applications
> and Tools"

This is great, thank you.

Quote:

> 1. If JAVALIBNAME is defined as ${PORTNAME}-${PORTVERSION} a symlink
>    for ${PORTNAME} would be useful for managing dependencies.

I think that should be up to the user to decide which version they want to use
(if they have more than one installed).   Either way, that still doesn't mean
anything if $CLASSPATH isn't set correctly.  

I don't think we should make any assumptions about which versions should be
symlinked.

Quote:

> 2. Why should Javadocs be treated differently from ordinary
>    documentation and placed anywhere other than ${DOCSDIR}? Javadocs
>    are just another form of documentation and should be excluded when
>    installing ports with NOPORTDOCS.

My opinion on this for what it's worth:

The API docs should be bundled with the rest of the JDK/SDK.  I like it when
the JDK is one tree of binaries and docs.  

Everything else should be in $DOCSDIR, though.

Agree with you on NOPORTDOCS.  However the API docs, like the SDK source code,
have to be manually fetched.  Until we have distributables, they probably
should remain as separate ports (jdk13-doc, etc).   I'm not sure our license
covers API doc redistribution anyway, so that may never happen.

Quote:

> 3. Regarding placing all library JAR files are in
>    ${JAVAPREFIX}/classes/${JAVALIBNAME}/

>    a. Everything java involves classes. As this is a directory for
>       just library classes would "lib" or "import" be a more
>       appropriate directory name?

Not sure how this is relevant.

I wouldn't be opposed to changing ${JAVAPREFIX} to ${PREFIX}/lib/java.
Perl, PHP, Python, Ruby all do it this way, basically.

They like us do not want to mix up C libs with Java libs.  Segregating that
stuff is a good idea.

Quote:

>    b. Placing each library jar under its own ${JAVALIBNAME} directory
>       will create many subdirectories with just one jar file (or few
>       if different versions are installed). I'd suggest just placing
>       them in ${JAVAPREFIX}/classes (or lib or import...). If a
>       library includes more than one class file and isn't packaged
>       within a jar a ${JAVALIBNAME} subdirectory could be appropriate
>       or they could be jared during installation.

Agree with your first sentence.   Second is sketchy (see above).

Agree with third, and I'd like to suggest that the proposal gets amended to
require that libraries with multiple classes get built into a JAR file at
install time.  That's a good idea, because we can do a lot more with
versioning if all the classes are wrapped up in a JAR.  I'm not sure that any
of the Makefiles do JAR version checking but if not we should probably work
in that direction.

Ernst?

Quote:

>    c. Is there a need for ${JAVAPREFIX} at all? Why not install
>       libraries in ${PREFIX}/share/javalib or
>       ${PREFIX}/share/javaimport.

I think it is.  It's cleaner to know where all of your java libraries are,
instead of having them mixed up with all the C libraries.  Perl operates on
this same basis.  I don't want to look at a directory and try to figure out
what is a set of c libs, and what is Java.  ${JAVAPREFIX} solves that.  

Quote:

>       I'm not sure of the intentions behind the additional java in the
>       ${PREFIX}/share/java/classes hierarchy. I don't think
>       ${PREFIX}/share/java is the right place for docs or examples and
>       applications should reside in ${PREFIX}/share or ${PREFIX}. Are
>       any other ports installed under a subdirectory denoting their
>       implementation language?

Perl:   /usr/local/lib/perl5/%interpreter-version%/
PHP:  /usr/local/lib/php/
Python:  /usr/local/lib/python%ver%/
Ruby:  /usr/local/lib/ruby/%interpreter-version%/
...etc...

Quote:

> 4. Is there a need to break away from the existing standard of placing
>    examples in ${EXAMPLESDIR} (default:
>    ${PREFIX}/share/examples/${PORTNAME})?

Nope, no need.  I basically agree with you.  Some other languages actually do
it this way:  ${PREFIX}/share/exmaples/%lang%/${PORTNAME}

I would suggest:  
${PREFIX}/share/examples/java-${JAVAAPIVERSION}/${PORTNAME}

e.g., /usr/local/share/examples/java13/jakarta-oro/

...

I'd like a few of the committers here (Ernst, Greg primarily) to weigh in on
these ideas before I amend the existing proposal.   Most of your comments are
agreeable, though, thank you -- if only a few tweaks are (in my opinion)
necessary to mimic how other languages handle their ports.

Cheers,
--


with "unsubscribe freebsd-java" in the body of the message

 
 
 

Please review: new Java Project docs

Post by Ernst de Ha » Tue, 20 Aug 2002 20:02:30


Hi Dylan,

Some comments:

1) Is "News" more appropriate as a title than "Updates" ?
2) On the "Updates" page, the IBM JDK port is named "ibm-jdk13" while it
should be "linux-ibm-jdk13".
3) Section 2.1.3.2. ad 1: Why would someone recompile the kernel? What is
the advantage?
4) 2.1.3 The 1.1.8 JDK is a FreeBSD JDK, not a Sun JDK.
5) 2.1.3.3 Will the JDK 1.1 port really be removed? I don't think so, since
it is really used quite a lot still... Nate?
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.
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

I will review the rest later if I have time.

Ernst


Quote:> Hello,

> I have finished a 1st-pass at rewriting the FreeBSD Java Project
> documentation into DocBook/SGML source format.  I have transformed the
> preview version into HTML.   I would like volunteers to do basic
> fact-checking and give me their opinions on where the docs can use
> improvement.

> Specifically, contributions are needed in the following areas, in order
> of importance:

> 1.  Adding items to the FAQ (I know I missed some).

> 2.  Filling out the "Known Issues" portion of the Release Info sections
> ... I know there are open issues currently.

> 3.  Authors for the following articles:
>    3a.  Basics of setting up a Java environment
>    3b.  Basics of running and troubleshooting Java applications
>    3c.  Benchmarks (ones that we can legally publish)

> 4.  Artists needed for a logo and other decorations.  Primarily, it would
> be nice to have a Project logo for the index page.   Probably nothing
> bigger than 300 x 300, royalty-free.  Vector graphics need to be in EPS
> format, and bitmaps in PNG.

> [ http://home.earthlink.net/~dylancarlson/projects/freebsd/javadoc/ ]

> Looking forward to your feedback.   Cheers,

--
Ernst de Haan
EuroNet Internet B.V.

    "Come to me all who are weary and burdened
        and I will give you rest" -- Jesus Christ


with "unsubscribe freebsd-java" in the body of the message

 
 
 

Please review: new Java Project docs

Post by Ernst de Ha » Tue, 20 Aug 2002 21:22:31


Dylan,

One more sug/question:

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 :-\

Ernst


Quote:> Hello,

> I have finished a 1st-pass at rewriting the FreeBSD Java Project
> documentation into DocBook/SGML source format.  I have transformed the
> preview version into HTML.   I would like volunteers to do basic
> fact-checking and give me their opinions on where the docs can use
> improvement.

> Specifically, contributions are needed in the following areas, in order
> of importance:

> 1.  Adding items to the FAQ (I know I missed some).

> 2.  Filling out the "Known Issues" portion of the Release Info sections
> ... I know there are open issues currently.

> 3.  Authors for the following articles:
>    3a.  Basics of setting up a Java environment
>    3b.  Basics of running and troubleshooting Java applications
>    3c.  Benchmarks (ones that we can legally publish)

> 4.  Artists needed for a logo and other decorations.  Primarily, it would
> be nice to have a Project logo for the index page.   Probably nothing
> bigger than 300 x 300, royalty-free.  Vector graphics need to be in EPS
> format, and bitmaps in PNG.

> [ http://home.earthlink.net/~dylancarlson/projects/freebsd/javadoc/ ]

> Looking forward to your feedback.   Cheers,

--
Ernst de Haan
EuroNet Internet B.V.

    "Come to me all who are weary and burdened
        and I will give you rest" -- Jesus Christ


with "unsubscribe freebsd-java" in the body of the message

 
 
 

Please review: new Java Project docs

Post by Calvin Varn » Thu, 22 Aug 2002 09:28:28


Dylan Carlson <absin...@pobox.com> writes:
> On Sunday 18 August 2002 07:05pm, Calvin Varney wrote:
>> Although you haven't asked for feedback on the documentation section
>> I'd like to comment on "4.4. Proposal for Porting Java Applications
>> and Tools"

> This is great, thank you.

>> 1. If JAVALIBNAME is defined as ${PORTNAME}-${PORTVERSION} a symlink
>>    for ${PORTNAME} would be useful for managing dependencies.

> I think that should be up to the user to decide which version they want to use
> (if they have more than one installed).   Either way, that still doesn't mean
> anything if $CLASSPATH isn't set correctly.  

I agree in that the user/porter *may* wish to specify a particular
library version. The majority of time I imagine they would only want
to specify the major part of the version.

When suggesting symlinks I was thinking about the situation when a
minor update is made to a library, the minor part of ${PORTVERSION}
is increased and all ports that build a classpath by statically
specifying ${PORTNAME}-${PORTVERSION}'s would break.

Maybe this situation could be handled by dynamically building
classpaths, I don't know, would like to here other peoples
experiences/opinions.

> I don't think we should make any assumptions about which versions should be
> symlinked.

I would have thought the latest minor version of a library
libname.majorver.minorver linked to libname.majorver Thats assuming
library interfaces don't change between minor versions. (how safe is
that?)

>> 2. Why should Javadocs be treated differently from ordinary
>>    documentation and placed anywhere other than ${DOCSDIR}? Javadocs
>>    are just another form of documentation and should be excluded when
>>    installing ports with NOPORTDOCS.

> My opinion on this for what it's worth:

> The API docs should be bundled with the rest of the JDK/SDK.  I like it when
> the JDK is one tree of binaries and docs.  

> Everything else should be in $DOCSDIR, though.

> Agree with you on NOPORTDOCS.  However the API docs, like the SDK source code,
> have to be manually fetched.  Until we have distributables, they probably
> should remain as separate ports (jdk13-doc, etc).   I'm not sure our license
> covers API doc redistribution anyway, so that may never happen.

Ok, the SDK API docs must remain a separate port. I was concerned
about the API documentation produced by javadoc for other ports
(libraries and applications) ending up somewhere other than $DOCSDIR.

>> 3. Regarding placing all library JAR files are in
>>    ${JAVAPREFIX}/classes/${JAVALIBNAME}/

>>    a. Everything java involves classes. As this is a directory for
>>       just library classes would "lib" or "import" be a more
>>       appropriate directory name?

> Not sure how this is relevant.

I'm just being pedantic. I'd suggest placing java libraries in a
directory with a name that more accurately describes its
contents. "classes" could mean application classes or library classes,
"lib" is slightly more accurate.

> I wouldn't be opposed to changing ${JAVAPREFIX} to ${PREFIX}/lib/java.
> Perl, PHP, Python, Ruby all do it this way, basically.

Great, for consistency ${PREFIX}/lib/java has my vote. Interesting to
note the likes of perl and php libraries aren't located under
${PREFIX}/share as architecture-independent files though.

- Show quoted text -

> They like us do not want to mix up C libs with Java libs.  Segregating that
> stuff is a good idea.

>>    b. Placing each library jar under its own ${JAVALIBNAME} directory
>>       will create many subdirectories with just one jar file (or few
>>       if different versions are installed). I'd suggest just placing
>>       them in ${JAVAPREFIX}/classes (or lib or import...). If a
>>       library includes more than one class file and isn't packaged
>>       within a jar a ${JAVALIBNAME} subdirectory could be appropriate
>>       or they could be jared during installation.

> Agree with your first sentence.   Second is sketchy (see above).

> Agree with third, and I'd like to suggest that the proposal gets amended to
> require that libraries with multiple classes get built into a JAR file at
> install time.  That's a good idea, because we can do a lot more with
> versioning if all the classes are wrapped up in a JAR.  I'm not sure that any
> of the Makefiles do JAR version checking but if not we should probably work
> in that direction.

I'd support this.

> Ernst?

>>    c. Is there a need for ${JAVAPREFIX} at all? Why not install
>>       libraries in ${PREFIX}/share/javalib or
>>       ${PREFIX}/share/javaimport.

> I think it is.  It's cleaner to know where all of your java libraries are,
> instead of having them mixed up with all the C libraries.  Perl operates on
> this same basis.  I don't want to look at a directory and try to figure out
> what is a set of c libs, and what is Java.  ${JAVAPREFIX} solves that.  

I wasn't clear here, I was questioning the need for a directory
${PREFIX}/share/java. Other than the proposed classes subdirectory
for libraries what else should be located here? If nothing else why
not place libraries in ${PREFIX}/share/javalib rather than
${PREFIX}/share/java/classes. (still prefer ${PREFIX}/lib/java
discussed above though)

Definitely agree java libs should be in their own directory.

>>       I'm not sure of the intentions behind the additional java in the
>>       ${PREFIX}/share/java/classes hierarchy. I don't think
>>       ${PREFIX}/share/java is the right place for docs or examples and
>>       applications should reside in ${PREFIX}/share or ${PREFIX}. Are
>>       any other ports installed under a subdirectory denoting their
>>       implementation language?

> Perl:   /usr/local/lib/perl5/%interpreter-version%/
> PHP:  /usr/local/lib/php/
> Python:  /usr/local/lib/python%ver%/
> Ruby:  /usr/local/lib/ruby/%interpreter-version%/
> ...etc...

As above, was trying to determine the need for the proposed
${JAVAPREFIX}. Java libraries should have their own directory but
should the applications that use these libraries be placed under
${JAVAPREFIX} or be placed directly under ${PREFIX} or
${PREFIX}/share. I don't see a need to group application files under a
directory denoting the language they were implemented in.

>> 4. Is there a need to break away from the existing standard of placing
>>    examples in ${EXAMPLESDIR} (default:
>>    ${PREFIX}/share/examples/${PORTNAME})?

> Nope, no need.  I basically agree with you.  Some other languages actually do
> it this way:  ${PREFIX}/share/exmaples/%lang%/${PORTNAME}

This sounds good.

> I would suggest:  
> ${PREFIX}/share/examples/java-${JAVAAPIVERSION}/${PORTNAME}

> e.g., /usr/local/share/examples/java13/jakarta-oro/

Don't like this as many ports specify java x.y or later.

> ...

> I'd like a few of the committers here (Ernst, Greg primarily) to weigh in on
> these ideas before I amend the existing proposal.   Most of your comments are
> agreeable, though, thank you -- if only a few tweaks are (in my opinion)
> necessary to mimic how other languages handle their ports.

Would also like to here form those with more porting experience. I've
just started trying to port a couple of java apps and have found it
tough going trying to nut out what goes where and how to handle common
libraries.

In addition to the handling of java library versions, the location of
java libraries, application files, examples and documentation
discussed here I also think locations for configuration files and
application log files need to be covered. If java ports are brought in
line with other ports hopefully little will need to be said, just a
reference to hier(7) and the likes of
http://www.freebsd.org/doc/en_US.ISO8859-1/books/porters-handbook/x30...

--
Calvin Varney

To Unsubscribe: send mail to majord...@FreeBSD.org
with "unsubscribe freebsd-java" in the body of the message