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