Re: GCJ manual changed

["Joseph S. Myers" <jsm28 at cam dot ac dot uk>]

On 29 Jan 2002, Nic Ferrier wrote:

> I've attached the whole file because the changes seem substantial
> enough to warrant that. If people would prefer me to send a diff
> against the current repository I'll be happy to do so.

Diffs are generally preferred.  You also attached it as
application/texinfo; for text attachments, text/whatever types should be
used.

> @code{gcj} uses the same compiler technology as @code{g++} (the GNU

Use @command to mark up command names.

> You write CNI code as a regular C++ source file.  (You do have to use
> a Java/CNI-aware C++ compiler, specifically a recent version of @code{G++}.)

@code{G++} is never appropriate; if it's a command, it's @command{g++}; if
not, G++ with no markup.

> And then must include one header file for each Java class it uses, eg:

"eg" with no punctuation is not a proper spelling; it should be "e.g.".

> These header files are automatically generated by @code{gcjh}.

Again, here and below (not further detailed below), @command for commands.

> allows the program text to refer to @var{class-name} as a shorthand for 
> the fully qualified name: @var{package-name}.@var{class-name}.

You probably want @code{@var{package-name}.@var{class-name}} to get the
dot in the correct font.

> refered to only by it's class-name within the program text.

The possessive is "its"; "it's" means "it is" or "it has".

> characters and booleans (and also the void type). C++ has it's own

Two spaces after full stops in Texinfo input.

> When refering to a Java type You should always use these C++ typenames (e.g. @code{jint})

Full stops following lowercase letters not at the end of sentences must be
followed by @: or other punctuation, so you want "e.g.@:" or "e.g.," here.

> The Gcj compiler inserts calls to @code{JvInitClass} at appropriate places to ensure that a

You're using "Gcj" here, earlier you used "GCJ".  Be consistent.  (The
distinction between "GCJ" and "@command{gcj}" is that the first refers to
the Java compiler in general and the other specifically to the compilation
command.)

> insert these calls automatically - it is the programmer's

TeX dashes - "---" with no spaces around it.

> @dfn{class-instance-creation-expression}, eg:

Again, "e.g." not "eg".

> Referencing a Java array in C++ code is done using the
> JArray template, which as defined as follows:

I think this should be @code{JArray}.

> @example
> JvNewBooleanArray
> @end example
> 
> can be used to create an array of Java primitive boolean types.

If this partial paragraph gets indented in the DVI output, you should
precede it by @noindent so that it doesn't.

> @deftypefun jbooleanArray JvNewBooleanArray (jint @var{length})
> Create's an array @code{length} indices long.

@var{length} (strictly, @code{@var{length}}).

> @end deftypefun
> 
> @deftypefun jsize JvGetArrayLength (jarray @var{array})
> Returns the length of the @code{array}.

Likewise.

> Calling a Java instance method from a C++ @acronym{CNI} method is done 
> using the standard C++ syntax, eg:

"e.g.".

> @acronym{CNI} provides a number of utility functions for
> working with Java Java @code{String} objects.
> The names and interfaces are analogous to those of @acronym{JNI}.

In general, full stops following capital letters at ends of sentences
should be "@.".  This isn't necessary where the capital letter is in @code
or @samp; but unless you're sure @acronym works that way, there should be
@. here.

> @deftypefun jstring JvNewString (const char* @var{chars}, jsize @var{len})
> Returns a Java @code{String} object with characters from the C string
> @code{chars} up to the index @code{len} in that array.

Again, using @var, here and below.  Note that @var arguments get
capitalised in the Info manual and the inconsistency will look very odd
there.

> @deftypefun jstring JvNewStringUTF (const char* @var{bytes})
> Returns a @code{String} which is made up of the UTF encoded characters

You say "UTF", which UTF (there are several, e.g., UTF-8, UTF-16, UTF-32)?

> Normally, GNU C++ will automatically detect when you are writing C++

"GNU C++" is the name of the GNU language dialect rather than an
implementation; see codingconventions.html.  You probably want to say G++
here.

> extern void bar();    // is implemented in Java and may throw exceptions

Comments in examples, here and above, should be in @r{}.

> >From C++, it makes sense to use a destructor to release a lock.

Anyone checking in this patch had better make sure the version they have
doesn't have the >From there.  Sending a proper patch rather than a new
version of the file would avoid >From problems.

> might become this C++ code:

@noindent, as noted above, may be necessary here and elsewhere.

> Reflection is possible with CNI code, it functions similarly to how it
> functions with JNI.
> 
> @c clean this up... I mean, what are the types jfieldID and jmethodID in JNI?
> The types @code{jfieldID} and @code{jmethodID}
> are as in JNI.

@. for full stops at ends of sentences preceded by capital letters.

> will be added shortly, as will other functions corresponding to JNI.

Likewise.

-- 
Joseph S. Myers
jsm28@cam.ac.uk