Bug 137760 – update Java documentation

• Product: [OLD] Docs on www.gentoo.org
• Status: RESOLVED FIXED

[Description Josh Nichols (RETIRED) 2006-06-23 10:33:52 UTC]

In preparation for the changes we will be making to the way Java is handled, we have updated Java user documentation. It is in subversion at:

http://svn.gentooexperimental.org/svn/java/migration/docs/java-user.xml

I spoke briefly with nightmorph in #gentoo-doc, and he said it looked good overall, but the guidexml needed some work.

[Comment 1 nm (RETIRED) 2006-06-23 11:32:01 UTC]

(In reply to comment #0)

Indeed. Are you sure you used the current version (Dec. 12 2005, v0.3) of the guide when you prepared this? Also, please note that the file name is java.xml, not java-user.xml. :)

I ran a diff against this doc, and the changes are certainly substantial. But has all the work Swift and vanquirius done been tossed out the window for this version? (please do note the odd file version change, too. 0.3 --> 0.1.8?)

Still, this looks pretty good overall.

[Comment 2 Josh Nichols (RETIRED) 2006-06-23 11:55:02 UTC]

The guide was started a long while ago (probably 9+ months ago) while work was being done on the new system. I wasn't involved with the work then, so I'm not sure where it came from, or what the history was at that point.

As for 0.3, these updated docs should cover all the bases covered in it.

Side note: but would it be possible to associate a particular doc with a team? Specifically, it'd be useful to know when docs related to us change :)

[Comment 3 Vlastimil Babka (Caster) (RETIRED) 2006-06-23 16:01:42 UTC]

I've read it and have few comments if you don't mind.

- java-config
 - shows only long commands like --list-available-vms or --set-system-vm but not short variants -L -S which IMHO every non-"typeholic" would prefer to use :)
 - Code listing 3.1: Listing available VMs - the real output is more colorful, selected VM is green, JRE and JDK have different color, maybe colorize example and mention that?

- jdk.conf is mentioned in great detail, but nothing about compilers.conf 
- typos and malformed sentences, but that's bout editing right

otherwise good :)

[Comment 4 nm (RETIRED) 2006-06-24 08:47:41 UTC]

(In reply to comment #3)
> I've read it and have few comments if you don't mind.
> 
> - java-config
>  - shows only long commands like --list-available-vms or --set-system-vm but
> not short variants -L -S which IMHO every non-"typeholic" would prefer to use

No need. It's much clearer this way for new java users. If you're that gung-ho on shortening things, "man java-config" isn't that difficult.

>  - Code listing 3.1: Listing available VMs - the real output is more colorful,
> selected VM is green, JRE and JDK have different color, maybe colorize example
> and mention that?

There's no way to do this.
 
> - jdk.conf is mentioned in great detail, but nothing about compilers.conf 

nichoj, how do you feel about discussing compilers.conf? For now, I'll edit the minor details and post it for you to review, and you can make any content changes at any time before or after the doc is committed.

[Comment 5 nm (RETIRED) 2006-06-24 09:06:10 UTC]

Created attachment 90038 [details]
edited java.xml

Edits for guidexml, coding style, etc. Lengthy changes, but on the whole, this is a nice doc that reads very well. Yay for java updates.

[Comment 6 nm (RETIRED) 2006-06-24 09:09:35 UTC]

Created attachment 90039 [details, diff]
diff of the edit against the SVN original

Here's a diff showing the changes I made to the original. Again, mostly just guidexml & coding style changes. nichoj, tell me about any changes you'd like to make.

[Comment 7 Josh Nichols (RETIRED) 2006-06-24 09:31:13 UTC]

Thanks nightmorph :) 

As for covering compilers.conf, it's not a crucial aspect of the system, so I think we can get away with not document immediately. Although, it wouldn't require much doc'ing, so I guess I'll update it today.

As for using long switches for java-config, I think it's useful to use them for clarity about what they mean / do. Perhaps we could add a note that there are short switches.

[Comment 8 Petteri Räty (RETIRED) 2006-06-24 09:57:26 UTC]

(In reply to comment #7)
> 
> As for using long switches for java-config, I think it's useful to use them for
> clarity about what they mean / do. Perhaps we could add a note that there are
> short switches.
> 

Quite useless as it is almost impossible to not run into short switches when using *nix.

[Comment 9 nm (RETIRED) 2006-06-24 11:30:39 UTC]

In CVS. Thanks to nichoj + java team for all the hard work on this update. Blame me for any remaining typographical errors or missing guidexml stuff; should be none. :)