Major changes to the policy and wrote simple publish script.

1 files changed, 275 insertions, 204 deletions

diff --git a/policy.xml b/policy.xml
index 17edfe0..b3daf5b 100644
--- a/policy.xml
+++ b/policy.xml
@@ -4,7 +4,11 @@
 <!ENTITY must "<emphasis>must</emphasis>">
 <!ENTITY may "<emphasis>may</emphasis>">
 <!ENTITY should "<emphasis>should</emphasis>">
-<!ENTITY repository "<filename>/usr/share/java/repository</filename>">
+<!ENTITY jvm "<emphasis>java-virtual-machine</emphasis>">
+<!ENTITY j1r "<emphasis>java1-runtime</emphasis>">
+<!ENTITY j2r "<emphasis>java2-runtime</emphasis>">
+<!ENTITY jc "<emphasis>java-compiler</emphasis>">
+<!ENTITY j2c "<emphasis>java2-compiler</emphasis>">
 ]>
 
 <!-- I need a good way to add a <package> tag for names of the Debian
@@ -14,212 +18,279 @@
   <title>PROPOSED Debian policy for Java</title>
   <artheader>
     <author>
-      <surname>Bortzmeyer</surname>
-      <firstname>Stephane</firstname>
+      <surname>Lundqvist</surname>
+      <firstname>Ola</firstname>
       <authorblurb>
-	<para><email>bortzmeyer@debian.org</email></para>
+	<para><email>opal@debian.org</email></para>
       </authorblurb>
     </author>
-    <edition>Version 0.3, 12 July 2000</edition>
-    <!-- $Id$ -->
+    <edition>$Revision:$ $Date:$</edition>
+    <!-- $Id:$ -->
   </artheader>
