Documentation proposal

[Herve Quiroz]

Manfred,

On Thu, Apr 01, 2004 at 08:45:22PM +0200, Manfred Riem wrote:
> Hi there,
> 
> I want to try to make the Java documentation on the FreeBSD website
> a bit more usable. Currently the bits are a bit scattered around.

That's a good thing. I just posted a message to this list (in the Tomcat
thread IIRC) regarding my plan of filling the Java section of the
porter's handbook.

>  - Removing "Creating Ports" as currently not a real standard has
>    been set. Follow up on the discussion recently held on the 
>    mailinglist.

Actually, the first two points are now "official" because some macros
are provided by bsd.java.mk: The JAVAJARDIR macro is the location for
the JAR files from Java libraries, and JAVASHAREDIR is the prefix for
Java applications. Many ports do not use them yet, probably because
their maintainer don't know (yet) about them. That's another good reason
to update the Java documentation.

However, in practice, the third point is not official. Most of the Java
ports I know of use directly DOCSDIR as for any other (non-Java) port.
IMHO, this approach (DOCSDIR) is the correct one.

I think the best place to explain Java porter's practice is the Java
section of the porter's handbook. As I said above, I will try to fill it
as soon as bsd.java.mk 2.0 is commited (so information is up-to-date).

Ernst has already written a quite complete manual for porting Java
applications/libraries with bsd.java.mk 1.0 and I have built (based on
Ernst's work) a similar documentation regarding bsd.java.mk 2.0. So
putting it in the porter's handbook won't be too complex.

FYI:

- Ernst's web page (he is maintaining bsd.java.mk):
http://people.freebsd.org/~znerd/

Unfortunately, some of the documentation is not up-to-date... and some
other is on www.metaverse.nl which seems to be offline for the moment.

- Documentation about bsd.java.mk 2.0:
http://www.esil.univ-mrs.fr/~hquiroz/freebsd/bsd.java.mk-2.0.html

(Not relevant for now, but will be the reference documentation when
version 2.0 is commited)

If you want, I will handle everything that is related to Java porting as
you will already have a lot of work with the remaining points ;)

>  - A more clear definition for newbies on how to install Java from
>    the sources (eg. tell them about the linux bootstrap).

That would be nice. Having the most common issues resolved on a web page
is better for end-users. Indeed they won't have to subscribe to the list
to get a simple, common problem solved.

Herve


PS: hum... I realize that I reply to the freebsd-doc list, to which I am
not even registered. Please forgive me for this bad practice. It's for
the good cause, and I will subscribe to it probably in the near future
anyway ;)