OSDN Git Service

f7a2d245e7dd4e6748373cc9238e1a433fab093c
[pf3gnuchains/gcc-fork.git] / libjava / classpath / doc / cp-tools.texinfo
1 \input texinfo @c -*-texinfo-*-
2
3 @c %**start of header
4 @setfilename cp-tools.info
5 @settitle GNU Classpath Tools Guide
6 @c %**end of header
7
8 @setchapternewpage on
9
10 @c Common macros to support generating man pages:
11
12 @macro gcctabopt{body}
13 @code{\body\}
14 @end macro
15 @macro gccoptlist{body}
16 @smallexample
17 \body\
18 @end smallexample
19 @end macro
20
21 @ifinfo
22 This file documents the Tools included in a standard distribution of the GNU
23 Classpath project deliverables.
24
25 Copyright (C) 2006, 2007 Free Software Foundation, Inc.
26
27 @ifnotplaintext
28 @dircategory GNU Libraries
29 @direntry
30 * Classpath Tools: (cp-tools).  GNU Classpath Tools Guide
31 @end direntry
32 @end ifnotplaintext
33 @end ifinfo
34
35 @titlepage
36 @title GNU Classpath Tools Guide
37 @author The GNU Classpath Team
38
39 @page
40 @vskip 0pt plus 1filll
41 Copyright @copyright{} 2006 Free Software Foundation, Inc.
42 @sp 2
43 Permission is granted to make and distribute verbatim copies of this document provided the copyright notice and this permission notice are preserved on all copies.
44
45 Permission is granted to copy and distribute modified versions of this document under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.
46
47 Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Free Software Foundation.
48
49 @end titlepage
50
51 @contents
52
53 @ifinfo
54 @node Top, Applet Tools, (dir), (dir)
55 @top GNU Classpath Tools Guide
56
57 This document contains important information you need to know in order to use
58 the tools included in the GNU Classpath project deliverables.
59
60 The Tools aim at providing a free replacement, similar in their behavior, to
61 their counter-parts found in the Reference Implementation (RI) of the Java
62 Software Development Kit (SDK).
63
64 @end ifinfo
65
66 @menu
67 * Applet Tools::               Work with applets
68 * Security Tools::             Work securely with Java applications
69 * Other Tools::                Other tools in classpath
70 * I18N Issues::                How to add support for non-English languages
71
72 @detailmenu
73  --- The Detailed Node Listing ---
74
75 Applet Tools
76
77 * appletviewer Tool::          Load applets
78 * gcjwebplugin::               Load applets in a web browser
79
80 Security Tools
81
82 * jarsigner Tool::             Sign and verify .JAR files
83 * keytool Tool::               Manage private keys and public certificates
84
85 jarsigner Tool
86
87 * Common jarsigner Options::   Options used when signing or verifying a file
88 * Signing Options::            Options only used when signing a .JAR file
89 * Verification Options::       Options only used when verifying a .JAR file
90
91 keytool Tool
92
93 * Getting Help::               How to get help with keytool commands
94 * Common keytool Options::     Options used in more than one command
95 * Distinguished Names::        X.500 Distinguished Names used in certificates
96 * Add/Update Commands::        Commands for adding data to a Key Store
97 * Export Commands::            Commands for exporting data from a Key Store
98 * Display Commands::           Commands for displaying data in a Key Store
99 * Management Commands::        Commands for managing a Key Store
100
101 Add/Update Commands
102
103 * Command -genkey::            Generate private key and self-signed certificate
104 * Command -import::            Import certificates and certificate replies
105 * Command -selfcert::          Generate self-signed certificate
106 * Command -cacert::            Import a CA Trusted Certificate
107 * Command -identitydb::        Import JDK-1 style identities
108
109 Export Commands
110
111 * Command -certreq::           Generate Certificate Signing Requests (CSR)
112 * Command -export::            Export a certificate in a Key Store
113
114 Display Commands
115
116 * Command -list::              Display information about one or all Aliases
117 * Command -printcert::         Print a certificate or a certificate fingerprint
118
119 Management Commands
120
121 * Command -keyclone::          Clone a Key Entry in a Key Store
122 * Command -storepasswd::       Change the password protecting a Key Store
123 * Command -keypasswd::         Change the password protecting a Key Entry
124 * Command -delete::            Remove an entry in a Key Store
125
126 Other Tools
127
128 * jar Tool::                   Archive tool for Java archives
129 * javah Tool::                 A java header compiler
130 * gcjh Tool::                  A java header compiler (old version)
131 * native2ascii Tool::          An encoding converter
132 * orbd Tool::                  An object request broker daemon
133 * serialver Tool::             A serial version command
134 * rmid Tool::                  RMI activation daemon
135 * rmiregistry Tool::           Remote object registry
136 * tnameserv Tool::             Naming service
137 * gjdoc Tool::                 Documenation generator tool.
138
139 Generating HTML Documentation
140
141 * Invoking the Standard Doclet::   How to generate HTML documentation.
142 * Invoking a Custom Doclet::       How to run third-party and other 
143                                    built-in Doclets.
144
145 * Option Summary by Type::         Brief list of all options, grouped by type.
146 * Gjdoc Option Summary::           List of all options accepted by Gjdoc.
147
148 * Source Set Options::      Select the set of source codes to run Gjdoc on.
149 * Source Format Options::   Specify the format of the source codes to document.
150
151 * Interlinking Options::    Connection your documentation with other projects.
152 * Output Control Options::  Specify the target directory and locale, and more.
153 * Generation Options::      Select which pieces of information to generate.
154 * Decoration Options::      Add or modify some titles, headers and footers or
155                             override/amend static resources like stylesheets.
156 * Taglet Options::          Define your own javadoc @@tags.
157
158 * Virtual Machine Options:: Controlling the kind of output:
159                             an executable, object files, assembler files,
160                             or preprocessed source.
161 * Verbosity Options::
162 * Doclet Options::
163
164 * Other Doclets::           Generating Other Output Types. 
165
166 * Built-in Doclets::        Using the Built-in Doclets.
167 * Using XmlDoclet::
168 * Using TexiDoclet::
169 * Using IspellDoclet::
170 * Using DebugDoclet::
171
172 * Third-party Doclets::     Using Third-Party Doclets.
173 * DocBook Doclet::
174 * PDFDoclet::
175 * JUnitDoclet::
176
177 * Gjdoc Concepts::          Advanced Concepts.
178 * Writing Doclets::
179
180 * Doclet Invocation Interface::    Implementing the Doclet Invocation Interface
181 * Using AbstractDoclet::           Deriving Your Doclet from AbstractDoclet.
182 * GNU Doclet SPI::                 Preparing the GNU Doclet Service Provider
183                                    Interface.
184
185 * Taglets::                        Adding Custom Tags to the Documentation.
186 * XHTML Fragments::                Well-Formed Documentation Fragments.
187 * First Sentence Detector::        How Gjdoc Determines where the First
188                                    Sentence Ends.
189 * Adding Custom Resources::        Adding Images and Other Resources.
190
191 I18N Issues
192
193 * Language Resources::         Where resources are located
194 * Message Formats::            How messages are internationalized
195
196 @end detailmenu
197 @end menu
198
199 @comment ----------------------------------------------------------------------
200
201 @node Applet Tools, Security Tools, Top, Top
202 @comment node-name, next, previous, up
203 @chapter Applet Tools
204
205 Two Applet Tools are available with GNU Classpath: @b{appletviewer}
206 and @b{gcjwebplugin}.
207
208 To avoid conflicts with other implementations, the appletviewer
209 executable is called ``gappletviewer''.
210
211 @menu
212 * appletviewer Tool::          Load applets
213 * gcjwebplugin::               Load applets in a web browser
214 @end menu
215
216 If while using these tools you think you found a bug, then please report it at @uref{http://www.gnu.org/software/classpath/bugs.html,classpath-bugs}.
217
218 @comment ----------------------------------------------------------------------
219
220 @node appletviewer Tool, gcjwebplugin, Applet Tools, Applet Tools
221 @comment node-name, next, previous, up
222 @section The @code{appletviewer} Tool
223 @c man title gappletviewer Load and runs an applet
224
225 SYNOPSIS
226
227 @c man begin SYNOPSIS gappletviewer
228 appletviewer [@var{OPTION}]@dots{} @var{URL}@dots{} @var{@*}
229
230 appletviewer [@var{OPTION}]@dots{} @option{-code} @var{CODE} @var{@*}
231
232 appletviewer [@var{OPTION}]@dots{} @option{-plugin} @var{INPUT},@var{OUTPUT}
233 @c man end
234
235 DESCRIPTION
236 @c man begin DESCRIPTION gappletviewer
237 The @command{appletviewer} tool loads and runs an applet.
238
239 Use the first form to test applets specified by tag.  The URL should
240 resolve to an HTML document from which the @command{appletviewer} will
241 extract applet tags.  The APPLET, EMBED and OBJECT tags are supported.
242 If a given document contains multiple applet tags, all the applets
243 will be loaded, with each applet appearing in its own window.
244 Likewise, when multiple URLs are specified, each applet tag instance
245 is given its own window.  If a given document contains no recognized
246 tags the @command{appletviewer} does nothing.
247
248 @smallexample
249 appletviewer http://www.gnu.org/software/classpath/
250 @end smallexample
251
252 Use the second form to test an applet in development.  This form
253 allows applet tag attributes to be supplied on the command line.  Only
254 one applet may be specified using the @option{-code} option.  The
255 @option{-code} option overrides the URL form -- any URLs specified will
256 be ignored.
257
258 @smallexample
259 appletviewer -code Test.class -param datafile,data.txt
260 @end smallexample
261
262 @command{gcjwebplugin} uses the third form to communicate with the
263 @command{appletviewer} through named pipes.
264 @c man end
265
266 @c man begin OPTIONS gappletviewer
267 URL OPTIONS
268 @table @gcctabopt
269 @item -debug
270 This option is not yet implemented but is provided for compatibility.
271
272 @item -encoding @var{CHARSET}
273 Use this option to specify an alternate character encoding for the
274 specified HTML page.
275
276 @end table
277
278 APPLET TAG OPTIONS
279 @table @gcctabopt
280 @item -code @var{CODE}
281 Use the @option{-code} option to specify the value of the applet tag
282 @var{CODE} attribute.
283
284 @item -codebase @var{CODEBASE}
285 Use the @option{-codebase} option to specify the value of the applet tag
286 @var{CODEBASE} attribute.
287
288 @item -archive @var{ARCHIVE}
289 Use the @option{-archive} option to specify the value of the applet tag
290 @var{ARCHIVE} attribute.
291
292 @item -width @var{WIDTH}
293 Use the @option{-width} option to specify the value of the applet tag
294 @var{WIDTH} attribute.
295
296 @item -height @var{HEIGHT}
297 Use the @option{-height} option to specify the value of the applet tag
298 @var{HEIGHT} attribute.
299
300 @item -param @var{NAME},@var{VALUE}
301 Use the @option{-param} option to specify values for the @var{NAME}
302 and @var{VALUE} attributes of an applet PARAM tag.
303
304 @end table
305
306 PLUGIN OPTION
307 @table @gcctabopt
308 @item -plugin @var{INPUT},@var{OUTPUT}
309 @command{gcjwebplugin} uses the @option{-plugin} option to specify the
310 named pipe the @command{appletviewer} should use for receiving commands
311 (@var{INPUT}) and the one it should use for sending commands to
312 @command{gcjwebplugin} (@var{OUTPUT}).
313
314 @end table
315
316 DEBUGGING OPTION
317 @table @gcctabopt
318 @item -verbose
319 Use the @option{-verbose} option to have the @command{appletviewer} print
320 debugging messages.
321
322 @end table
323
324 STANDARD OPTIONS
325
326 @table @gcctabopt
327 @item -help
328 Use the @option{-help} option to have the @command{appletviewer} print a
329 usage message, then exit.
330
331 @item -version
332 Use the @option{-version} option to have the @command{appletviewer} print
333 its version, then exit.
334
335 @item -J@var{OPTION}
336 Use the @option{-J} option to pass @var{OPTION} to the virtual machine that
337 will run the @command{appletviewer}.  Unlike other options, there must
338 not be a space between the @option{-J} and @var{OPTION}.
339
340 @end table
341 @c man end
342
343 @comment ----------------------------------------------------------------------
344
345 @node gcjwebplugin, , appletviewer Tool, Applet Tools
346 @comment node-name, next, previous, up
347 @section The @code{gcjwebplugin} Tool
348
349 @code{gcjwebplugin} is a plugin that adds applet support to web
350 browsers.  Currently @code{gcjwebplugin} only supports Mozilla-based
351 browsers (e.g., Firefox, Galeon, Mozilla).
352
353 @comment ----------------------------------------------------------------------
354
355 @node Security Tools, Other Tools, Applet Tools, Top
356 @comment node-name, next, previous, up
357 @chapter Security Tools
358
359 Two Security Tools are available with GNU Classpath:
360 @command{jarsigner} and @command{keytool}.
361
362 To avoid conflicts with other implementations, the jarsigner
363 executable is called @command{gjarsigner} and the keytool executable is
364 called @command{gkeytool}.
365
366 @menu
367 * jarsigner Tool::             Sign and verify .JAR files
368 * keytool Tool::               Manage private keys and public certificates
369 @end menu
370
371 If while using these tools you think you found a bug, then please report it at @uref{http://www.gnu.org/software/classpath/bugs.html,classpath-bugs}.
372
373 @comment ----------------------------------------------------------------------
374
375 @node jarsigner Tool, keytool Tool, Security Tools, Security Tools
376 @comment node-name, next, previous, up
377 @section The @code{jarsigner} Tool
378 @c man title gjarsigner Java ARchive (JAR) file signing and verification tool
379
380 The @command{jarsigner} tool is invoked from the command line, in one
381 of two forms, as follows:
382
383 @example
384 @c man begin SYNOPSIS gjarsigner
385 jarsigner [@var{OPTION}]@dots{} @var{FILE} @var{ALIAS}
386
387 jarsigner @option{-verify} [@var{OPTION}]@dots{} @var{FILE}
388 @c man end
389 @end example
390
391 @c man begin DESCRIPTION gjarsigner
392 When the first form is used, the tool signs the designated JAR file. The second form, on the other hand, is used to verify a previously signed JAR file.
393
394 @var{FILE} is the .JAR file to process; i.e., to sign if the first syntax form is used, or to verify if the second syntax form is used instead.
395
396 @var{ALIAS} must be a known @i{Alias} of a @i{Key Entry} in the designated @i{Key Store}. The private key material associated with this @i{Alias} is then used for signing the designated .JAR file.
397 @c man end
398
399 @menu
400 * Common jarsigner Options::   Options used when signing or verifying a file
401 * Signing Options::            Options only used when signing a .JAR file
402 * Verification Options::       Options only used when verifying a .JAR file
403 @end menu
404
405 @comment ----------------------------------------------------------------------
406
407 @node Common jarsigner Options, Signing Options, jarsigner Tool, jarsigner Tool
408 @comment node-name, next, previous, up
409 @c man begin OPTIONS gjarsigner
410 @subsection Common options
411
412 The following options may be used when the tool is used for either signing, or verifying, a .JAR file.
413
414 @table @gcctabopt
415 @item -verbose
416 Use this option to force the tool to generate more verbose messages, during its processing.
417
418 @item -internalsf
419 When present, the tool will include --which otherwise it does not-- the @code{.SF} file in the @code{.DSA} generated file.
420
421 @item -sectionsonly
422 When present, the tool will include in the @code{.SF} generated file --which otherwise it does not-- a header containing a hash of the whole manifest file.  When that header is included, the tool can quickly check, during verification, if the hash (in the header) matches or not the manifest file.
423
424 @item -provider PROVIDER_CLASS_NAME
425 A fully qualified class name of a @i{Security Provider} to add to the current list of @i{Security Providers} already installed in the JVM in-use. If a provider class is specified with this option, and was successfully added to the runtime --i.e.@: it was not already installed-- then the tool will attempt to remove this @i{Security Provider} before exiting.
426
427 @item -help
428 Prints a help text similar to this one.
429
430 @end table
431 @c man end
432
433 @comment ----------------------------------------------------------------------
434
435 @node Signing Options, Verification Options, Common jarsigner Options, jarsigner Tool
436 @comment node-name, next, previous, up
437 @c man begin OPTIONS gjarsigner
438 @subsection Signing options
439
440 The following options may be specified when using the tool for signing purposes.
441
442 @table @gcctabopt
443 @item -keystore @var{URL}
444 Use this option to specify the location of the key store to use. The default value is a file URL referencing the file named @file{.keystore} located in the path returned by the call to @code{java.lang.System#getProperty(String)} using @code{user.home} as argument.
445
446 If a URL was specified, but was found to be malformed --e.g.@: missing protocol element-- the tool will attempt to use the URL value as a file-name (with absolute or relative path-name) of a key store --as if the protocol was @code{file:}.
447
448 @item -storetype @var{STORE_TYPE}
449 Use this option to specify the type of the key store to use. The default value, if this option is omitted, is that of the property @code{keystore.type} in the security properties file, which is obtained by invoking the static method call @code{getDefaultType()} in @code{java.security.KeyStore}.
450
451 @item -storepass @var{PASSWORD}
452 Use this option to specify the password which will be used to unlock the key store. If this option is missing, the User will be prompted to provide a password.
453
454 @item -keypass @var{PASSWORD}
455 Use this option to specify the password which the tool will use to unlock the @i{Key Entry} associated with the designated @i{Alias}.
456
457 If this option is omitted, the tool will first attempt to unlock the @i{Key Entry} using the same password protecting the key store. If this fails, you will then be prompted to provide a password.
458
459 @item -sigfile @var{NAME}
460 Use this option to designate a literal that will be used to construct file names for both the @code{.SF} and @code{.DSA} signature files. These files  will be generated, by the tool, and placed in the @file{META-INF} directory of the signed JAR@.  Permissible characters for @var{NAME} must be in the range "a-zA-Z0-9_-".  All characters will be converted to upper-case ones.
461
462 If this option is missing, the first eight characters of the @var{ALIAS} argument will be used. When this is the case, any character in @var{ALIAS} that is outside the permissible range of characters will be replaced by an underscore.
463
464 @item -signedjar @var{FILE}
465 Use this option to specify the file name of the signed JAR@. If this option is omitted, then the signed JAR will be named the same as @var{FILE}; i.e., the input JAR file will be replaced with the signed copy.
466
467 @end table
468 @c man end
469
470 @comment ----------------------------------------------------------------------
471
472 @node Verification Options, , Signing Options, jarsigner Tool
473 @comment node-name, next, previous, up
474 @c man begin OPTIONS gjarsigner
475 @subsection Verification options
476
477 The following options may be specified when using the tool for verification purposes.
478
479 @table @gcctabopt
480 @item -verify
481 Use this option to indicate that the tool is to be used for verification purposes.
482
483 @item -certs
484 This option is used in conjunction with the @option{-verbose} option. When present, along with the @option{-verbose} option, the tool will print more detailed information about the certificates of the signer(s) being processed.
485
486 @end table
487 @c man end
488
489 @comment ----------------------------------------------------------------------
490
491 @node keytool Tool, , jarsigner Tool, Security Tools
492 @comment node-name, next, previous, up
493 @section The @code{keytool} Tool
494 @c man title gkeytool Manage private keys and public certificates
495
496 @ignore
497 @c man begin SYNOPSIS gkeytool
498 keytool [@var{COMMAND}] @dots{}
499 @c man end
500 @end ignore
501
502 @c man begin DESCRIPTION gkeytool
503 Cryptographic credentials, in a Java environment, are usually stored in a @i{Key Store}. The Java SDK specifies a @i{Key Store} as a persistent container of two types of objects: @i{Key Entries} and @i{Trusted Certificates}. The security tool @command{keytool} is a Java-based application for managing those types of objects.
504
505 A @i{Key Entry} represents the private key part of a key-pair used in Public-Key Cryptography, and a signed X.509 certificate which authenticates the public key part for a known entity; i.e.@: the owner of the key-pair. The X.509 certificate itself contains the public key part of the key-pair.
506
507 A @i{Trusted Certificate} is a signed X.509 certificate issued by a trusted entity. The @i{Trust} in this context is relative to the User of the @command{keytool}. In other words, the existence of a @i{Trusted Certificate} in the @i{Key Store} processed by a @command{keytool} command implies that the User trusts the @i{Issuer} of that @i{Trusted Certificate} to also sign, and hence authenticates, other @i{Subjects} the tool may process.
508
509 @i{Trusted Certificates} are important because they allow the tool to mechanically construct @i{Chains of Trust} starting from one of the @i{Trusted Certificates} in a @i{Key Store} and ending with a certificate whose @i{Issuer} is potentially unknown. A valid chain is an ordered list, starting with a @i{Trusted Certificate} (also called the @i{anchor}), ending with the target certificate, and satisfying the condition that the @i{Subject} of certificate @code{#i} is the @i{Issuer} of certificate @code{#i + 1}.
510
511 The @command{keytool} is invoked from the command line as follows:
512
513 @smallexample
514 keytool [COMMAND] ...
515 @end smallexample
516
517 Multiple @var{COMMAND}s may be specified at once, each complete with its own options. @command{keytool} will parse all the arguments, before processing, and executing, each @code{COMMAND}. If an exception occurs while executing one @var{COMMAND} @command{keytool} will abort. Note however that because the implementation of the tool uses code to parse command line options that also supports GNU-style options, you have to separate each command group with a double-hyphen; e.g
518
519 @smallexample
520 keytool -list -- -printcert -alias mykey
521 @end smallexample
522 @c man end
523
524 Here is a summary of the commands supported by the tool:
525
526 @c man begin OPTIONS gkeytool
527 @enumerate
528 @item Add/Update commands
529 @table @gcctabopt
530 @item -genkey [@var{OPTION}]@dots{}
531 Generate a new @i{Key Entry}, eventually creating a new key store.
532
533 @item -import [@var{OPTION}]@dots{}
534 Add, to a key store, @i{Key Entries} (private keys and certificate chains authenticating the public keys) and @i{Trusted Certificates} (3rd party certificates which can be used as @i{Trust Anchors} when building chains-of-trust).
535
536 @item -selfcert [@var{OPTION}]@dots{}
537 Generate a new self-signed @i{Trusted Certificate}.
538
539 @item -cacert [@var{OPTION}]@dots{}
540 Import a CA @i{Trusted Certificate}.
541
542 @item -identitydb [@var{OPTION}]@dots{}
543 @b{NOT IMPLEMENTED YET}.@*
544 Import a JDK 1.1 style Identity Database.
545 @end table
546
547 @item Export commands
548 @table @gcctabopt
549 @item -certreq [@var{OPTION}]@dots{}
550 Issue a @i{Certificate Signing Request} (CSR) which can be then sent to a @i{Certification Authority} (CA) to issue a certificate signed (by the CA) and authenticating the @i{Subject} of the request.
551
552 @item -export [@var{OPTION}]@dots{}
553 Export a certificate from a key store.
554 @end table
555
556 @item  Display commands
557 @table @gcctabopt
558 @item -list [@var{OPTION}]@dots{}
559 Print one or all certificates in a key store to @code{STDOUT}.
560
561 @item -printcert [@var{OPTION}]@dots{}
562 Print a human-readable form of a certificate, in a designated file, to @code{STDOUT}.
563 @end table
564
565 @item Management commands
566 @table @gcctabopt
567 @item -keyclone [@var{OPTION}]@dots{}
568 Clone a @i{Key Entry} in a key store.
569
570 @item -storepasswd [@var{OPTION}]@dots{}
571 Change the password protecting a key store.
572
573 @item -keypasswd [@var{OPTION}]@dots{}
574 Change the password protecting a @i{Key Entry} in a key store.
575
576 @item -delete [@var{OPTION}]@dots{}
577 Delete a @i{Key Entry} or a @i{Trusted Certificate} from a key store.
578 @end table
579 @end enumerate
580 @c man end
581
582 @menu
583 * Getting Help::               How to get help with keytool commands
584 * Common keytool Options::     Options used in more than one command
585 * Distinguished Names::        X.500 Distinguished Names used in certificates
586 * Add/Update Commands::        Commands for adding data to a Key Store
587 * Export Commands::            Commands for exporting data from a Key Store
588 * Display Commands::           Commands for displaying data in a Key Store
589 * Management Commands::        Commands for managing a Key Store
590 @end menu
591
592 @comment ----------------------------------------------------------------------
593
594 @node Getting Help, Common keytool Options, keytool Tool, keytool Tool
595 @comment node-name, next, previous, up
596 @subsection Getting help
597
598 To get a general help text about the tool, use the @code{-help} option; e.g.
599
600 @example
601 @code{keytool -help}
602 @end example
603
604 To get more specific help text about one of the tool's command use the @code{-help} option for that command; e.g.
605
606 @example
607 @code{keytool -genkey -help}
608 @end example
609
610 In both instances, the tool will print a help text and then will exit the running JVM.
611
612 It is worth noting here that the help messages printed by the tool are I18N-ready. This means that if/when the contents of the tool's @i{Message Bundle} properties file are available in languages other than English, you may see those messages in that language.
613
614 @comment ----------------------------------------------------------------------
615
616 @node Common keytool Options, Distinguished Names, Getting Help, keytool Tool
617 @comment node-name, next, previous, up
618 @c man begin OPTIONS gkeytool
619 @subsection Common options
620
621 The following @option{OPTION}s are used in more than one @command{COMMAND}. They are described here to reduce redundancy.
622
623 @table @gcctabopt
624 @anchor{alias}
625 @item -alias @var{Alias}
626 Every entry, be it a @i{Key Entry} or a @i{Trusted Certificate}, in a key store is uniquely identified by a user-defined @var{Alias} string. Use this option to specify the @var{Alias} to use when referring to an entry in the key store. Unless specified otherwise, a default value of @code{mykey} shall be used when this option is omitted from the command line.
627
628 @anchor{keyalg}
629 @item -keyalg @var{ALGORITHM}
630 Use this option to specify the canonical name of the key-pair generation algorithm. The default value for this option is @code{DSS} (a synonym for the Digital Signature Algorithm also known as DSA).
631
632 @anchor{keysize}
633 @item -keysize @var{SIZE}
634 Use this option to specify the number of bits of the shared modulus (for both the public and private keys) to use when generating new keys. A default value of @code{1024} will be used if this option is omitted from the command line.
635
636 @anchor{validity}
637 @item -validity @var{DAY_COUNT}
638 Use this option to specify the number of days a newly generated certificate will be valid for. The default value is @code{90} (days) if this option is omitted from the command line.
639
640 @anchor{storetype}
641 @item -storetype @var{STORE_TYPE}
642 Use this option to specify the type of the key store to use. The default value, if this option is omitted, is that of the property @code{keystore.type} in the security properties file, which is obtained by invoking the static method call @code{getDefaultType()} in @code{java.security.KeyStore}.
643
644 @anchor{storepass}
645 @item -storepass @var{PASSWORD}
646 Use this option to specify the password protecting the key store. If this option is omitted from the command line, you will be prompted to provide a password.
647
648 @anchor{keystore}
649 @item -keystore @var{URL}
650 Use this option to specify the location of the key store to use. The default value is a file URL referencing the file named @file{.keystore} located in the path returned by the call to @code{java.lang.System#getProperty(String)} using @code{user.home} as argument.
651
652 If a URL was specified, but was found to be malformed --e.g.@: missing protocol element-- the tool will attempt to use the URL value as a file-name (with absolute or relative path-name) of a key store --as if the protocol was @code{file:}.
653
654 @anchor{provider}
655 @item -provider @var{PROVIDER_CLASS_NAME}
656 A fully qualified class name of a @i{Security Provider} to add to the current list of @i{Security Providers} already installed in the JVM in-use. If a provider class is specified with this option, and was successfully added to the runtime --i.e.@: it was not already installed-- then the tool will attempt to removed this @i{Security Provider} before exiting.
657
658 @anchor{file}
659 @item -file @var{FILE}
660 Use this option to designate a file to use with a command. When specified with this option, the value is expected to be the fully qualified path of a file accessible by the File System. Depending on the command, the file may be used as input or as output. When this option is omitted from the command line, @code{STDIN} will be used instead, as the source of input, and @code{STDOUT} will be used instead as the output destination.
661
662 @anchor{verbose}
663 @item -v
664 Unless specified otherwise, use this option to enable more verbose output.
665
666 @end table
667 @c man end
668
669 @comment ----------------------------------------------------------------------
670
671 @node Distinguished Names, Add/Update Commands, Common keytool Options, keytool Tool
672 @comment node-name, next, previous, up
673 @subsection X.500 Distinguished Names
674
675 @anchor{dn}
676 A @i{Distinguished Name} (or DN) MUST be supplied with some of the @code{COMMAND}s using a @code{-dname} option. The syntax of a valid value for this option MUST follow RFC-2253 specifications. Namely the following components (with their accepted meaning) will be recognized. Note that the component name is case-insensitive:
677
678 @ftable @var
679 @item CN
680 The Common Name; e.g.@: @kbd{host.domain.com}
681 @item OU
682 The Organizational Unit; e.g.@: @kbd{IT Department}
683 @item O
684 The Organization Name; e.g.@: @kbd{The Sample Company}
685 @item L
686 The Locality Name; e.g.@: @kbd{Sydney}
687 @item ST
688 The State Name; e.g.@: @kbd{New South Wales}
689 @item C
690 The 2-letter Country identifier; e.g.@: @kbd{AU}
691 @end ftable
692
693 When specified with a @code{-dname} option, each pair of component/value will be separated from the other with a comma. Each component and value pair MUST be separated by an equal sign. For example, the following is a valid DN value:@*
694
695 @format
696 CN=host.domain.com, O=The Sample Company, L=Sydney, ST=NSW, C=AU
697 @end format
698 @*
699 If the @i{Distinguished Name} is required, and no valid default value can be used, the tool will prompt you to enter the information through the console.
700
701 @comment ----------------------------------------------------------------------
702
703 @node Add/Update Commands, Export Commands, Distinguished Names, keytool Tool
704 @comment node-name, next, previous, up
705 @c man begin OPTIONS gkeytool
706 @subsection Add/Update commands
707 @c man end
708
709 @menu
710 * Command -genkey::            Generate private key and self-signed certificate
711 * Command -import::            Import certificates and certificate replies
712 * Command -selfcert::          Generate self-signed certificate
713 * Command -cacert::            Import a CA Trusted Certificate
714 * Command -identitydb::        Import JDK-1 style identities
715 @end menu
716
717 @comment ----------------------------------------------------------------------
718
719 @node Command -genkey, Command -import, Add/Update Commands, Add/Update Commands
720 @comment node-name, next, previous, up
721 @c man begin OPTIONS gkeytool
722 @subsubsection The @option{-genkey} command
723
724 Use this command to generate a new key-pair (both private and public keys), and save these credentials in the key store as a @i{Key Entry}, associated with the designated (if was specified with the @option{-alias} option) or default (if the @option{-alias} option is omitted) @i{Alias}.
725
726 The private key material will be protected with a user-defined password (see @option{-keypass} option). The public key on the other hand will be part of a self-signed X.509 certificate, which will form a 1-element chain and will be saved in the key store.
727
728 @table @gcctabopt
729 @item -alias @var{ALIAS}
730 For more details @pxref{alias,, ALIAS}.
731
732 @item -keyalg @var{ALGORITHM}
733 For more details @pxref{keyalg,, ALGORITHM}.
734
735 @item -keysize @var{KEY_SIZE}
736 For more details @pxref{keysize,, KEY_SIZE}.
737
738 @item -sigalg @var{ALGORITHM}
739 The canonical name of the digital signature algorithm to use for signing certificates. If this option is omitted, a default value will be chosen based on the type of the key-pair; i.e., the algorithm that ends up being used by the -keyalg option. If the key-pair generation algorithm is @code{DSA}, the value for the signature algorithm will be @code{SHA1withDSA}. If on the other hand the key-pair generation algorithm is @code{RSA}, then the tool will use @code{MD5withRSA} as the signature algorithm.
740
741 @item -dname @var{NAME}
742 This a mandatory value for the command. If no value is specified --i.e.@: the @option{-dname} option is omitted-- the tool will prompt you to enter a @i{Distinguished Name} to use as both the @i{Owner} and @i{Issuer} of the generated self-signed certificate.
743
744 For more details @pxref{dn,, X.500 DISTINGUISHED NAME}.
745
746 @item -keypass @var{PASSWORD}
747 Use this option to specify the password which the tool will use to protect the newly created @i{Key Entry}.
748
749 If this option is omitted, you will be prompted to provide a password.
750
751 @item -validity @var{DAY_COUNT}
752 For more details @pxref{validity,, DAY_COUNT}.
753
754 @item -storetype @var{STORE_TYPE}
755 For more details @pxref{storetype,, STORE_TYPE}.
756
757 @item -keystore @var{URL}
758 For more details @pxref{keystore,, URL}.
759
760 @item -storepass @var{PASSWORD}
761 For more details @pxref{storepass,, PASSWORD}.
762
763 @item -provider @var{PROVIDER_CLASS_NAME}
764 For more details @pxref{provider,, PROVIDER_CLASS_NAME}.
765
766 @item -v
767 For more details @pxref{verbose}.
768
769 @end table
770 @c man end
771
772 @comment ----------------------------------------------------------------------
773
774 @node Command -import, Command -selfcert, Command -genkey, Add/Update Commands
775 @comment node-name, next, previous, up
776 @c man begin OPTIONS gkeytool
777 @subsubsection The @option{-import} command
778
779 Use this command to read an X.509 certificate, or a PKCS#7 @i{Certificate Reply} from a designated input source and incorporate the certificates into the key store.
780
781 If the @i{Alias} does not already exist in the key store, the tool treats the certificate read from the input source as a new @i{Trusted Certificate}. It then attempts to discover a chain-of-trust, starting from that certificate and ending at another @i{Trusted Certificate}, already stored in the key store. If the @option{-trustcacerts} option is present, an additional key store, of type @code{JKS} named @file{cacerts}, and assumed to be present in @file{$@{JAVA_HOME@}/lib/security} will also be consulted if found --@code{$@{JAVA_HOME@}} refers to the location of an installed @i{Java Runtime Environment} (JRE). If no chain-of-trust can be established, and unless the @code{-noprompt} option has been specified, the certificate is printed to @code{STDOUT} and the user is prompted for a confirmation.
782
783 If @i{Alias} exists in the key store, the tool will treat the certificate(s) read from the input source as a @i{Certificate Reply}, which can be a chain of certificates, that eventually would replace the chain of certificates associated with the @i{Key Entry} of that @i{Alias}. The substitution of the certificates only occurs if a chain-of-trust can be established between the bottom certificate of the chain read from the input file and the @i{Trusted Certificates} already present in the key store. Again, if the @option{-trustcacerts} option is specified, additional @i{Trusted Certificates} in the same @file{cacerts} key store will be considered. If no chain-of-trust can be established, the operation will abort.
784
785 @table @gcctabopt
786 @item -alias @var{ALIAS}
787 For more details @pxref{alias,, ALIAS}.
788
789 @item -file @var{FILE}
790 For more details @pxref{file,, FILE}.
791
792 @item -keypass @var{PASSWORD}
793 Use this option to specify the password which the tool will use to protect the @i{Key Entry} associated with the designated @i{Alias}, when replacing this @i{Alias}' chain of certificates with that found in the certificate reply.
794
795 If this option is omitted, and the chain-of-trust for the certificate reply has been established, the tool will first attempt to unlock the @i{Key Entry} using the same password protecting the key store. If this fails, you will then be prompted to provide a password.
796
797 @item -noprompt
798 Use this option to prevent the tool from prompting the user.
799
800 @item -trustcacerts
801 Use this option to indicate to the tool that a key store, of type @code{JKS}, named @file{cacerts}, and usually located in @file{lib/security} in an installed @i{Java Runtime Environment} should be considered when trying to establish chain-of-trusts.
802
803 @item -storetype @var{STORE_TYPE}
804 For more details @pxref{storetype,, STORE_TYPE}.
805
806 @item -keystore @var{URL}
807 For more details @pxref{keystore,, URL}.
808
809 @item -storepass @var{PASSWORD}
810 For more details @pxref{storepass,, PASSWORD}.
811
812 @item -provider @var{PROVIDER_CLASS_NAME}
813 For more details @pxref{provider,, PROVIDER_CLASS_NAME}.
814
815 @item -v
816 For more details @pxref{verbose}.
817
818 @end table
819 @c man end
820
821 @comment ----------------------------------------------------------------------
822
823 @node Command -selfcert, Command -cacert, Command -import, Add/Update Commands
824 @comment node-name, next, previous, up
825 @c man begin OPTIONS gkeytool
826 @subsubsection The @option{-selfcert} command
827
828 Use this command to generate a self-signed X.509 version 1 certificate. The newly generated certificate will form a chain of one element which will replace the previous chain associated with the designated @i{Alias} (if @option{-alias} option was specified), or the default @i{Alias} (if @option{-alias} option was omitted).
829
830 @table @gcctabopt
831 @item -alias @var{ALIAS}
832 For more details @pxref{alias,, ALIAS}.
833
834 @item -sigalg @var{ALGORITHM}
835 The canonical name of the digital signature algorithm to use for signing the certificate. If this option is omitted, a default value will be chosen based on the type of the private key associated with the designated @i{Alias}. If the private key is a @code{DSA} one, the value for the signature algorithm will be @code{SHA1withDSA}. If on the other hand the private key is an @code{RSA} one, then the tool will use @code{MD5withRSA} as the signature algorithm.
836
837 @item -dname @var{NAME}
838 Use this option to specify the @i{Distinguished Name} of the newly generated self-signed certificate. If this option is omitted, the existing @i{Distinguished Name} of the base certificate in the chain associated with the designated @i{Alias} will be used instead.
839
840 For more details @pxref{dn,, X.500 DISTINGUISHED NAME}.
841
842 @item -validity @var{DAY_COUNT}
843 For more details @pxref{validity,, DAY_COUNT}.
844
845 @item -keypass @var{PASSWORD}
846 Use this option to specify the password which the tool will use to unlock the @i{Key Entry} associated with the designated @i{Alias}.
847
848 If this option is omitted, the tool will first attempt to unlock the @i{Key Entry} using the same password protecting the key store. If this fails, you will then be prompted to provide a password.
849
850 @item -storetype @var{STORE_TYPE}
851 For more details @pxref{storetype,, STORE_TYPE}.
852
853 @item -keystore @var{URL}
854 For more details @pxref{keystore,, URL}.
855
856 @item -storepass @var{PASSWORD}
857 For more details @pxref{storepass,, PASSWORD}.
858
859 @item -provider @var{PROVIDER_CLASS_NAME}
860 For more details @pxref{provider,, PROVIDER_CLASS_NAME}.
861
862 @item -v
863 For more details @pxref{verbose}.
864
865 @end table
866 @c man end
867
868 @comment ----------------------------------------------------------------------
869
870 @node Command -cacert, Command -identitydb, Command -selfcert, Add/Update Commands
871 @comment node-name, next, previous, up
872 @c man begin OPTIONS gkeytool
873 @subsubsection The @option{-cacert} command
874
875 Use this command to import, a CA certificate and add it to the key store as a @i{Trusted Certificate}. The @i{Alias} for this new entry will be constructed from the FILE's base-name after replacing hyphens and dots with underscores.
876
877 This command is useful when used in a script that recursively visits a directory of CA certificates to populate a @code{cacerts.gkr} @i{Key Store} of trusted certificates which can then be used commands that specify the @option{-trustcacerts} option.
878
879 @table @gcctabopt
880 @item -file @var{FILE}
881 For more details @pxref{file,, FILE}.
882
883 @item -storetype @var{STORE_TYPE}
884 For more details @pxref{storetype,, STORE_TYPE}.
885
886 @item -keystore @var{URL}
887 For more details @pxref{keystore,, URL}.
888
889 @item -storepass @var{PASSWORD}
890 For more details @pxref{storepass,, PASSWORD}.
891
892 @item -provider @var{PROVIDER_CLASS_NAME}
893 For more details @pxref{provider,, PROVIDER_CLASS_NAME}.
894
895 @item -v
896 For more details @pxref{verbose}.
897
898 @end table
899 @c man end
900
901 @comment ----------------------------------------------------------------------
902
903 @node Command -identitydb, , Command -cacert, Add/Update Commands
904 @comment node-name, next, previous, up
905 @c man begin OPTIONS gkeytool
906 @subsubsection The @option{-identitydb} command
907
908 @b{NOT IMPLEMENTED YET}.
909
910 Use this command to import a JDK 1.1 style Identity Database.
911
912 @table @gcctabopt
913 @item -file @var{FILE}
914 For more details @pxref{file,, FILE}.
915
916 @item -storetype @var{STORE_TYPE}
917 For more details @pxref{storetype,, STORE_TYPE}.
918
919 @item -keystore @var{URL}
920 For more details @pxref{keystore,, URL}.
921
922 @item -storepass @var{PASSWORD}
923 For more details @pxref{storepass,, PASSWORD}.
924
925 @item -provider @var{PROVIDER_CLASS_NAME}
926 For more details @pxref{provider,, PROVIDER_CLASS_NAME}.
927
928 @item -v
929 For more details @pxref{verbose}.
930
931 @end table
932 @c man end
933
934 @comment ----------------------------------------------------------------------
935
936 @node Export Commands, Display Commands, Add/Update Commands, keytool Tool
937 @comment node-name, next, previous, up
938 @c man begin OPTIONS gkeytool
939 @subsection Export commands
940 @c man end
941
942 @menu
943 * Command -certreq::           Generate Certificate Signing Requests (CSR)
944 * Command -export::            Export a certificate in a Key Store
945 @end menu
946
947 @comment ----------------------------------------------------------------------
948
949 @node Command -certreq, Command -export, Export Commands, Export Commands
950 @comment node-name, next, previous, up
951 @c man begin OPTIONS gkeytool
952 @subsubsection The @option{-certreq} command
953
954 Use this command to generate a PKCS#10 @i{Certificate Signing Request} (CSR) and write it to a designated output destination. The contents of the destination should look something like the following:
955
956 @example
957 -----BEGIN NEW CERTIFICATE REQUEST-----
958 MI...QAwXzEUMBIGA1UEAwwLcnNuQGdudS5vcmcxGzAZBgNVBAoMElUg
959 Q2...A0GA1UEBwwGU3lkbmV5MQwwCgYDVQQIDANOU1cxCzAJBgNVBACC
960 ...
961 FC...IVwNVOfQLRX+O5kAhQ/a4RTZme2L8PnpvgRwrf7Eg8D6w==
962 -----END NEW CERTIFICATE REQUEST-----
963 @end example
964
965 @b{IMPORTANT}: Some documentation (e.g.@: RSA examples) claims that the @code{Attributes} field, in the CSR is @code{OPTIONAL} while RFC-2986 implies the opposite. This implementation considers this field, by default, as @code{OPTIONAL}, unless the option @option{-attributes} is specified on the command line.
966
967 @table @gcctabopt
968 @item -alias @var{ALIAS}
969 For more details @pxref{alias,, ALIAS}.
970
971 @item -sigalg @var{ALGORITHM}
972 The canonical name of the digital signature algorithm to use for signing the certificate. If this option is omitted, a default value will be chosen based on the type of the private key associated with the designated @i{Alias}. If the private key is a @code{DSA} one, the value for the signature algorithm will be @code{SHA1withDSA}. If on the other hand the private key is an @code{RSA} one, then the tool will use @code{MD5withRSA} as the signature algorithm.
973
974 @item -file @var{FILE}
975 For more details @pxref{file,, FILE}.
976
977 @item -keypass @var{PASSWORD}
978 Use this option to specify the password which the tool will use to unlock the @i{Key Entry} associated with the designated @i{Alias}.
979
980 If this option is omitted, the tool will first attempt to unlock the @i{Key Entry} using the same password protecting the key store. If this fails, you will then be prompted to provide a password.
981
982 @item -storetype @var{STORE_TYPE}
983 For more details @pxref{storetype,, STORE_TYPE}.
984
985 @item -keystore @var{URL}
986 For more details @pxref{keystore,, URL}.
987
988 @item -storepass @var{PASSWORD}
989 For more details @pxref{storepass,, PASSWORD}.
990
991 @item -provider @var{PROVIDER_CLASS_NAME}
992 For more details @pxref{provider,, PROVIDER_CLASS_NAME}.
993
994 @item -v
995 For more details @pxref{verbose}.
996
997 @item -attributes
998 Use this option to force the tool to encode a @code{NULL} DER value in the CSR as the value of the @code{Attributes} field.
999
1000 @end table
1001 @c man end
1002
1003 @comment ----------------------------------------------------------------------
1004
1005 @node Command -export, , Command -certreq, Export Commands
1006 @comment node-name, next, previous, up
1007 @c man begin OPTIONS gkeytool
1008 @subsubsection The @option{-export} command
1009
1010 Use this command to export a certificate stored in a key store to a designated output destination, either in binary format (if the @option{-v} option is specified), or in RFC-1421 compliant encoding (if the @option{-rfc} option is specified instead).
1011
1012 @table @gcctabopt
1013 @item -alias @var{ALIAS}
1014 For more details @pxref{alias,, ALIAS}.
1015
1016 @item -file @var{FILE}
1017 For more details @pxref{file,, FILE}.
1018
1019 @item -storetype @var{STORE_TYPE}
1020 For more details @pxref{storetype,, STORE_TYPE}.
1021
1022 @item -keystore @var{URL}
1023 For more details @pxref{keystore,, URL}.
1024
1025 @item -storepass @var{PASSWORD}
1026 For more details @pxref{storepass,, PASSWORD}.
1027
1028 @item -provider @var{PROVIDER_CLASS_NAME}
1029 For more details @pxref{provider,, PROVIDER_CLASS_NAME}.
1030
1031 @item -rfc
1032 Use RFC-1421 specifications when encoding the output.
1033
1034 @item -v
1035 Output the certificate in binary DER encoding. This is the default output format of the command if neither @option{-rfc} nor @code{-v} options were detected on the command line. If both this option and the @option{-rfc} option are detected on the command line, the tool will opt for the RFC-1421 style encoding.
1036
1037 @end table
1038 @c man end
1039
1040 @comment ----------------------------------------------------------------------
1041
1042 @node Display Commands, Management Commands, Export Commands, keytool Tool
1043 @comment node-name, next, previous, up
1044 @c man begin OPTIONS gkeytool
1045 @subsection Display commands
1046 @c man end
1047
1048 @menu
1049 * Command -list::              Display information about one or all Aliases
1050 * Command -printcert::         Print a certificate or a certificate fingerprint
1051 @end menu
1052
1053 @comment ----------------------------------------------------------------------
1054
1055 @node Command -list, Command -printcert, Display Commands, Display Commands
1056 @comment node-name, next, previous, up
1057 @c man begin OPTIONS gkeytool
1058 @subsubsection The @option{-list} command
1059
1060 Use this command to print one or all of a key store entries to @code{STDOUT}. Usually this command will only print a @i{fingerprint} of the certificate, unless either the @option{-rfc} or the @option{-v} option is specified.
1061
1062 @table @gcctabopt
1063 @item -alias @var{ALIAS}
1064 If this option is omitted, the tool will print ALL the entries found in the key store.
1065
1066 For more details @pxref{alias,, ALIAS}.
1067
1068 @item -storetype @var{STORE_TYPE}
1069 For more details @pxref{storetype,, STORE_TYPE}.
1070
1071 @item -keystore @var{URL}
1072 For more details @pxref{keystore,, URL}.
1073
1074 @item -storepass @var{PASSWORD}
1075 For more details @pxref{storepass,, PASSWORD}.
1076
1077 @item -provider @var{PROVIDER_CLASS_NAME}
1078 For more details @pxref{provider,, PROVIDER_CLASS_NAME}.
1079
1080 @item -rfc
1081 Use RFC-1421 specifications when encoding the output.
1082
1083 @item -v
1084 Output the certificate in human-readable format. If both this option and the @option{-rfc} option are detected on the command line, the tool will opt for the human-readable form and will not abort the command.
1085
1086 @end table
1087 @c man end
1088
1089 @comment ----------------------------------------------------------------------
1090
1091 @node Command -printcert, , Command -list, Display Commands
1092 @comment node-name, next, previous, up
1093 @c man begin OPTIONS gkeytool
1094 @subsubsection The @option{-printcert} command
1095
1096 Use this command to read a certificate from a designated input source and print it to @code{STDOUT} in a human-readable form.
1097
1098 @table @gcctabopt
1099 @item -file @var{FILE}
1100 For more details @pxref{file,, FILE}.
1101
1102 @item -v
1103 For more details @pxref{verbose}.
1104
1105 @end table
1106 @c man end
1107
1108 @comment ----------------------------------------------------------------------
1109
1110 @node Management Commands, , Display Commands, keytool Tool
1111 @comment node-name, next, previous, up
1112 @c man begin OPTIONS gkeytool
1113 @subsection Management commands
1114 @c man end
1115
1116 @menu
1117 * Command -keyclone::          Clone a Key Entry in a Key Store
1118 * Command -storepasswd::       Change the password protecting a Key Store
1119 * Command -keypasswd::         Change the password protecting a Key Entry
1120 * Command -delete::            Remove an entry in a Key Store
1121 @end menu
1122
1123 @comment ----------------------------------------------------------------------
1124
1125 @node Command -keyclone, Command -storepasswd, Management Commands, Management Commands
1126 @comment node-name, next, previous, up
1127 @c man begin OPTIONS gkeytool
1128 @subsubsection The @option{-keyclone} command
1129
1130 Use this command to clone an existing @i{Key Entry} and store it under a new (different) @i{Alias} protecting, its private key material with possibly a new password.
1131
1132 @table @gcctabopt
1133 @item -alias @var{ALIAS}
1134 For more details @pxref{alias,, ALIAS}.
1135
1136 @item -dest @var{ALIAS}
1137 Use this option to specify the new @i{Alias} which will be used to identify the cloned copy of the @i{Key Entry}.
1138
1139 @item -keypass @var{PASSWORD}
1140 Use this option to specify the password which the tool will use to unlock the @i{Key Entry} associated with the designated @i{Alias}.
1141
1142 If this option is omitted, the tool will first attempt to unlock the @i{Key Entry} using the same password protecting the key store. If this fails, you will then be prompted to provide a password.
1143
1144 @item -new @var{PASSWORD}
1145 Use this option to specify the password protecting the private key material of the newly cloned copy of the @i{Key Entry}.
1146
1147 @item -storetype @var{STORE_TYPE}
1148 For more details @pxref{storetype,, STORE_TYPE}.
1149
1150 @item -keystore @var{URL}
1151 For more details @pxref{keystore,, URL}.
1152
1153 @item -storepass @var{PASSWORD}
1154 For more details @pxref{storepass,, PASSWORD}.
1155
1156 @item -provider @var{PROVIDER_CLASS_NAME}
1157 For more details @pxref{provider,, PROVIDER_CLASS_NAME}.
1158
1159 @item -v
1160 For more details @pxref{verbose}.
1161
1162 @end table
1163 @c man end
1164
1165 @comment ----------------------------------------------------------------------
1166
1167 @node Command -storepasswd, Command -keypasswd, Command -keyclone, Management Commands
1168 @comment node-name, next, previous, up
1169 @c man begin OPTIONS gkeytool
1170 @subsubsection The @option{-storepasswd} command
1171
1172 Use this command to change the password protecting a key store.
1173
1174 @table @gcctabopt
1175 @item -new @var{PASSWORD}
1176 The new, and different, password which will be used to protect the designated key store.
1177
1178 @item -storetype @var{STORE_TYPE}
1179 For more details @pxref{storetype,, STORE_TYPE}.
1180
1181 @item -keystore @var{URL}
1182 For more details @pxref{keystore,, URL}.
1183
1184 @item -storepass @var{PASSWORD}
1185 For more details @pxref{storepass,, PASSWORD}.
1186
1187 @item -provider @var{PROVIDER_CLASS_NAME}
1188 For more details @pxref{provider,, PROVIDER_CLASS_NAME}.
1189
1190 @item -v
1191 For more details @pxref{verbose}.
1192
1193 @end table
1194 @c man end
1195
1196 @comment ----------------------------------------------------------------------
1197
1198 @node Command -keypasswd, Command -delete, Command -storepasswd, Management Commands
1199 @comment node-name, next, previous, up
1200 @c man begin OPTIONS gkeytool
1201 @subsubsection The @option{-keypasswd} command
1202
1203 Use this command to change the password protecting the private key material of a designated @i{Key Entry}.
1204
1205 @table @gcctabopt
1206 @item -alias @var{ALIAS}
1207 For more details @pxref{alias,, ALIAS}.
1208
1209 Use this option to specify the password which the tool will use to unlock the @i{Key Entry} associated with the designated @i{Alias}.
1210
1211 If this option is omitted, the tool will first attempt to unlock the @i{Key Entry} using the same password protecting the key store. If this fails, you will then be prompted to provide a password.
1212
1213 @item -new @var{PASSWORD}
1214 The new, and different, password which will be used to protect the private key material of the designated @i{Key Entry}.
1215
1216 @item -storetype @var{STORE_TYPE}
1217 For more details @pxref{storetype,, STORE_TYPE}.
1218
1219 @item -keystore @var{URL}
1220 For more details @pxref{keystore,, URL}.
1221
1222 @item -storepass @var{PASSWORD}
1223 For more details @pxref{storepass,, PASSWORD}.
1224
1225 @item -provider @var{PROVIDER_CLASS_NAME}
1226 For more details @pxref{provider,, PROVIDER_CLASS_NAME}.
1227
1228 @item -v
1229 For more details @pxref{verbose}.
1230
1231 @end table
1232 @c man end
1233
1234 @comment ----------------------------------------------------------------------
1235
1236 @node Command -delete, , Command -keypasswd, Management Commands
1237 @comment node-name, next, previous, up
1238 @c man begin OPTIONS gkeytool
1239 @subsubsection The @option{-delete} command
1240
1241 Use this command to delete a designated key store entry.
1242
1243 @table @gcctabopt
1244 @item -alias @var{ALIAS}
1245 For more details @pxref{alias,, ALIAS}.
1246
1247 @item -storetype @var{STORE_TYPE}
1248 For more details @pxref{storetype,, STORE_TYPE}.
1249
1250 @item -keystore @var{URL}
1251 For more details @pxref{keystore,, URL}.
1252
1253 @item -storepass @var{PASSWORD}
1254 For more details @pxref{storepass,, PASSWORD}.
1255
1256 @item -provider @var{PROVIDER_CLASS_NAME}
1257 For more details @pxref{provider,, PROVIDER_CLASS_NAME}.
1258
1259 @item -v
1260 For more details @pxref{verbose}.
1261
1262 @end table
1263 @c man end
1264
1265 @comment ----------------------------------------------------------------------
1266
1267 @node Other Tools, I18N Issues, Security Tools, Top
1268 @comment node-name, next, previous, up
1269 @chapter Other Tools
1270
1271 This is a list of currently undocumented classpath tools: @b{jar},
1272 @b{javah}, @b{gcjh}, @b{native2ascii}, @b{orbd}, @b{serialver}, @b{rmid}, @b{rmiregistry}
1273 and @b{tnameserv}.
1274
1275 @menu
1276 * jar Tool::                   Archive tool for Java archives
1277 * javah Tool::                 A java header compiler
1278 * gcjh Tool::                  A java header compiler (old version)
1279 * native2ascii Tool::          An encoding converter
1280 * orbd Tool::                  An object request broker daemon
1281 * serialver Tool::             A serial version command
1282 * rmid Tool::                  RMI activation daemon
1283 * rmiregistry Tool::           Remote object registry
1284 * tnameserv Tool::             Naming service
1285 * gjdoc Tool::                 A documentation generator
1286 @end menu
1287
1288 @comment ----------------------------------------------------------------------
1289
1290 @node jar Tool, javah Tool, , Other Tools
1291 @comment node-name, next, previous, up
1292 @section The @command{jar} Tool
1293 @c man title gjar - Archive tool for Java archives
1294
1295 @c man begin DESCRIPTION gjar
1296
1297 @command{gjar} is an implementation of Sun's jar utility that comes with
1298 the JDK.
1299
1300 If any file is a directory then it is processed recursively.  The
1301 manifest file name and the archive file name needs to be specified in
1302 the same order the @option{-m} and @option{-f} flags are specified.
1303
1304 @c man end
1305
1306 @ignore
1307 @c man begin SYNOPSIS gjar
1308 gjar @option{-ctxui} [@var{OPTIONS}] @var{jar-file} [@option{-C} @var{DIR} @var{FILE}] @var{FILE}@dots{}
1309 @c man end
1310 @end ignore
1311
1312 @c man begin OPTIONS gjar
1313
1314 Operation mode:
1315
1316 @table @gcctabopt
1317 @item -c
1318 Create new archive.
1319
1320 @item -t
1321 List table of contents for archive.
1322
1323 @item -x
1324 Extract named (or all) files from archive.
1325
1326 @item -u
1327 Update existing archive.
1328
1329 @item -i @var{FILE}
1330 Compute archive index.
1331 @end table
1332
1333 Operation modifiers:
1334
1335 @table @gcctabopt
1336 @item -f @var{FILE}
1337 Specify archive file name.
1338
1339 @item -0
1340 Store only; use no ZIP compression.
1341
1342 @item -v
1343 Generate verbose output on standard output.
1344
1345 @item -M
1346 Do not create a manifest file for the entries.
1347
1348 @item -m @var{manifest}
1349 Include manifest information from specified @var{manifest} file.
1350 @end table
1351
1352 File name selection:
1353
1354 @table @gcctabopt
1355 @item -C @var{DIR} @var{FILE}
1356 Change to the @var{DIR} and include the following @var{FILE}.
1357
1358 @item -@@
1359 Read the names of the files to add to the archive from stdin.  This
1360 option is supported only in combination with @option{-c} or @option{-u}.
1361 Non standard option added in the GCC version.
1362 @end table
1363
1364 Standard options:
1365
1366 @table @gcctabopt
1367 @item -help
1368 Print help text, then exit.
1369 @item -version
1370 Print version number, then exit.
1371 @item -J@var{OPTION}
1372 Pass argument to the Java runtime.
1373 @end table
1374
1375 @c man end
1376
1377 @c man begin SEEALSO gjar
1378 java(1), @dots{}
1379 @c man end
1380
1381 @comment ----------------------------------------------------------------------
1382
1383 @node javah Tool, gcjh Tool, jar Tool, Other Tools
1384 @comment node-name, next, previous, up
1385 @section The @command{javah} Tool
1386 @c man title gjavah - generate header files from Java class files
1387
1388 @c man begin DESCRIPTION gjavah
1389
1390 The @command{gjavah} program is used to generate header files from class
1391 files.  It can generate both CNI and JNI header files, as well as stub
1392 implementation files which can be used as a basis for implementing the
1393 required native methods.
1394
1395 @c man end
1396
1397 @ignore
1398 @c man begin SYNOPSIS gjavah
1399 gjavah @dots{}
1400 @c man end
1401 @end ignore
1402
1403 @c man begin OPTIONS gjavah
1404
1405 @table @gcctabopt
1406 @item -d @var{DIR}
1407 Set output directory.
1408
1409 @item -o @var{FILE}
1410 Set output file (only one of @option{-d} or @option{-o} may be used).
1411
1412 @item -cmdfile @var{FILE}
1413 Read command file.
1414
1415 @item -all @var{DIR}
1416 Operate on all class files under directory @var{DIR}.
1417
1418 @item -stubs
1419 Emit stub implementation.
1420
1421 @item -jni
1422 Emit JNI stubs or header (default).
1423
1424 @item -cni
1425 Emit CNI stubs or header (default JNI).
1426
1427 @item -verbose
1428 Set verbose mode.
1429
1430 @item -force
1431 Output files should always be written.
1432 @end table
1433
1434 Class path options:
1435 @table @gcctabopt
1436 @item -classpath @var{PATH}
1437 Set the class path.
1438
1439 @item -I@var{DIR}
1440 Add directory to class path.
1441
1442 @item -bootclasspath @var{PATH}
1443 Set the boot class path.
1444
1445 @item -extdirs @var{PATH}
1446 Set the extension directory path.
1447 @end table
1448
1449 Standard options:
1450 @table @gcctabopt
1451 @item -help
1452 Print help text, then exit.
1453 @item -version
1454 Print version number, then exit.
1455 @item -J@var{OPTION}
1456 Pass argument to the Java runtime.
1457 @end table
1458 @c man end
1459
1460 @c man begin SEEALSO gjavah
1461 javac(1), @dots{}
1462 @c man end
1463
1464 @comment ----------------------------------------------------------------------
1465
1466 @node gcjh Tool, native2ascii Tool, javah Tool, Other Tools
1467 @comment node-name, next, previous, up
1468 @section The @command{gcjh} Tool
1469 @c man title gcjh - generate header files from Java class files
1470
1471 @c man begin DESCRIPTION gcjh
1472
1473 The @code{gcjh} program is used to generate header files from class
1474 files.  It can generate both CNI and JNI header files, as well as stub
1475 implementation files which can be used as a basis for implementing the
1476 required native methods.  It is similar to @code{javah} but has
1477 slightly different command line options, and defaults to CNI.
1478
1479 @c man end
1480
1481 @ignore
1482 @c man begin SYNOPSIS gcjh
1483 gcjh [@var{OPTIONS}]@dots{} @var{CLASS}@dots{}
1484 @c man end
1485 @end ignore
1486
1487 @c man begin OPTIONS gcjh
1488
1489 See @code{javah} for a full description; this page only lists the
1490 additional options provided by @code{gcjh}.
1491
1492 CNI text options
1493 @table @gcctabopt
1494 @item -add @var{text}
1495 Insert @var{text} into class body.
1496 @item -append @var{text}
1497 Append @var{text} after class declaration.
1498 @item -friend @var{text}
1499 Insert @var{text} as a @code{friend} declaration.
1500 @item -prepend @var{text}
1501 Insert @var{text} before start of class.
1502 @end table
1503
1504 Compatibility options (unused)
1505 @table @gcctabopt
1506 @item -td @var{DIR}
1507 @itemx -M
1508 @itemx -MM
1509 @itemx -MD
1510 @itemx -MMD
1511 Unused compatibility option.
1512 @end table
1513
1514
1515 Standard options:
1516 @table @gcctabopt
1517 @item -help
1518 Print help text, then exit.
1519 @item -version
1520 Print version number, then exit.
1521 @item -J@var{OPTION}
1522 Pass argument to the Java runtime.
1523 @end table
1524 @c man end
1525
1526 @c man begin SEEALSO gcjh
1527 javac(1), javah(1), @dots{}
1528 @c man end
1529
1530 @comment ----------------------------------------------------------------------
1531
1532 @node native2ascii Tool, orbd Tool, gcjh Tool, Other Tools
1533 @comment node-name, next, previous, up
1534 @section The @command{native2ascii} Tool
1535 @c man title gnative2ascii - An encoding converter
1536
1537 @c man begin DESCRIPTION gnative2ascii
1538
1539 To be written @dots{}
1540
1541 @c man end
1542
1543 @ignore
1544 @c man begin SYNOPSIS gnative2ascii
1545 gnative2ascii [@var{OPTIONS}]@dots{} [@var{INPUTFILE} [@var{OUTPUTFILE}]]
1546 @c man end
1547 @end ignore
1548
1549 @c man begin OPTIONS gnative2ascii
1550
1551 @table @gcctabopt
1552 @item -encoding @var{NAME}
1553 Set the encoding to use.
1554
1555 @item -reversed
1556 Convert from encoding to native.
1557 @end table
1558
1559 Standard options:
1560 @table @gcctabopt
1561 @item -help
1562 Print help text, then exit.
1563 @item -version
1564 Print version number, then exit.
1565 @item -J@var{OPTION}
1566 Pass argument to the Java runtime.
1567 @end table
1568
1569 @c man end
1570
1571 @c man begin SEEALSO gnative2ascii
1572 javac(1), @dots{}
1573 @c man end
1574
1575 @comment ----------------------------------------------------------------------
1576
1577 @node orbd Tool, serialver Tool, native2ascii Tool, Other Tools
1578 @comment node-name, next, previous, up
1579 @section The @command{orbd} object request broker daemon
1580 @c man title gorbd - An object request broker daemon
1581
1582 @c man begin DESCRIPTION gorbd
1583
1584 To be written @dots{}
1585
1586 @c man end
1587
1588 @ignore
1589 @c man begin SYNOPSIS gorbd
1590 gorbd @dots{}
1591 @c man end
1592 @end ignore
1593
1594 @c man begin OPTIONS gorbd
1595
1596 @table @gcctabopt
1597 @item -ORBInitialPort @var{PORT}
1598 Port on which persistent naming service is to be started.
1599
1600 @item -ior @var{FILE}
1601 File in which to store persistent naming service's IOR reference
1602
1603 @item -directory @var{DIR}
1604 Directory in which to store persistent data.
1605
1606 @item -restart
1607 Restart persistent naming service, clearing persistent naming
1608 database.
1609 @end table
1610
1611 Standard options:
1612 @table @gcctabopt
1613 @item -help
1614 Print help text, then exit.
1615 @item -version
1616 Print version number, then exit.
1617 @item -J@var{OPTION}
1618 Pass argument to the Java runtime.
1619 @end table
1620
1621 @c man end
1622
1623 @c man begin SEEALSO gorbd
1624 java(1), @dots{}
1625 @c man end
1626
1627 @comment ----------------------------------------------------------------------
1628
1629 @node serialver Tool, rmid Tool, orbd Tool, Other Tools
1630 @comment node-name, next, previous, up
1631 @section The @command{serialver} version command
1632 @c man title gserialver version command
1633
1634 @c man begin DESCRIPTION gserialver
1635
1636 Print the serialVersionUID of the specified classes.
1637
1638 @c man end
1639
1640 @ignore
1641 @c man begin SYNOPSIS gserialver
1642 gserialver [@var{OPTIONS}]@dots{} @var{CLASS}@dots{}
1643 @c man end
1644 @end ignore
1645
1646 @c man begin OPTIONS gserialver
1647
1648 @table @gcctabopt
1649 @item -classpath @var{PATH}
1650 Class path to use to find classes.
1651 @end table
1652
1653 Standard options:
1654 @table @gcctabopt
1655 @item -help
1656 Print help text, then exit.
1657 @item -version
1658 Print version number, then exit.
1659 @item -J@var{OPTION}
1660 Pass argument to the Java runtime.
1661 @end table
1662
1663 @c man end
1664
1665 @c man begin SEEALSO gserialver
1666 javac(1), @dots{}
1667 @c man end
1668
1669 @comment ----------------------------------------------------------------------
1670
1671 @node rmid Tool, rmiregistry Tool, serialver Tool, Other Tools
1672 @comment node-name, next, previous, up
1673 @section The @command{rmid} RMI activation system daemon
1674 @c man title grmid - RMI activation system daemon
1675
1676 @c man begin DESCRIPTION grmid
1677
1678 @command{rmiregistry} starts a remote object registry on the current
1679 host.  If no port number is specified, then port 1099 is used.
1680
1681 @c man end
1682
1683 @ignore
1684 @c man begin SYNOPSIS grmid
1685 grmid [@var{OPTIONS}]@dots{}
1686 @c man end
1687 @end ignore
1688
1689 @c man begin OPTIONS grmid
1690
1691 Activation process control:
1692 @table @gcctabopt
1693 @item -port @var{PORT}
1694 Port on which activation system is to be started.
1695
1696 @item -restart
1697 Restart activation system, clearing persistent naming database, if
1698 any.
1699
1700 @item -stop
1701 Stop activation system.
1702 @end table
1703
1704 Persistence:
1705 @table @gcctabopt
1706 @item -persistent
1707 Make activation system persistent.
1708
1709 @item -directory @var{DIR}
1710 Directory in which to store persistent data.
1711 @end table
1712
1713 Debugging:
1714 @table @gcctabopt
1715 @item -verbose
1716 Log binding events to standard out.
1717 @end table
1718
1719 Standard options:
1720 @table @gcctabopt
1721 @item -help
1722 Print help text, then exit.
1723 @item -version
1724 Print version number, then exit.
1725 @item -J@var{OPTION}
1726 Pass argument to the Java runtime.
1727 @end table
1728
1729 @c man end
1730
1731 @c man begin SEEALSO grmid
1732 java(1), @dots{}
1733 @c man end
1734
1735 @comment ----------------------------------------------------------------------
1736
1737 @node rmiregistry Tool, tnameserv Tool, rmid Tool, Other Tools
1738 @comment node-name, next, previous, up
1739 @section The @command{rmiregistry} Tool
1740 @c man title grmiregistry - Remote object registry
1741
1742 @c man begin DESCRIPTION grmiregistry
1743
1744 @command{grmiregistry} starts a remote object registry on the current
1745 host.  If no port number is specified, then port 1099 is used.
1746
1747 @c man end
1748
1749 @ignore
1750 @c man begin SYNOPSIS grmiregistry
1751 grmiregistry [@var{OPTIONS}]@dots{} @var{PORT}
1752 @c man end
1753 @end ignore
1754
1755 @c man begin OPTIONS grmiregistry
1756
1757 Registry process control:
1758 @table @gcctabopt
1759 @item -restart
1760 Restart RMI naming service, clearing persistent naming database, if
1761 any.
1762
1763 @item -stop
1764 Stop RMI naming service.
1765 @end table
1766
1767 Persistence:
1768 @table @gcctabopt
1769 @item -persistent
1770 Make RMI naming service persistent.
1771
1772 @item -directory @var{DIR}
1773 Directory in which to store persistent data.
1774 @end table
1775
1776 Debugging:
1777 @table @gcctabopt
1778 @item -verbose
1779 Log binding events to standard out.
1780 @end table
1781
1782 Standard options:
1783 @table @gcctabopt
1784 @item -help
1785 Print help text, then exit.
1786 @item -version
1787 Print version number, then exit.
1788 @item -J@var{OPTION}
1789 Pass argument to the Java runtime.
1790 @end table
1791
1792 @c man end
1793
1794 @c man begin SEEALSO grmiregistry
1795 java(1), @dots{}
1796 @c man end
1797
1798 @comment ----------------------------------------------------------------------
1799
1800 @node tnameserv Tool, gjdoc Tool, rmiregistry Tool, Other Tools
1801 @comment node-name, next, previous, up
1802 @section The @command{tnameserv} Tool
1803 @c man title gtnameserv Naming service
1804
1805 @c man begin DESCRIPTION gtnameserv
1806
1807 To be written @dots{}
1808
1809 @c man end
1810
1811 @ignore
1812 @c man begin SYNOPSIS gtnameserv
1813 tnameserv [@var{OPTIONS}]
1814 @c man end
1815 @end ignore
1816
1817 @c man begin OPTIONS gtnameserv
1818
1819 @table @gcctabopt
1820 @item -ORBInitialPort @var{PORT}
1821 Port on which naming service is to be started.
1822
1823 @item -ior @var{FILE}
1824 File in which to store naming service's IOR reference.
1825 @end table
1826
1827 Standard options:
1828 @table @gcctabopt
1829 @item -help
1830 Print help text, then exit.
1831 @item -version
1832 Print version number, then exit.
1833 @item -J@var{OPTION}
1834 Pass argument to the Java runtime.
1835 @end table
1836
1837 @c man end
1838
1839 @c man begin SEEALSO gtnameserv
1840 java(1), @dots{}
1841 @c man end
1842
1843 @comment ----------------------------------------------------------------------
1844
1845 @ignore
1846 @c man begin SYNOPSIS gjdoc
1847 gjdoc [@option{-sourcepath }@var{pathlist}]
1848       [@option{-all}] [@option{-subpackages }@var{pkg:pkg:@dots{}}] [@option{-exclude }@var{pkglist}]
1849       [@option{-encoding }@var{charset}] [@option{-locale }@var{name}] [@option{-source }@var{release}]
1850       [@option{-public}] [@option{-protected}] [@option{-package}] [@option{-private}] 
1851       [@option{-doctitle }@var{text}] [@option{-header }@var{text}] [@option{-footer }@var{text}] [@option{-bottom }@var{text}]
1852       [@option{-link }@var{url}] [@option{-linkoffline }@var{url} @var{path}] [@option{-noqualifier }@var{pkg:pkg:@dots{}}] 
1853       [@option{-tagletpath }@var{pathlist}] [@option{-taglet }@var{className}] [@option{-tag }@var{tagspec}]
1854       [@option{-use}] [@option{-linksource}] [@option{-splitindex}] [@option{-noindex}] [@option{-notree}] 
1855       [@option{-version}] [@option{-author}] [@option{-nosince}] [@option{-addstylesheet }@var{file}]
1856       [@option{-d }@var{targetdir}] 
1857       [@var{packages}@dots{}] [@var{sourcefiles}@dots{}] [@@@var{cmdfile}]
1858
1859 gjdoc [@option{-sourcepath }@var{pathlist}]
1860       [@option{-all}] [@option{-subpackages }@var{pkg:pkg:@dots{}}] [@option{-exclude }@var{pkglist}]
1861       [@option{-encoding }@var{charset}] [@option{-locale }@var{name}] [@option{-source }@var{release}]
1862       [@option{-public}] [@option{-protected}] [@option{-package}] [@option{-private}] 
1863       [@option{-docletpath }@var{pathlist}] [@option{-doclet }@var{className}]
1864       [@var{packages}@dots{}] [@var{sourcefiles}@dots{}] [@@@var{cmdfile}]
1865       [doclet options]
1866
1867 gjdoc @option{--help}
1868
1869 gjdoc @option{--version}
1870
1871 Only the most useful options are listed here; see below for the
1872 remainder.
1873 @c man end
1874 @end ignore
1875 @c man begin SEEALSO gjdoc
1876 Info entry for @file{gjdoc}.
1877 @c man end
1878 @c man begin BUGS gjdoc
1879 Please report bugs to @w{@uref{http://savannah.gnu.org/bugs/?group=classpath}}.
1880 @c man end
1881 @c man begin AUTHOR gjdoc
1882 Julian Scheid
1883 @c man end
1884
1885 @node gjdoc Tool, , tnameserv Tool, Other Tools
1886 @chapter Generating HTML Documentation
1887 @cindex Gjdoc command options
1888 @cindex command options
1889 @cindex options, Gjdoc command
1890
1891 @c man begin DESCRIPTION gjdoc
1892 Gjdoc can be used in two ways: as a stand-alone documentation tool, or
1893 as a driver for a user-specified Doclet. @xref{Other Doclets}.
1894
1895 In the default mode, Gjdoc will use the Standard Doclet
1896 @samp{HtmlDoclet} to generate a set of HTML pages.  The canonical
1897 usage is:
1898
1899 @smallexample
1900 gjdoc -s src/java/ -all -d api-docs/
1901 @end smallexample
1902
1903 Here, @samp{src/java/} is the root of your source code class
1904 hierarchy, @option{-all} means that all valid Java files found under
1905 this root directory should be processed, and @samp{api-docs/} is the
1906 directory where the generated documentation should be placed.
1907
1908 To learn more about running Doclets other than the Standard Doclet,
1909 refer to the manual.  @xref{Invoking a Custom Doclet}.
1910
1911 @menu
1912 * Invoking the Standard Doclet::   How to generate HTML documentation.
1913 * Invoking a Custom Doclet::       How to run third-party and other 
1914                                    built-in Doclets.
1915
1916 * Option Summary by Type::         Brief list of all options, grouped by type.
1917 * Gjdoc Option Summary::           List of all options accepted by Gjdoc.
1918
1919 * Source Set Options::      Select the set of source codes to run Gjdoc on.
1920 * Source Format Options::   Specify the format of the source codes to document.
1921
1922 * Interlinking Options::    Connection your documentation with other projects.
1923 * Output Control Options::  Specify the target directory and locale, and more.
1924 * Generation Options::       Select which pieces of information to generate.
1925 * Decoration Options::      Add or modify some titles, headers and footers or
1926                               override/amend static resources like stylesheets.
1927 * Taglet Options::          Define your own javadoc @@tags
1928
1929 * Virtual Machine Options::
1930 * Verbosity Options::
1931 * Doclet Options::
1932
1933 * Other Doclets::                  Generating Other Output Types
1934 * Gjdoc Concepts::                 Advanced Concepts
1935
1936 @end menu
1937
1938 @c man end
1939
1940 @comment ----------------------------------------------------------------------
1941
1942 @node Invoking the Standard Doclet, Invoking a Custom Doclet, , gjdoc Tool
1943 @section Invoking the Standard Doclet
1944 @cindex Gjdoc command options
1945 @cindex command options
1946 @cindex options, Gjdoc command
1947
1948 Running the Gjdoc Standard Doclet @samp{HtmlDoclet} is the default
1949 mode of operation for Gjdoc.  This section lists the command line
1950 options you can specify in this mode.  It doesn't distinguish between
1951 general Gjdoc options and options specific to the Standard Doclet.
1952
1953 If you want to learn which options are accepted when Gjdoc is used as
1954 a doclet driver, @xref{Invoking a Custom Doclet}.
1955
1956 @menu
1957 * Source Set Options::      Select the set of source codes to run Gjdoc on.
1958 * Source Format Options::   Specify the format of the source codes to document.
1959
1960 * Output Control Options::  Specify the target directory and locale, and more.
1961 * Generation Options::       Select which pieces of information to generate.
1962 * Decoration Options::      Add or modify some titles, headers and footers or
1963                               override/amend static resources like stylesheets.
1964 * Taglet Options::          Define your own javadoc @@tags
1965
1966 * Virtual Machine Options::
1967 * Doclet Options::
1968
1969 @end menu
1970
1971 @c man begin OPTIONS gjdoc
1972
1973 @node Option Summary by Type, Gjdoc Option Summary, Invoking a Custom Doclet, gjdoc Tool
1974 @section Option Summary by Type
1975
1976 Here is a summary of all the options of both Gjdoc and the Standard
1977 Doclet, grouped by type.  Explanations are in the following sections.
1978
1979 @table @emph
1980 @item Source Set Options
1981 @xref{Source Set Options,,Options For Specifying the Source Files To Operate on}.
1982 @gccoptlist{-sourcepath @var{pathlist}  -subpackages @var{pkglist}  -exclude @var{pkglist}}
1983
1984 @item Source Format Options
1985 @xref{Source Format Options,,Options For Specifying the Source Format}.
1986 @gccoptlist{-source @var{release}  -encoding @var{encoding}  -breakiterator}
1987
1988 @item Interlinking Options
1989 @xref{Interlinking Options,,Options For Specifying the Source Files To Operate on}.
1990 @gccoptlist{-link @var{url}  -linkoffline @var{url} @var{file}  -noqualifier @var{pkg:pkg:...}}
1991
1992 @item Generation Options
1993 @xref{Generation Options,,Options Controlling What is Included in the Output}.
1994 @gccoptlist{-author  -licensetext  -use  -version  -splitindex  -noindex
1995  -nodeprecated  -nodeprecatedlist  -nohelp  -nonavbar
1996  -nosince  -notree  -public  -protected  -package  -private
1997  -docfilessubdirs  -excludedocfilessubdir @var{dirname}
1998  -linksource}
1999
2000 @item Output Options
2001 @xref{Generation Options,,Options Controlling the Output}.
2002 @gccoptlist{-d  -locale @var{name}  -charset @var{charset}  -docencoding @var{charset}
2003  -validhtml  -baseurl @var{url}}
2004
2005 @item Decoration Options
2006 @gccoptlist{-windowtitle @var{text}  -doctitle @var{text}  -title @var{text}  
2007  -header @var{text}  -footer @var{text}  -bottom @var{text}
2008  -helpfile @var{file}  -stylesheetfile @var{file}  -addstylesheet @var{file}
2009  -group @var{groupheading} @var{pkgpattern:pkgpattern:@dots{}}}
2010
2011 @item Taglet Options
2012 @xref{Taglet Options,,Options For Specifying user-defined Taglets}.
2013 @gccoptlist{-tagletpath  -taglet @var{classname}  -tag @var{tagspec}}
2014
2015 @item Doclet Options
2016 @xref{Doclet Options,,Options For Specifying the Doclet to use}.
2017 @gccoptlist{-docletpath  -doclet @var{classname}}
2018
2019 @item Verbosity Options
2020 @xref{Verbosity Options,,Options Controlling Gjdoc Behavior}.
2021 @gccoptlist{-quiet  -verbose}
2022
2023 @item Virtual Machine Options
2024 @xref{Virtual Machine Options,,Options Controlling Gjdoc Behavior}.
2025 @gccoptlist{-classpath}  @gccoptlist{-bootclasspath}  @gccoptlist{-J}@var{vmopt}
2026
2027 @end table
2028
2029 @menu
2030 * Virtual Machine Options::     Controlling the kind of output:
2031                         an executable, object files, assembler files,
2032                         or preprocessed source.
2033 @end menu
2034
2035 @node Source Set Options, Source Format Options, Gjdoc Option Summary, gjdoc Tool
2036 @section Selecting which Source Files to Process
2037
2038 @table @gcctabopt
2039 @item -s @var{pathlist}
2040 @item -sourcepath @var{pathlist}
2041 Look for source files in the specified directory or directories.
2042
2043 @var{pathlist} should be one or more directory paths separated by your
2044 platform's path separator (usually @samp{:} or @samp{;}).
2045
2046 If this option is not given, @command{gjdoc} will look for source
2047 files in the current directory.
2048
2049 The directories specified should be root directories in terms of the
2050 Java package system.  For example, if you want to generate
2051 documentation for classes in package @samp{foo.bar}, you must specify
2052 the directory containing the top-level @samp{@file{foo}}
2053 sub-directory, not the directory @samp{@file{foo/bar/}} in which the
2054 Java source files reside.
2055
2056 The short-hand alias @option{-s} is specific to @command{gjdoc} and
2057 not compatible to Sun @command{javadoc}.
2058
2059 @item -all
2060 @emph{[EXPERIMENTAL]}
2061 Process all valid Java source files found in the directories listed in
2062 the source path and their sub-directories.
2063
2064 This is an option specific to @command{gjdoc} and not compatible to
2065 Sun @command{javadoc}.
2066
2067 @item -subpackages @var{pkg:pkg:@dots{}}
2068 Process the classes in the given Java packages and all sub-packages,
2069 recursively.  Note that multiple package names must be separated with
2070 colons instead of whitespace.
2071
2072 @item -exclude @var{pkg:pkg:@dots{}}
2073 Do not process classes in the given Java packages and all
2074 sub-packages, recursively.  This option can be used in conjunction
2075 with @option{-all} or @option{-subpackages} in order to exclude
2076 individual packages or package sub-trees from the output.
2077
2078 @item @var{packages}@dots{}
2079 Process all classes in the given Java packages.
2080
2081 @item @var{sourcefiles}@dots{}
2082 Process the classes in the given Java source files.
2083 @end table
2084
2085 @node Source Format Options, Interlinking Options, Source Set Options, gjdoc Tool
2086 @section Specifying the Format of Input Files
2087
2088 @table @gcctabopt
2089 @item -source @var{release}
2090 Assume that the source files are targeted at the given release of the
2091 Java platform.
2092
2093 @var{release} should be the version number of a Java platform release
2094 in the format MAJOR.MINOR, for example @samp{1.4}.
2095
2096 This option is currently ignored except that an error is raised if a
2097 release number other than @samp{1.2}, @samp{1.3} or @samp{1.4} is
2098 specified.
2099
2100 @item -encoding @var{charset}
2101 Assume that the source files are encoded using @var{charset}.
2102
2103 Examples for @var{charset} are @samp{US-ASCII}, @samp{ISO-8859-1} or
2104 @samp{UTF-8}.
2105
2106 The semantics of @var{charset} are identical to those of @samp{java.nio.charset.Charset.forName(String)}.
2107
2108 @item -breakiterator
2109 Use the locale's java.text.BreakIterator instead of the internal
2110 first sentence detector.
2111
2112 By default, @command{gjdoc} uses an internal algorithm to determine
2113 where a sentence ends. When this option is given, it will instead use
2114 the @samp{java.text.BreakIterator} instance for the locale given with
2115 @option{-locale} (or the default locale).
2116
2117 This option should be specified when applying @command{gjdoc} to
2118 source code commented in a non-latin language for which the default
2119 first sentence detector does not work. For all other cases, the
2120 default (do not use BreakIterator) produces better results at the time
2121 of this writing.
2122 @end table
2123
2124 @node Interlinking Options, Output Control Options, Source Format Options, gjdoc Tool
2125 @section Interlinking with other Documentation Sets
2126
2127 @table @gcctabopt
2128 @item -link @var{url}
2129
2130 Create hyperlinks to another documentation set.
2131
2132 By default, @command{gjdoc} will only create hyperlinks to classes in
2133 the source set.  Use this option to additionally create hyperlinks to
2134 classes covered by the specified documentation set.
2135
2136 @var{url} should be the root URL of the other documentation set. For
2137 example, to add hyperlinks to GNU Classpath, specify the following:
2138
2139 @smallexample
2140 -link http://developer.classpath.org/doc/
2141 @end smallexample
2142
2143 The @option{-link} option can be specified multiple times.
2144
2145 Note that specifying the @option{-link} option will cause an HTTP
2146 access every time gjdoc is invoked. You can use @option{-linkoffline}
2147 instead to avoid this access.
2148
2149 @item -linkoffline @var{url} @var{file}
2150
2151 Create hyperlinks to another documentation set which is also present
2152 on the local file system.
2153
2154 This option works exactly like @option{-link}, except that it accesses
2155 the local file system instead of the network for determining which
2156 classes are covered by the linked documentation set.
2157
2158 When using @option{-linkoffline} the remote documentation set is not
2159 accessed at all, which can significantly speed up generation time
2160 depending on your network connection.  The generated hyperlinks to the
2161 documentation set however refer to the remote set, not to the local
2162 one, so that you can distribute the documentation without any further
2163 dependencies.
2164
2165 The @option{-linkoffline} option can be specified multiple times.
2166
2167 @item -noqualifier @var{pkg:pkg:@dots{}}
2168
2169 Do not qualify names of classes in the given packages with their
2170 package name.
2171
2172 By default, a class name is displayed unqualified only if the class is
2173 part of the source set or a linked documentation set, and qualified
2174 with the name of its containing package if it is not. You can use this
2175 option to force unqualified names for classes even if they are not
2176 part of the documentation set.
2177
2178 For example, usually a reference to the String class is represented
2179 fully-qualified as @samp{java.lang.String} (unless you link to the
2180 appropriate documentation set using @option{-link}) because it isn't
2181 part of the documentation set.  You can specify @samp{-noqualifier
2182 java.lang} to render the same references just as @samp{String}.
2183
2184 Note that for all unqualified class names, a tooltip is provided when
2185 you place your mouse pointer over it in the HTML documentation.
2186
2187 @item -noqualifier @samp{all}
2188 Omit package name qualifier from all class names.
2189
2190 Specify this option to omit package name qualifiers altogether,
2191
2192 @end table
2193
2194 @node Generation Options, Decoration Options, Output Control Options, gjdoc Tool
2195 @section Selecting which Information to Generate
2196
2197 @table @gcctabopt
2198 @item -public
2199 Only include public members of public classes in the output.  By
2200 default, protected class members are included as well.
2201
2202 @item -protected
2203
2204 Include public or protected members of public classes in the output.
2205 This is the default.
2206
2207 @item -package
2208
2209 Include public, protected and package-private members of public and
2210 package-private classes.
2211
2212 @item -private
2213
2214 Include all classes and class members regardless of their access
2215 level.
2216
2217 @item -splitindex
2218 Generate one index page per letter instead of a single, monolithic
2219 index page.
2220
2221 By default, the index created by the Standard Doclet contains all
2222 entries on a single page.  This is fine for small documentation sets,
2223 but for large sets you should specify this option.
2224
2225 @item -nosince
2226 Ignore @samp{@@since} tags in javadoc comments.
2227
2228 By default, the generated output contains sections listing the version
2229 of your API since which the package, class or class member in question
2230 exists when this tag is encountered.  Specify this option to omit this
2231 information.
2232
2233 @item -notree
2234 Do not generate any tree pages.
2235
2236 By default, the generated output includes one inheritance tree per
2237 package, and - if the documentation set consists of multiple packages
2238 - a page with the full inheritance tree.  Specify this option to omit
2239 generation of these pages.
2240
2241 @item -noindex
2242 Do not output the alphabetical index.
2243
2244 By default, gjdoc generates an alphabetical index of all program
2245 elements in the documentation set (packages, classes, inner classes,
2246 constructors, methods, and fields).  Specify this option to omit this
2247 information.
2248
2249 @item -nohelp
2250 Do not generate the help page.
2251
2252 This option is currently ignored as the Standard Doclet doesn't
2253 provide a help page.
2254
2255 @item -nodeprecated
2256 Do not output inline information about deprecated packages, classes or
2257 class members.
2258
2259 By default, the Standard Doclet adds a highlighted paragraph with
2260 deprecation information to the description of each deprecated program
2261 element.  Specify this option to omit this information.
2262
2263 @item -nodeprecatedlist
2264 Do not output the summary page for deprecated API elements.
2265
2266 By default, the Standard Doclet generates a page listing all
2267 deprecated API elements along with a deprecation description which
2268 usually includes the reason for deprecation and possible
2269 alternatives.  Specify this option to omit this information.
2270
2271 @item -nonavbar
2272 Do not output the navigation bar, header, and footer.
2273
2274 By default, each output page is equipped with a top navigation bar
2275 (which may include a user-specified header) and a bottom navigation
2276 bar (which may include a user-specified footer).  Specify this option
2277 to omit this decoration.
2278
2279 @item -nocomment
2280
2281 Omit all documentation text from the generated files and output only
2282 declarations and program element relationships.
2283
2284 This option is here for compatibility with @command{javadoc}.  If you
2285 plan on extracting information about your project via @command{gjdoc},
2286 you should consider using a different Doclet for your purposes
2287 instead, for example XmlDoclet.  You could also use the Doclet API
2288 directly by implementing a new Doclet.
2289
2290 @item -linksource
2291
2292 Generate a page with syntax-highlighted source code for each class.
2293 By default, this page is not generated.
2294
2295 The source code can be accessed by clicking on the button labelled
2296 "Source" in the navigation bar, or by clicking on the name of a
2297 constructor, field, method, or inner class in the detail section of a
2298 class documentation page.
2299
2300 @item -use
2301
2302 Generate a page with cross-reference information. By default, this
2303 page is not generated.
2304
2305 The cross-reference information can be accessed by clicking on the
2306 button labelled `Use' in the navigation bar.
2307
2308 The `Use' page lists all classes/interfaces in the documentation set
2309 that extend/implement the class (type) in question; fields of the
2310 type; methods or constructors accepting a parameter of the type;
2311 methods returning the type; and methods or constructors throwing the
2312 type.
2313
2314 @item -author
2315 Include author information in the output.
2316
2317 When specified, author information as specified using the
2318 @samp{@@author} tag in javadoc comments is incorporated into the
2319 output. By default, @samp{@@author} tags are ignored.
2320
2321 @item -version
2322 Include version information in the output.
2323
2324 When specified, version information as specified using the
2325 @samp{@@version} tag in javadoc comments is incorporated into the
2326 output. By default, @samp{@@version} tags are ignored.
2327
2328 @item -licensetext
2329
2330 Assume that the first comment in each source file contains the license
2331 text, and add license information to the footer of each generated
2332 class page.
2333
2334 This is an option specific to @command{gjdoc} and not compatible to
2335 Sun @command{javadoc}.
2336
2337 This option is intended for use with free and open source projects
2338 where source code is typically prefixed with a boilerplate license
2339 comment, when there are legal reasons for including the license in the
2340 documentation.
2341
2342 @item -docfilessubdirs
2343
2344 Recursively copy all files in the @file{doc-files} sub-directory of each
2345 package directory.
2346
2347 Usually, only the files in the @file{doc-files} sub-directory are copied
2348 without descending recursively.
2349
2350 @xref{Adding Custom Resources}.
2351
2352 @item -excludedocfilessubdir @var{name}:@var{name}:@dots{}
2353
2354 Do not copy some directories directly under the @file{doc-files}
2355 sub-directories when descending recursively.
2356
2357 The argument to this option should be a colon-separated list of
2358 directory names.
2359
2360 This option only makes sense if @option{-docfilessubdirs} is also
2361 specified.  In this case, any sub-directory located directly beneath a
2362 @file{doc-files} directory is omitted if listed.
2363
2364 @end table
2365
2366 @node Taglet Options, Virtual Machine Options, Decoration Options, gjdoc Tool
2367 @section Custom Documentation Tags
2368
2369 @table @gcctabopt
2370 @item -tagletpath @var{pathlist}
2371 Search @var{pathlist} when loading subsequent Taglet classes specified
2372 using @option{-taglet}.
2373
2374 @var{pathlist} should be one or more paths to a directory or jar file,
2375 separated by your platform's path separator (usually @samp{:} or
2376 @samp{;}).
2377
2378 @item -taglet @var{classname}
2379 Register a Taglet.
2380
2381 @var{classname} should be the fully-qualified name of a Java class
2382 implementing @samp{com.sun.tools.doclets.Taglet}.
2383
2384 The Taglet classes will be loaded from the classpath specified using
2385 @option{-tagletpath}, from the classpath specified using
2386 @option{-classpath} and from the default classpath.
2387
2388 See the documentation of @samp{com.sun.tools.doclets.Taglet} for
2389 further information.
2390
2391 Note that for simple tags, there is also @option{-tag}.
2392
2393 @item -tag @var{tagspec}
2394 Register a generic Taglet.
2395
2396 The format of @var{tagspec} must be @samp{<tagname>:<flags>:"<taghead>"}.
2397
2398 @var{tagname} is the tag name to match, without the leading @@ sign. 
2399
2400 @var{flags} is one or more of the following characters, where each
2401 character specifies a source code context in which the tag is to be
2402 recognized.
2403
2404 @table @gcctabopt
2405 @item a  
2406 all contexts
2407 @item c  
2408 constructors
2409 @item f  
2410 fields
2411 @item m  
2412 methods
2413 @item o  
2414 overview
2415 @item p  
2416 packages
2417 @item t  
2418 types (classes, interfaces, exceptions, errors)
2419 @item X  
2420 special character which temporarily disables the
2421 Taglet altogether.
2422 @end table
2423
2424 @var{taghead} is the string to display in the header of the section
2425 devoted to the tag in question.
2426
2427 For example, to define a tag matching @samp{@@cvsid} which is to be
2428 accepted in overview, package and type pages and which is labelled
2429 with the header @samp{CVS ID}, you would specify:
2430
2431 @smallexample
2432 -tag cvsid:tpo:"CVS ID"
2433 @end smallexample
2434
2435 Let's say that a class javadoc comment contains
2436
2437 @smallexample
2438 @@cvsid $Id: cp-tools.texinfo,v 1.7 2008/08/13 13:32:05 jsumali Exp $
2439 @end smallexample
2440
2441 Then the HTML output will contain something like
2442
2443 @smallexample
2444 CVS ID:
2445   $Id: cp-tools.texinfo,v 1.7 2008/08/13 13:32:05 jsumali Exp $
2446 @end smallexample
2447 @end table
2448
2449 @node Doclet Options, Other Doclets, Verbosity Options, gjdoc Tool
2450 @section Running Other Doclets
2451
2452 @table @gcctabopt
2453
2454 @item -docletpath @var{pathlist}
2455 Search @var{pathlist} when loading classes for the Doclet specified
2456 using @option{-doclet}.
2457
2458 @var{pathlist} should be one or more paths to a directory or jar file,
2459 separated by your platform's path separator (usually @samp{:} or
2460 @samp{;}).
2461
2462 @item -doclet @var{className}
2463 Run the specified doclet instead of the standard HtmlDoclet.
2464
2465 @var{className} should be the fully-qualified name of a class which
2466 has a public default constructor and contain a method with the
2467 following signature:
2468
2469 @smallexample
2470    import com.sun.javadoc.RootDoc;
2471    public static boolean start(RootDoc rootDoc) 
2472 @end smallexample
2473
2474 The Doclet classes will be loaded from the classpath specified using
2475 @option{-docletpath}, from the classpath specified using
2476 @option{-classpath} and from the default classpath.
2477
2478 The @samp{start} method should process the information exposed by the
2479 Doclet API via @samp{rootDoc} and return @samp{true} on success,
2480 @samp{false} on failure.
2481
2482 If you are using a third-party doclet, refer to its documentation for
2483 further instructions.  Note that support for third-party doclets is
2484 experimental.  Please report any problems you encounter, or provide
2485 feedback when successfully running third-party applets.
2486
2487 This option can be specified multiple times, in which case all doclets
2488 are executed with the same information tree exposed via the Doclet API
2489 for each Doclet run.
2490
2491 @end table
2492
2493 @node Decoration Options, Taglet Options, Generation Options, gjdoc Tool
2494 @section Adding Information to the Output
2495
2496 @table @gcctabopt
2497 @item -windowtitle @var{text}
2498 Use @var{text} as the browser window title prefix.
2499
2500 When specified, the browser window title for each page will be
2501 prefixed with @var{text} instead of the default string @samp{Generated
2502 API Documentation}.
2503
2504 @var{text} should be plain text (it should not contain HTML tags).
2505
2506 @item -doctitle @var{text}
2507 Set the header text of the overview page to @var{text}.
2508
2509 @var{text} should be a short plain text string.
2510
2511 When generating documentation for a single package, specifying this
2512 option forces generation of the overview page.
2513
2514 @item -header @var{htmltext}
2515
2516 Add @var{htmltext} to the right upper corner of every generated page.
2517 @var{htmltext} is usually set to the name of the project being
2518 documented.
2519
2520 @item -footer @var{htmltext}
2521
2522 Add @var{htmltext} to the right bottom corner of every generated page.
2523 @var{htmltext} is often set to the same value as for @option{-header}.
2524
2525 @item -bottom @var{htmltext}
2526
2527 Add @var{htmltext} to the very bottom of every generated page,
2528 spanning the whole width of the page.  When specified, @var{htmltext}
2529 usually consists of a copyright notice and/or links to other project
2530 pages.
2531
2532 @item -addstylesheet @var{file}
2533
2534 Augment the default CSS style sheets with the user-specified
2535 stylesheet @var{file}.
2536
2537 The given stylesheet is simply loaded by each HTML page in addition to
2538 the default ones, as the last stylesheet.
2539
2540 Note that the CSS cascading rules apply.  That is, your style
2541 properties will only be assigned if they have a higher cascading order
2542 than @command{gjdoc}'s default style.  One simple way to make sure
2543 that this is the case is to declare your overrides @samp{!important}.
2544
2545 See @w{@uref{http://www.w3.org/TR/REC-CSS2/cascade.html#cascading-order}}.
2546
2547 @item -group @var{heading} @var{pkgwildcard}:@var{pkgwildcard}:@dots{}
2548
2549 Arrange the given packages in a separate group on the overview page.
2550
2551 The first argument should be a short plain text which is used as the
2552 title of the package group.  The second argument should be a
2553 colon-separated list of package wildcards.  The group will consist of
2554 all packages in the documentation set whose name matches any of the
2555 given wildcards.
2556
2557 There is only one wildcard character, @samp{*}, which matches both
2558 letters in package name components and the @samp{.} separating package
2559 name components.  For example, @samp{j*regex} would match package
2560 @samp{java.util.regex}.  A more useful example would be
2561 @samp{javax.swing*} to match @samp{javax.swing} and all of its
2562 sub-packages.
2563
2564 This option can be given multiple times.  
2565
2566 FIXME: Information about group nesting here.
2567
2568 @smallexample
2569 gjdoc -group "Core Classes" 'java*' \
2570       -group "Swing" 'javax.swing*' \
2571       -group "XML APIs" 'javax.xml*' \
2572       -group "Other Extensions" javax* \
2573       @dots{}
2574 @end smallexample
2575
2576 @item -overview @var{file}
2577
2578 Add the XHTML body fragment from @var{file} to the overview page.
2579
2580 @var{file} should contain an XHTML fragment with the HTML @samp{body}
2581 tag as the root node.  @xref{XHTML Fragments}.
2582
2583 This option can be used to supply a description of the documentation
2584 set as a whole.
2585
2586 When specified, the first sentence of the fragment will be put above
2587 the tables listing the documented packages, along with a link to the
2588 full copy of the fragment which is put below the tables.
2589 @xref{First Sentence Detector}.
2590
2591 When generating documentation for a single package, specifying this
2592 option forces generation of the overview page.
2593
2594 @item -stylesheetfile @var{file}
2595
2596 Use the CSS stylesheet in @var{file} instead of the default CSS
2597 stylesheets.
2598
2599 If you only want to override parts of the default stylesheets, use
2600 @option{-addstylesheet} instead.
2601
2602 @item -title @var{text}
2603
2604 @emph{Deprecated.} Use @option{-doctitle} @var{text} instead.
2605
2606 @item -helpfile @var{file}
2607
2608 This option is currently ignored.
2609
2610 When implemented, it will use the XHTML fragment in @var{file} for the
2611 help page contents instead of the default help text.
2612
2613 @end table
2614
2615 @node Output Control Options, Generation Options, Interlinking Options, gjdoc Tool
2616 @section Controlling the Output.
2617
2618 @table @gcctabopt
2619 @item -d @var{directory}
2620 Place all output files into @var{directory} (and
2621 sub-directories). @var{directory} will be created if it does not
2622 exist, including all non-existing parent directories and all required
2623 sub-directories.
2624
2625 If not specified, output will be placed into the current directory.
2626
2627 @item -locale @var{name}
2628
2629 Use locale @var{name} instead of the default locale for all purposes.
2630
2631 @var{name} should be a locale specifier in the form @samp{ll_CC[_VAR]}
2632 where @samp{ll} is a lowercase two-letter ISO-639 language code,
2633 @samp{CC} is an optional uppercase two-letter ISO-3166 country code,
2634 and @samp{VAR} is an optional variant code.  For example, @samp{en}
2635 specifies English, @samp{en_US} specifies US English, and
2636 @samp{en_US_WIN} specifies a deviant variant of the US English locale.
2637
2638 Note that the semantics of this option correspond exactly to those of
2639 the constructors of class @samp{java.util.Locale}.
2640
2641 This option currently only determines which Collator is being used for
2642 sorting output elements.  This means that the locale will only have an
2643 effect when you are using non-ASCII characters in identifiers.
2644
2645 @item -charset @var{charset}
2646
2647 @emph{Deprecated.} Override the specified encoding in output XHTML
2648 files with the one given by @samp{charset}.
2649
2650 If this option is not given, the encoding specification in output
2651 XHTML is chosen to match the encoding used when writing the file (the
2652 encoding given with @option{-docencoding}, or your platform's default
2653 encoding).
2654
2655 The semantics for @var{charset} are specified here:
2656 @w{@uref{http://www.w3.org/TR/2000/REC-xml-20001006#NT-EncName}}.  For
2657 all practical purposes, they are identical to those of the other
2658 options accepting charset parameters.
2659
2660 This option is here for compatibility with @command{javadoc} and
2661 should be avoided.
2662
2663 @item -docencoding @var{charset}
2664
2665 Use the given charset encoding when writing output files instead of
2666 your platform's default encoding.
2667
2668 Examples for @var{charset} are @samp{US-ASCII}, @samp{ISO-8859-1} or
2669 @samp{UTF-8}.
2670
2671 The semantics of this option correspond exactly to those of the
2672 constructors of class @samp{java.util.Locale}.
2673
2674 @item -validhtml
2675
2676 Force generation of valid XHTML code.  This breaks compatibility to
2677 the traditional Javadoc tool to some extent.
2678
2679 If this option is specified, anchor names will be mangled so that they
2680 are valid according to the XHTML 1.1 specification.  However, a
2681 documentation set generated with this option cannot be linked to
2682 properly using the traditional Javadoc tool.  It can be linked to just
2683 fine using Gjdoc, though.
2684
2685 Without this option, anchor names for executable class members use the
2686 traditional format, for example: ``foo(String,int[])''.  This is
2687 compatible to the traditional Javadoc tool, but according to both the
2688 HTML 4.0 and XHTML 1.0 and 1.1 specifications, this format includes
2689 illegal characters.  Parentheses, square brackets, and the comma are
2690 not allowed in anchor names.
2691
2692 @item -baseurl @var{url}
2693
2694 Hardwire a page URL relative to @var{url} into each generated page.
2695
2696 If you are generating documentation which will exclusively be
2697 available at a certain URL, you should use this option to specify this
2698 URL.
2699
2700 This can help avoid certain redirect attacks used by spammers, and it
2701 can be helpful for certain web clients.
2702
2703 @end table
2704
2705 @node Verbosity Options, Doclet Options, Virtual Machine Options, gjdoc Tool
2706 @section Verbosity Options
2707
2708 @table @gcctabopt
2709 @item -quiet
2710 Suppress all output except for warnings and error messages.
2711
2712 @item -verbose
2713 Be very verbose about what @command{gjdoc} is doing.
2714
2715 This option is currently ignored.
2716
2717 @end table
2718
2719 @node Virtual Machine Options, Verbosity Options, Taglet Options, gjdoc Tool
2720 @section Virtual Machine Options
2721
2722 Sun's @command{javadoc} tool seems to be based on @command{javac} and
2723 as such it seems to operate on the VM level.  @command{gjdoc}, in
2724 contrast, is a pure Java application.
2725
2726 Therefore, @command{gjdoc} can only fake, or simulate, the following
2727 VM-level options.
2728
2729 @table @gcctabopt
2730
2731 @item -classpath @var{pathlist}
2732 Set the Virtual Machine @samp{classpath} to @var{pathlist}.
2733
2734 In most cases you should use @option{-docletpath} or
2735 @option{-tagletpath} instead of this option.
2736
2737 @var{pathlist} should be one or more paths to a directory or jar file,
2738 separated by your platform's path separator (usually @samp{:} or
2739 @samp{;}).
2740
2741 If this option is not intercepted at the wrapper level,
2742 @command{gjdoc} currently fakes it by calling
2743 @samp{System.setProperty("java.class.path", @var{pathlist});} and
2744 outputs a warning.
2745
2746 @item -bootclasspath @var{pathlist}
2747 Set the Virtual Machine @samp{bootclasspath} to @var{pathlist}.
2748
2749 If this option is not intercepted at the wrapper level,
2750 @command{gjdoc} outputs a warning.
2751
2752 @item -J@var{vmopt}
2753
2754 Pass an arbitrary parameter to the Virtual Machine @command{gjdoc}
2755 runs on.
2756
2757 If this option is not intercepted at the wrapper level,
2758 @command{gjdoc} tries to emulate the option and outputs a warning.
2759
2760 Currently, only the VM option @option{-D} for setting system
2761 properties is emulated.
2762
2763 @end table
2764
2765 @c man end
2766
2767 @comment ----------------------------------------------------------------------
2768
2769 @node Invoking a Custom Doclet, Option Summary by Type, Invoking the Standard Doclet, gjdoc Tool
2770 @section Invoking a Custom Doclet
2771
2772 For invoking one of the other doclets shipping with @command{gjdoc} or
2773 a third-party doclet, the canonical usage is:
2774
2775 @smallexample
2776 gjdoc -s src/java/ -all \
2777   -docletpath /path/to/doclet.jar -doclet foo.BarDoclet \
2778   (more Gjdoc core options and Doclet-specific options here)
2779 @end smallexample
2780
2781 @samp{/path/to/doclet.jar} is a placeholder for a class path
2782 specifying where the Doclet classes and dependencies can be found and
2783 @samp{foo.BarDoclet} is the fully-qualified name of the Doclet's main
2784 class.
2785
2786 @comment ----------------------------------------------------------------------
2787
2788 @node Gjdoc Option Summary, Source Set Options, Option Summary by Type, gjdoc Tool
2789 @section Gjdoc Option Summary
2790 @cindex Gjdoc Options
2791
2792 @comment ----------------------------------------------------------------------
2793
2794 @node Other Doclets, Gjdoc Concepts, Doclet Options, gjdoc Tool
2795 @chapter Generating Other Output Types
2796
2797 @menu
2798 * Built-in Doclets::
2799 * Third-party Doclets::
2800 @end menu
2801
2802 @comment ----------------------------------------------------------------------
2803
2804 @node Built-in Doclets, Third-party Doclets, , Other Doclets
2805 @section Using the Built-in Doclets
2806 @cindex Built-in Doclets
2807
2808 @menu
2809 * Using XmlDoclet::
2810 * Using TexiDoclet::
2811 * Using IspellDoclet::
2812 * Using DebugDoclet::
2813 @end menu
2814
2815 @comment ----------------------------------------------------------------------
2816
2817 @node Using TexiDoclet, Using XmlDoclet, , Built-in Doclets
2818 @subsection TexiDoclet: Generating Info, PDF, and other formats
2819 @cindex TexiDoclet
2820
2821 Missing.
2822
2823 @comment ----------------------------------------------------------------------
2824
2825 @node Using XmlDoclet, Using IspellDoclet, Using TexiDoclet, Built-in Doclets
2826 @subsection XmlDoclet: Generating XML Documentation
2827 @cindex HtmlDoclet
2828
2829 Missing.
2830
2831 @comment ----------------------------------------------------------------------
2832
2833 @node Using IspellDoclet, Using DebugDoclet, Using XmlDoclet, Built-in Doclets
2834 @subsection IspellDoclet: Spell-checking Source Code
2835 @cindex IspellDoclet
2836
2837 Missing.
2838
2839 @comment ----------------------------------------------------------------------
2840
2841 @node Using DebugDoclet, , Using IspellDoclet, Built-in Doclets
2842 @subsection DebugDoclet: Inspecting the Doclet API
2843 @cindex HtmlDoclet
2844
2845 Missing.
2846
2847 @comment ----------------------------------------------------------------------
2848
2849 @node Third-party Doclets, , Built-in Doclets, Other Doclets
2850 @section Using Third-Party Doclets
2851 @cindex Third-party Doclets
2852
2853 @menu
2854 * DocBook Doclet::
2855 * PDFDoclet::
2856 * JUnitDoclet::
2857 @end menu
2858
2859 @comment ----------------------------------------------------------------------
2860
2861 @node DocBook Doclet,PDFDoclet, ,Third-party Doclets
2862 @subsection DocBook Doclet
2863 @cindex DocBook Doclet
2864
2865 Missing.
2866
2867 @comment ----------------------------------------------------------------------
2868
2869 @node PDFDoclet, JUnitDoclet, DocBook Doclet, Third-party Doclets
2870 @subsection PDFDoclet
2871 @cindex PDFDoclet
2872
2873 Missing.
2874
2875 @comment ----------------------------------------------------------------------
2876
2877 @node JUnitDoclet, , PDFDoclet, Third-party Doclets
2878 @subsection JUnitDoclet
2879 @cindex JUnitDoclet
2880
2881 Missing.
2882
2883 @comment ----------------------------------------------------------------------
2884
2885 @node Gjdoc Concepts, , Other Doclets, gjdoc Tool
2886 @chapter Advanced Concepts
2887
2888 @menu
2889 * Writing Doclets::
2890 * Taglets::
2891 * XHTML Fragments::
2892 * First Sentence Detector::
2893 * Adding Custom Resources::
2894 @end menu
2895
2896 @comment ----------------------------------------------------------------------
2897
2898 @node Taglets, Writing Doclets, , Gjdoc Concepts
2899 @section Adding Custom Tags to the Documentation
2900 @cindex Taglet
2901
2902 Missing.
2903
2904 @comment ----------------------------------------------------------------------
2905
2906 @node Writing Doclets, XHTML Fragments, Taglets, Gjdoc Concepts
2907 @section Writing Doclets
2908 @cindex Taglet
2909
2910 If the various Doclets already available don't suit your needs, you
2911 can write a custom Doclet yourself.  
2912
2913 @menu
2914 * Doclet Invocation Interface::
2915 * Using AbstractDoclet::
2916 * GNU Doclet SPI::
2917 @end menu
2918
2919 @comment ----------------------------------------------------------------------
2920
2921 @node Doclet Invocation Interface, Using AbstractDoclet, , Writing Doclets
2922 @subsection Implementing the Doclet Invocation Interface
2923
2924 A Doclet is a class that contains a method with the following
2925 signature:
2926
2927 @smallexample
2928 public static boolean start(RootDoc rootDoc);
2929 @end smallexample
2930
2931 @var{rootDoc} is the root of an object hierarchy containing the
2932 information @command{gjdoc} extracted from the source files.  See the
2933 Doclet API for more details.
2934
2935 @samp{start} should process all the information and return
2936 @samp{true} on success, @samp{false} on failure.
2937
2938 For printing status information, the Doclet should use methods
2939 @samp{printNotice}, @samp{printWarning} and @samp{printError} instead
2940 of @samp{System.err}.  The Doclet can opt to use @samp{System.out} for
2941 redirectable output.
2942
2943 @comment ----------------------------------------------------------------------
2944
2945 @node Using AbstractDoclet, GNU Doclet SPI, Doclet Invocation Interface, Writing Doclets
2946 @subsection Deriving Your Doclet from AbstractDoclet
2947 @cindex AbstractDoclet
2948
2949 You may want your Doclet to provide functionality similar to
2950 HtmlDoclet.  For example, you may want it to support Taglets, generate
2951 Index, Tree, and Uses pages, or show other cross-reference information
2952 like @samp{Overrides} and @samp{All Implementing Classes}.
2953
2954 This information is not directly provided by the Doclet API, so your
2955 Doclet would normally have to assemble it itself.  For example, it
2956 would have to add the names of all program elements to a list and sort
2957 this list in order to create the Index page.
2958
2959 If you want to provide this information or part of it, you should
2960 consider deriving your class from
2961 @samp{gnu.classpath.tools.doclets.AbstractDoclet}.  This class
2962 provides the following benefits:
2963
2964 @itemize @bullet
2965
2966 @item 
2967 Handles options @option{-tag}, @option{-taglet}, @option{-tagletpath}
2968 (Taglets)
2969
2970 @item 
2971 Provides standard taglets for @@version, @@author, @@since, @@serial,
2972 @@deprecated, @@see, @@param, @@return and handles all related options
2973 (@option{-version}, @option{-author}, @option{-nosince},
2974 @option{-nodeprecated})
2975
2976 @item 
2977 Handles option @option{-d} (destination directory)
2978
2979 @item 
2980 Handles option @option{-noqualifier} (classes to omit qualifier for)
2981
2982 @item 
2983 Handles options @option{-docfilessubdirs} and
2984 @option{-excludedocfilessubdir} (resource copying)
2985
2986 @item 
2987 Can generate a full index or an index split by first letter
2988
2989 @item 
2990 Can generate a full tree and package trees
2991
2992 @item 
2993 Can generate cross-reference information
2994
2995 @item 
2996 Can aggregate interface information (all superinterfaces, all
2997 subinterfaces, all implementing classes)
2998
2999 @item 
3000 Provides convenient access to constructors, fields, methods, and inner
3001 classes sorted by name/signature instead of the default sort order.
3002
3003 @item 
3004 Provides various other convenience methods
3005
3006 @end itemize
3007
3008 If you derive from @samp{AbstractDoclet}, there are a number of things
3009 you need to take care of:
3010
3011 @itemize @bullet
3012
3013 @item 
3014
3015 @end itemize
3016
3017 you should not implement the
3018 @samp{start(RootDoc)} method as it is already defined by
3019 @samp{AbstractDoclet} so that it can care about parsing the options.
3020
3021 Instead, you implement method @samp{run()}, @samp{getOptions()} and
3022 the other abstract methods to define your Doclet's behavior.
3023
3024 Note that all information provided by @samp{AbstractDoclet} is
3025 evaluated lazily.  That is, if your Doclet doesn't need to create an
3026 Index page, then @samp{AbstractDoclet} will not spend resources on
3027 creating the corresponding information.
3028
3029 See the API documentation for
3030 @samp{gnu.classpath.tools.doclets.AbstractDoclet} for more details.
3031
3032 You should be aware that if you base your Doclet on
3033 @samp{AbstractDoclet} then you have to bundle this and all related
3034 classes with your Doclet, with all implications such as possible
3035 licensing issues.  Otherwise, your Doclet will only be runnable on
3036 @samp{gjdoc} and not on other documentation systems.  Also note that
3037 @samp{AbstractDoclet} has not been extensively tested in environments
3038 other than @samp{gjdoc}.
3039
3040 @comment ----------------------------------------------------------------------
3041
3042 @node GNU Doclet SPI, , Using AbstractDoclet, Writing Doclets
3043 @subsection Preparing for the GNU Doclet Service Provider Interface
3044 @cindex GNU Doclet SPI, Service Provider, SPI
3045
3046 In addition to the standard Doclet invocation interface described
3047 above, @command{gjdoc} also offers a Service Provider Interface
3048 conforming to the Java standard.  Adding support for this interface to
3049 your Doclet simplifies usage for @command{gjdoc} users because it
3050 makes your Doclet ``discoverable''.
3051
3052 In order to provide the alternate interface, you have to add a class
3053 implementing @samp{gnu.classpath.tools.gjdoc.spi.DocletSpi} to your
3054 Doclet classes, and bundle all Doclet classes in a Jar file along with
3055 a file named
3056 @samp{META_INF/services/gnu.classpath.tools.gjdoc.spi.DocletSpi} which
3057 contains the name of your class implementing DocletSpi on a single
3058 line.
3059
3060 Note that if your Doclet depends on third-party classes bundled in
3061 separate Jar files, you can link in these classes using the
3062 @samp{Class-path:} Manifest attribute of your Doclet Jar.
3063
3064 Your Doclet can then be invoked in one of the following ways:
3065 @smallexample
3066 gjdoc -docletjar /path/to/doclet.jar
3067 gjdoc -docletpath /path/to/doclet.jar -docletname @var{docletname}
3068 gjdoc -docletname @var{docletname}
3069 @end smallexample
3070
3071 Here, @var{docletname} is the name of your doclet as returned by
3072 @samp{DocletSpi.getDocletName()}.
3073
3074 The last example will only work if your Doclet Jar is in
3075 @command{gjdoc}'s @file{doclets} directory or if it is on the
3076 classpath.
3077
3078 @comment ----------------------------------------------------------------------
3079
3080 @node XHTML Fragments, First Sentence Detector, Writing Doclets, Gjdoc Concepts
3081 @section Well-formed Documentation Fragments
3082 @cindex XHTML Fragments
3083
3084 For many Doclets it is advantagous if the HTML code in the comments
3085 and HTML code passed via the command line is well-formed.  For
3086 example, HtmlDoclet outputs XHTML code, and XmlDoclet XML code, both
3087 of which results in invalid files if the user-specified HTML isn't
3088 wellformed.
3089
3090 Unfortunately, comments were never required to contain well-formed
3091 HTML code, which means that every Doclet must deal with non-wellformed
3092 code as well.
3093
3094 The @command{gjdoc} built-in Doclets deal with this problem by
3095 ``fixing'' the HTML code - making sure that all tags are closed,
3096 attribute values are provided and quoted, tags are properly nested,
3097 etc.
3098
3099 This approach works OK in most instances, but since it uses some crude
3100 heuristics it can sometimes produce undesirable result.
3101
3102 Therefore, in order to make sure that your comments are always
3103 properly formatted, make sure they are well-formed as described in
3104 @w{@uref{http://www.w3.org/TR/xhtml1/#h-4.1, XHTML 1.0: Documents must
3105 be well-formed}}.
3106
3107 In addition, you should use meaningful tags instead of text formatting
3108 tags to make your output look better in other output formats derived
3109 from your HTML code.  For example, you should use the <em> tag instead
3110 of <b> if you want to emphasize text.
3111
3112 @comment ----------------------------------------------------------------------
3113
3114 @node First Sentence Detector, Adding Custom Resources, XHTML Fragments, Gjdoc Concepts
3115 @section How Gjdoc Determines where the First Sentence Ends
3116 @cindex First Sentence Detector
3117
3118 For a package, class or member summary, @command{gjdoc} only shows the
3119 first sentence of the documentation comment in question.  Because
3120 @command{gjdoc} is not human, it is not always obvious to
3121 @command{gjdoc} where the first sentence ends.
3122
3123 You might be tempted to say that the first sentence ends at the first
3124 occurrence of a punctuation character like @samp{.} or
3125 @samp{!}. However, consider examples like this:
3126 @smallexample
3127 This work, by Thomas J. Shahan et al., is about the middle ages.
3128 @end smallexample
3129
3130 As you can see, it is not trivial to determine the end of the
3131 sentence.
3132
3133 @command{gjdoc} gives you the choice between two approaches.  By
3134 default it uses built-in heuristics which should be compatible to
3135 Sun's @command{javadoc} tool.  This approach works quiet well in most
3136 cases, at least for english comments.
3137
3138 Alternatively, you can specify option @option{-breakiterator} in which
3139 case @command{gjdoc} will use
3140 @samp{java.text.BreakIterator.getSentenceInstance(@var{locale}).next()}
3141 to find the end of sentence, where @var{locale} is the locale
3142 specified by option @samp{-locale} or the default locale if none
3143 specified.
3144
3145 @emph{NOT YET IMPLEMENTED:}
3146
3147 @command{gjdoc} also allows you to explicitly delineate the first
3148 sentence by putting it in a @samp{<span>} tag with the CSS class
3149 @samp{first-sentence}.  For example:
3150 @smallexample
3151 /**
3152  *  <span class="first-sentence">This. is. the. first. 
3153  *  sentence.</span> This is the second sentence.
3154  */
3155 @end smallexample
3156
3157 Note that this will only work with @command{gjdoc}, but shouldn't hurt
3158 when using another documentation system since the @samp{<span>} tag
3159 usually doesn't show up in the output.
3160
3161 @comment ----------------------------------------------------------------------
3162
3163 @node Adding Custom Resources, , First Sentence Detector, Gjdoc Concepts
3164 @section Adding Images and Other Resources
3165 @cindex First Sentence Detector
3166
3167 Sometimes you want to decorate your documentation with secondary
3168 resources such as images, SVG graphics, applets, and so on.  To do so,
3169 simply put the required files in a subdirectory 'doc-files' in the
3170 package directory corresponding to the documentation entry you want to
3171 decorate, and refer to it with the URL
3172 @samp{doc-files/@var{filename}}.
3173
3174 For example, if you want to add an image to the description of class
3175 @samp{baz.FooBar}, create a directory @file{doc-files} in the
3176 directory @file{baz} containing @file{FooBar.java} and put your file,
3177 say @file{diagram.png}, into that directory.  Then, add the HTML code
3178 like this to a comment in @file{FooBar.java}:
3179 @smallexample
3180 <img src="doc-files/diagram.png" width="200" height="150"
3181   alt="Foo Diagram"/>
3182 @end smallexample
3183
3184 This works because the @file{doc-files} subdirectories will be copied
3185 to the target documentation directory every time you generate the
3186 documentation.  
3187
3188 Note however that by default, the @file{doc-files} directory will not
3189 be copied deeply.  In other words, if you create subdirectories under
3190 @file{doc-files} they will not be copied and any resources located in
3191 these subdirectories will not be accessible in your generated
3192 documentation.  You can specify option @option{-docfilessubdirs} to
3193 remove this limitation.
3194
3195 Sometimes you want to use option @option{-docfilessubdirs}, but there
3196 are certain directories which you don't want to be copied, for example
3197 because they contain source files for the resources in
3198 @file{doc-files}.  For cases like this, use
3199 @option{-excludedocfilessubdir} to specify directories to be omitted.
3200
3201 @comment ----------------------------------------------------------------------
3202
3203 @node I18N Issues, , Other Tools, Top
3204 @comment node-name, next, previous, up
3205 @chapter I18N Issues
3206
3207 Some tools --@pxref{Security Tools}-- allow using other than the English language when prompting the User for input, and outputting messages. This chapter describes the elements used to offer this support and how they can be adapted for use with specific languages.
3208
3209 @menu
3210 * Language Resources::         Where resources are located
3211 * Message Formats::            How messages are internationalized
3212 @end menu
3213
3214 @comment ----------------------------------------------------------------------
3215
3216 @node Language Resources, Message Formats, I18N Issues, I18N Issues
3217 @comment node-name, next, previous, up
3218 @section Language-specific resources
3219
3220 The Tools use Java @code{ResourceBundle}s to store messages, and message templates they use at runtime to generate the message text itself, depending on the locale in use at the time.
3221
3222 The @i{Resource Bundles} these tools use are essentially Java @i{Properties} files consisting of a set of @i{Name/Value} pairs. The @i{Name} is the @i{Property Name} and the @i{Value} is a substitution string that is used when the code references the associated @i{Name}. For example the following is a line in a @i{Resource Bundle} used by the @code{keytool} Tool:
3223
3224 @example
3225 Command.23=A correct key password MUST be provided
3226 @end example
3227
3228 When the tool needs to signal a mandatory but missing key password, it would reference the property named @code{Command.23} and the message "@kbd{A correct key password MUST be provided}" will be used instead. This indirect referencing of "resources" permits replacing, as late as possible, the English strings with strings in other languages, provided of course @i{Resource Bundles} in those languages are provided.
3229
3230 For the GNU Classpath Tools described in this Guide, the @i{Resource Bundles} are files named @file{messages[_ll[_CC[_VV]]].properties} where:
3231
3232 @ftable @var
3233 @item ll
3234 Is the 2-letter code for the Language,
3235 @item CC
3236 Is the 2-letter code for the Region, and
3237 @item VV
3238 Is the 2-letter code for the Variant of the language.
3239 @end ftable
3240
3241 The complete list of language codes can be found at @uref{http://ftp.ics.uci.edu/pub/ietf/http/related/iso639.txt, Code for the representation of names of languages}. A similar list for the region codes can be found at @uref{http://userpage.chemie.fu-berlin.de/diverse/doc/ISO_3166.html, ISO 3166 Codes (Countries)}.
3242
3243 The location of the @i{Resource Bundles} for the GNU Classpath Tools is specific to each tool. The next table shows where these files are found in a standard GNU Classpath distribution:
3244
3245 @ftable @code
3246 @item jarsigner
3247 @file{gnu/classpath/tools/jarsigner}
3248 @item keytool
3249 @file{gnu/classpath/tools/keytool}
3250 @end ftable
3251
3252 The collection of @i{Resource Bundles} in a location act as an inverted tree with a parent-child relationship. For example suppose in the @file{gnu/classpath/tools/keytool} there are 3 message bundles named:
3253
3254 @enumerate
3255 @item @code{messages.properties}
3256 @item @code{messages_fr.properties}
3257 @item @code{messages_fr_FR.properties}
3258 @end enumerate
3259
3260 In the above example, bundle #1 will act as the parent of bundle #2, which in turn will act as the parent for bundle #3. This ordering is used by the Java runtime to choose which file to load based on the set Locale. For example if the Locale is @code{fr_CH}, @code{messages_fr.properties} will be used because (a) @code{messages_fr_CH.properties} does not exist, but (b) @code{messages_fr.properties} is the parent for the required bundle, and it exists. As another example, suppose the Locale was set to @code{en_AU}; then the tool will end up using @code{messages.properties} because (a) @code{messages_en_AU.properties} does not exist, (b) @code{messages_en.properties} which is the parent for the required bundle does not exist, but (c) @code{messages.properties} exists and is the root of the hierarchy.
3261
3262 You can see from the examples above that @file{messages.properties} is the safety net that the Java runtime falls back to when failing to find a specific bundle and its parent(s). This file is always provided with the Tool. In time, more localized versions will be included to cater for other languages.
3263
3264 In the meantime, if you are willing to contribute localized versions of these resources, grab the @file{messages.properties} for a specific tool; translate it; save it with the appropriate language and region suffix and mail it to @code{classpath@@gnu.org}.
3265
3266 @comment ----------------------------------------------------------------------
3267
3268 @node Message Formats, , Language Resources, I18N Issues
3269 @comment node-name, next, previous, up
3270 @section Message formats
3271
3272 If you open any of the @file{messages.properties} described in the previous section, you may see properties that look like so:
3273
3274 @example
3275 Command.67=Issuer: @{0@}
3276 Command.68=Serial number: @{0,number@}
3277 Command.69=Valid from: @{0,date,full@} - @{0,time,full@}
3278 Command.70=\ \ \ \ \ until: @{0,date,full@} - @{0,time,full@}
3279 @end example
3280
3281 These are @i{Message Formats} used by the tools to customize a text string that will then be used either as a prompt for User input or as output.
3282
3283 If you are translating a @file{messages.properties} be careful not to alter text between curly braces.
3284
3285 @comment ----------------------------------------------------------------------
3286
3287 @bye