-
-<section id="policy-bg"><title>Background and metainfo</title>
-
-<para>An important warning: this text is
-a <emphasis>proposal</emphasis>. I put it here, publically, so it can be read,
-discussed, implemented, ignored, etc.  It has no sort of endorsement
-from any authority in Debian or elsewhere.</para>
-
-<para>Feel free to report me (Stephane Bortzmeyer
-<email>bortzmeyer@debian.org</email>) comments and disagrements. I'll
-put them on this text, if you don't object.</para>
-
-<para>There are several "subpolicies" in Debian. They all want to make
-the <ulink url="http://www.debian.org/doc/debian-policy/">Debian
-Policy</ulink> more precise when it comes to a specific subject. See
-the Emacs subpolicy in package emacsen-common for instance.  As far as
-I know, the only subpolicy for a programming language, is that of
-<ulink url="http://non-us.debian.org/~hertzog/perl-policy.html/">Perl</ulink>.
-</para>
-
-<para>This policy is intended to be in a package java-common, whose maintainer 
-will be Java Debian <email>debian-java@lists.debian.org</email>.</para>
-
-</section>
-
-<section id="policy-actual"><title>The policy</title>
-
-<para>A package java-common is created, containing this policy.</para>
-
-<para>Two virtual packages are created, java-compiler and 
-java-virtual-machine.</para>
-
-<para>Java compilers &must; provide java-compiler and depends on
-java-common.  They &should; use <filename>/etc/alternatives</filename>
-for the name 'javac' if they are more or less command-line compatible
-with Sun's JDK javac. They &should; have a CLASSPATH predefined which
-includes &repository;.</para>
-
-<para>Java virtual machines &must; provide java-virtual-machine and
-depends on java-common and use <filename>/etc/alternatives</filename>
-for the name 'java'. They &should; have a CLASSPATH predefined which
-includes &repository;.</para>
-
-<para>The problem of Java core classes is put on hold. In the mean time, Java
-virtual machines are requested to come with their own core classes. (Or to depends 
-on another VM, like jikes does.)</para>
-
-<para>If a given source (like the JDK does) brings both a compiler and a
-virtual machine, you MAY name the compiler package xxxx-dev.</para>
-
-<para>Packages written in Java are separated in two categories: programs and
-libraries. Programs are intended to be run by end-users. Libraries are
-intended to help programs to run and to be used by developers. 
-Both &must; depend on java-virtual-machine. </para>
-
-<para>Both are shipped as Java bytecode (<filename>*.class</filename> files, may
-be packaged in a <filename>*.jar</filename> archive) and with an 
-"Architecture: all" since Java bytecode is supposed to be portable.</para>
-
-<para>Programs must have executable(s) in
-<filename>/usr/bin</filename> and be executable. They can be Java
-classes (using binfmt_java, in Debian &lt;= 2.1 or binfmt_misc, in
-Debian &gt; 2.1) or wrappers. In any case, they &must; run without
-specific environment variables (see <ulink
-url="http://www.debian.org/doc/debian-policy/ch3.html#s3.8">Policy
-3.8</ulink>), for instance CLASSPATH. They must respect the Policy
-rules for executables (for instance a manual page per executable, see
-<ulink
-url="http://www.debian.org/doc/debian-policy/ch6.html#s6.1">Policy
-6.1</ulink>). If they have their own auxiliary classes, they MUST be
-either in a <filename>.jar</filename> in
-<filename>/usr/share/java/PACKAGE-NAME.jar</filename> or use
-the General Java Repository described below. Programs &must; depend on
-java-virtual-machine.</para>
-
-<para>Libraries are not separated between developers (-dev) and users
-versions, since it is meaningless in Java. Their classes MUST be either:</para>
-
-<itemizedlist>
-<listitem><para>in a <filename>.jar</filename> archive 
-	  in <filename>/usr/share/java/PACKAGE-NAME.jar</filename></para>
+  
+  <section id="policy-bg">
+    <title>Background</title>
+    
+    <para>An important warning: this text is
+      a <emphasis>proposal</emphasis>. I put it here, publically, so it can be
+      read, discussed, implemented, ignored, etc.  It has no sort of
+      endorsement from any authority in Debian or elsewhere.</para>
+    
+    <para>Feel free to report me (Ola Lundqvist
+      <email>opal@debian.org</email>) comments and disagrements. I'll
+      put them on this text and forward them to
+      <email>debian-java@lists.debian.org</email>, if you don't object.
+    </para>
+    
+    <para>There are several "subpolicies" in Debian. They all want to make the
+      <ulink url="http://www.debian.org/doc/debian-policy/">Debian Policy</ulink>
+      more precise when it comes to a specific subject. See
+      the Emacs subpolicy in package emacsen-common for instance.  As far as
+      I know, the only subpolicy for a programming language, is that of
+      <ulink url="http://non-us.debian.org/~hertzog/perl-policy.html/">Perl</ulink>.
+    </para>
+    
+    <para>This policy is intended to be in a package java-common, whose
+      maintainer will be Java Debian
+      <email>debian-java@lists.debian.org</email>, when the policy have been
+      officially accepted.
+    </para>
+    
+  </section>
+  
+  <section id="policy-introduction">
+    <title>Introduction</title>
+    
+    <para>A package java-common is created, containing this policy and
+      some basic tools.</para>
+    
+    <para>Virtual packages are created: &jc;, &j2c;,
+      &jvm;, &j1r; and &j2r;.</para>
+    
+    <para>Packages written in Java are separated in two categories: programs
+      and libraries. Programs are intended to be run by end-users. Libraries
+      are intended to help programs to run and to be used by developers. 
+      Both &must; depend on &jvm;.
+    </para>
+    
+    <para>Both are shipped as Java bytecode (<filename>*.class</filename>
+      files, packaged in a <filename>*.jar</filename> archive) and with
+      an "Architecture: all" since Java bytecode is supposed to be portable.
+    </para>
+    
+    <para>This policy does not address the issue of documentation (for instance
+      HTML pages made with javadoc).</para>
+
+  </section>
+  
+  <section id="policy-vm">
+    <title>Virtual machines</title>
+
+    <para>Java virtual machines &must; provide &jvm; and
+      depend on java-common. They can also provide the runtime environment that
+the package contains (&j1r; and/or &j2r;). If it does not
+      provide the files itself it &must; depend on the needed runtime
+      environment.
+    </para>
+    <para>I &should; use <filename>/etc/alternatives</filename>
+      for the name 'java' if they are command-line compatible with the
+      Sun's java program.
+    </para>
+    <para>They &should; have a CLASSPATH predefined which include the needed
+      runtime environment.
+    </para>
+    
+    <para>If a given source (like the JDK does) brings both a compiler and a
+      virtual machine, you &may; name the compiler package xxxx-dev.
+    </para>
+
+  </section>
+
+  <section id="policy-compiler">
+    <title>Java compilers</title>
+    
+    <para>Java compilers &must; provide &jc; and/or &j2c; and depend on
+      java-common. They &must; also depend on the needed runtime environemnt
+      (&j1r and/or &j2r;).
+      </para>
+
+    <para>They &should; use <filename>/etc/alternatives</filename>
+      for the name 'javac' if they are command-line compatible
+      with Sun's JDK javac. They &should; have a CLASSPATH predefined to
+      include the java core classes need for the compiler.</para>
+
+  </section>
+
+  <section id="policy-programs">
+    <title>Java programs</title>
+
+    <para>Programs &must; have executable(s) in
+      <filename>/usr/bin</filename> and be executable. They can be Java
+      classes (using binfmt_misc) or wrappers. In any case, they &must; run
+      without specific environment variables (see
+      <ulink url="http://www.debian.org/doc/debian-policy/ch3.html#s3.8">Policy
+	3.8</ulink>), for instance CLASSPATH. They &must; respect the Policy
+      rules for executables (for instance a manual page per executable, see
+      <ulink url="http://www.debian.org/doc/debian-policy/ch6.html#s6.1">
+	Policy 6.1</ulink>).
+    </para>
+    <para>If they have their own auxiliary classes, they
+      &must; be in a jar file in <filename>/usr/share/java</filename>. The name
+      of the jar &should; folow the same naming conventions as for libraries.
+    </para>
+    <para>Programs &must; depend on &jvm; and the needed
+      runtime environment (&j1r; and/or &j2r;).
+    </para>
+    <para>There is no naming rules for programs, they are ordinary programs,
+      from the user point of view.
+    </para>
+  </section>
+
+  <section id="policy-libraries">
+    <title>Java libraries</title>
+
+    <para>Libraries are not separated between developers (-dev) and users
+      versions, since it is meaningless in Java.
+    </para>
+
+    <para>Java libraries packages &must; be named libXXX[version]-java
+      (without the brackets), where the version part is optional and &should;
+      only contain the necessary part. The version part &should; only be
+      used to avoid naming colisions. The XXX part is the actual package
+      name used in the text below.
+    </para>
+
+    <para>Their classes &must; be in <filename>jar</filename> archive(s) in
+      the directory <filename>/usr/share/java</filename>,
+      with the name
+      <filename>packagename[-extraname]-fullversion.jar</filename>.
+      The extraname is optional and used internaly within the package to
+      separate the different
+      jars provided by the package. The fullversion is the version of that
+      jar file. In some cases that is not the same as the package version.
+    </para>
+    <para>Some package &must; also provide a symbolic link from
+      <filename>packagename-extraname.jar</filename> to the most compatible
+      version of the available
+      <filename>packagename-extraname-version.jar</filename> files.
+    </para>
+
+    <para>All jar files &must; have a well-documented CLASSPATH, so 
+      that developers should know what to add to their wrappers.
+    </para>
+    
+    <para>This applies only to libraries, <emphasis>not</emphasis> to the core
+      classes provied by a the runtime environment.
+    </para>
+    
+  </section>
+
+  <section id="policy-politics">
+    <title>Main, contrib or non-free</title>
+    <para>About politics: packaging Java stuff changes nothing to the
+      rules Debian uses to find if a program is free or not. Since there are
+      not many free Java tools, keep in mind the following:</para>
+    
+    <itemizedlist>
+      
+      <listitem><para>If your source package can compile (correctly) only
+	  with non-free tools (the only free Java compilers seem to be guavac,
+	  gcj and jikes, it cannot go to main. If your package itself is free,
+	  it &must; go to contrib.
+	</para></listitem>
+      
+      <listitem><para>If your binary package can run only with non-free
+	  virtual machines (the only free Java virtual machine seems to be
+	  kaffe - and the one included in libgcj), it cannot go to main. If
+	  your package itself is free, it &must; go to contrib.
+	</para></listitem>
+      
+    </itemizedlist>
+  </section>
+  
+  <section id="policy-discuss"><title>Issues to discuss</title>
+    
+    <para>The following points are discussions about the policy, either
+      because they have to be studied more, or are controversial.</para>
+    
+    <itemizedlist>
+      
+      <listitem><para>Name and existance of the repository. It was removed
+	  in the latest version.</para></listitem>
+
+      <listitem><para>The symbolic links in /usr/share/java be made by a script
+	  instead, similar to the c-libraries.
+	</para></listitem>
+
+      
+      <listitem><para>Core classes (<filename>java.*</filename>). More study
+	  needed.</para></listitem>
+      
+      <listitem><para>Sun's Community Source Licence. Can we use it? How?
+	  Where can we <ulink url="http://www.sun.com/software/communitysource/faq.html">
+	    find the text</ulink>?
+	</para></listitem>
+
+      <listitem>
+	<para>All jars must have a good CLASSPATH documentation, but
+	  how should it be documented. The best solution is probably in some
+	  computer parsable format to make it even easier for the developer.
+	</para>
+	<para>It should exist some tool to parse this. How should it
+	  work?
+	</para>
+	<para>Should the tool also be used to create the necessary symbilic
+	  links needed by servlets under tomcat?
+	</para>
       </listitem>
-<listitem><para>or in the General Java Repository.</para></listitem>
-</itemizedlist>
-
-<para>In the first case, they &must; have a well-documented CLASSPATH, so 
-that developers should know what to add to their wrappers.</para>
-
-<para>This applies only to libraries, <emphasis>not</emphasis> to the core classes.</para>
-
-<para>A General Java Repository is created by java-common in
-&repository;. Classes which comply with the hierarchical packages
-naming (for instance, gnu.getopt, com.foo.bar), &may; install classes
-under it. It is expected that adding &repository; to the CLASSPATH is
-enough to run any Java program which depends on such classes 
-(this &should; be done by Java virtual machines or compilers).</para>
-
-<para>This policy does not address the issue of documentation (for instance
-HTML pages made with javadoc).</para>
-
-<para>There is no naming rules for programs, they are ordinary programs, from
-the user point of view. Libraries packages &must; be named lib-XXX-java.</para>
-
-<para>About politics: packaging Java stuff changes nothing to the
-rules Debian uses to find if a program is free or not. Since there are
-not many free Java tools, keep in mind the following:</para>
-
-<itemizedlist>
-
-<listitem><para>If you source package can compile (correctly) only
-with non-free tools (the only free Java compilers seems to be guavac
-and gcj and may be jikes if it changes its licence), it
-cannot go to main. If your package itself is free, it must goes to
-contrib.</para></listitem>
-
-<listitem><para>If your binary package can run only with non-free
-virtual machines (the only free Java virtual machine seems to be
-kaffe - and the one included in libgcj), it cannot go to main.  If your package itself is free, it must
-goes to contrib.</para></listitem>
-
-</itemizedlist>
-
-</section>
-
-<section id="policy-discuss"><title>Issues to discuss</title>
-
-<para>The following points are discussions about the policy, either
-because they have to be studied more, or are controversial.</para>
-
-<itemizedlist>
-
-<listitem><para>Name of the Repository. There is a proposal to replace
-it by simply <filename>/usr/share/java</filename>. (Per Bothner
-<email>per@bothner.com</email>)</para></listitem>
-
-<listitem><para>Core classes (<filename>java.*</filename>). More study
-needed.</para></listitem>
-
-<listitem><para>Versioned dependencies. Programs may have the need to
-depend on a VM &gt;= 1.2, for instance. Since dpkg does not have
-versioned provides, it is difficult.  Also, many people mistake JDK
-versions for language versions. More studies of the Java Language
-Specification needed (Adam Di Carlo
-<email>adam@onshore.com</email>).</para></listitem>
-
-<listitem><para>Sun's Community Source Licence. Can we use it? How?
-Where can we <ulink url="http://www.sun.com/software/communitysource/faq.html">
-find the text</ulink>?
-</para></listitem>
-
-</itemizedlist>
-
-</section>
-
-<section id="policy-advices"><title>Advices to Java packagers</title>
-
-<para>Warning: they are just advices, they are not part of the policy.</para>
-
-<itemizedlist>
-
-<listitem><para>At the present time, there is no recommandation on
-wether a library should use a <filename>.jar</filename> or the General
-Java Repository. Some tools may require jars (for instance, for their
-cryptographical signatures). It is the advice of the original author
-of this policy that jars are almost useless for a local system
-(applets on a network are a different thing).</para></listitem>
-
-<listitem><para>Be sure to manage all dependencies by hand in
-<filename>debian/control</filename>. Debian development tools cannot
-find them automatically like they do with C programs and libraries (or
-like dh_perl does it for Perl, a volunteer to write dh_java would be
-welcome).</para></listitem>
-
-<listitem><para>You can suppress many calls in
-<filename>debian/rules</filename> which are meaningless for Java, like
-dh_strip or dh_shlibdeps.</para></listitem>
-
-<listitem><para>Source package handling is painful, since most Java
-upstream programs come with <filename>.class</filename> files. I
-suggest to make a new <filename>.orig</filename> tarball after
-cleaning them, otherwise, dpkg-source will complain.</para></listitem>
-
-<listitem><para>Java properties files are probably better under
-<filename>/etc</filename> and flagged as configuration files (this
-will be integrated in the policy, one day).</para>
-</listitem>
-
-</itemizedlist>
-
-</section>
-
+      
+      <listitem><para>Should there be a default classpath, similar to a
+	  repository? Which jars should be included in that? A standard and
+	  one optional part? If there are a default classpath (in the
+	  wrapper) how should it be overridden?
+	</para></listitem>      
+
+      <listitem><para>How to check for a good enough jvm, and to select a
+	  proper one to use. Are /etc/alternatives not good enough?
+	</para></listitem>
+      
+      <listitem><para>Should the jvm internal classes be possible to
+	  override entirely and how?
+	</para></listitem>
+    </itemizedlist>
+
+  </section>
+  
+  <section id="policy-advices"><title>Advices to Java packagers</title>
+    
+    <para>Warning: they are just advices, they are not part of the policy.</para>
+    
+    <itemizedlist>
+      <listitem><para>Be sure to manage all dependencies by hand in
+	  <filename>debian/control</filename>. Debian development tools cannot
+	  find them automatically like they do with C programs and libraries 
+	  (or like dh_perl does it for Perl, a volunteer to write dh_java
+	  would be welcome).
+	</para></listitem>
+      
+      <listitem><para>You can suppress many calls in
+	  <filename>debian/rules</filename> which are meaningless for Java,
+	  like dh_strip and dh_shlibdeps.
+	</para></listitem>
+      
+      <listitem><para>Source package handling is painful, since most Java
+	  upstream programs come with <filename>.class</filename> files. I
+	  suggest to make a new <filename>.orig</filename> tarball after
+	  cleaning them, otherwise, dpkg-source will complain.
+	</para></listitem>
+      
+      <listitem><para>Java properties files are probably better under
+	  <filename>/etc</filename> and flagged as configuration files (this
+	  will be integrated in the policy, one day).
+	</para></listitem>
+      
+    </itemizedlist>
+    
+  </section>
+  
 </article>
-
-
-
-
-
-
-
-