diff options
Diffstat (limited to 'gcc-4.9/libjava/classpath/doc/cp-tools.info')
| -rw-r--r-- | gcc-4.9/libjava/classpath/doc/cp-tools.info | 3146 |
1 files changed, 0 insertions, 3146 deletions
diff --git a/gcc-4.9/libjava/classpath/doc/cp-tools.info b/gcc-4.9/libjava/classpath/doc/cp-tools.info deleted file mode 100644 index b0133b35d..000000000 --- a/gcc-4.9/libjava/classpath/doc/cp-tools.info +++ /dev/null @@ -1,3146 +0,0 @@ -This is cp-tools.info, produced by makeinfo version 5.1 from -cp-tools.texinfo. - -This file documents the Tools included in a standard distribution of the -GNU Classpath project deliverables. - - Copyright (C) 2006, 2007 Free Software Foundation, Inc. - - Permission is granted to make and distribute verbatim copies of - this document provided the copyright notice and this permission - notice are preserved on all copies. - - Permission is granted to copy and distribute modified versions of - this document under the conditions for verbatim copying, provided - that the entire resulting derived work is distributed under the - terms of a permission notice identical to this one. - - Permission is granted to copy and distribute translations of this - manual into another language, under the above conditions for - modified versions, except that this permission notice may be stated - in a translation approved by the Free Software Foundation. -INFO-DIR-SECTION GNU Libraries -START-INFO-DIR-ENTRY -* Classpath Tools: (cp-tools). GNU Classpath Tools Guide -END-INFO-DIR-ENTRY - - -File: cp-tools.info, Node: Top, Next: Applet Tools, Prev: (dir), Up: (dir) - -GNU Classpath Tools Guide -************************* - -This document contains important information you need to know in order -to use the tools included in the GNU Classpath project deliverables. - - The Tools aim at providing a free replacement, similar in their -behavior, to their counter-parts found in the Reference Implementation -(RI) of the Java Software Development Kit (SDK). - -* Menu: - -* Applet Tools:: Work with applets -* Security Tools:: Work securely with Java applications -* Other Tools:: Other tools in classpath -* I18N Issues:: How to add support for non-English languages - - -- The Detailed Node Listing -- - -Applet Tools - -* appletviewer Tool:: Load applets -* gcjwebplugin:: Load applets in a web browser - -Security Tools - -* jarsigner Tool:: Sign and verify .JAR files -* keytool Tool:: Manage private keys and public certificates - -jarsigner Tool - -* Common jarsigner Options:: Options used when signing or verifying a file -* Signing Options:: Options only used when signing a .JAR file -* Verification Options:: Options only used when verifying a .JAR file - -keytool Tool - -* Getting Help:: How to get help with keytool commands -* Common keytool Options:: Options used in more than one command -* Distinguished Names:: X.500 Distinguished Names used in certificates -* Add/Update Commands:: Commands for adding data to a Key Store -* Export Commands:: Commands for exporting data from a Key Store -* Display Commands:: Commands for displaying data in a Key Store -* Management Commands:: Commands for managing a Key Store - -Add/Update Commands - -* Command -genkey:: Generate private key and self-signed certificate -* Command -import:: Import certificates and certificate replies -* Command -selfcert:: Generate self-signed certificate -* Command -cacert:: Import a CA Trusted Certificate -* Command -identitydb:: Import JDK-1 style identities - -Export Commands - -* Command -certreq:: Generate Certificate Signing Requests (CSR) -* Command -export:: Export a certificate in a Key Store - -Display Commands - -* Command -list:: Display information about one or all Aliases -* Command -printcert:: Print a certificate or a certificate fingerprint - -Management Commands - -* Command -keyclone:: Clone a Key Entry in a Key Store -* Command -storepasswd:: Change the password protecting a Key Store -* Command -keypasswd:: Change the password protecting a Key Entry -* Command -delete:: Remove an entry in a Key Store - -Other Tools - -* jar Tool:: Archive tool for Java archives -* javah Tool:: A java header compiler -* gcjh Tool:: A java header compiler (old version) -* native2ascii Tool:: An encoding converter -* orbd Tool:: An object request broker daemon -* serialver Tool:: A serial version command -* rmid Tool:: RMI activation daemon -* rmiregistry Tool:: Remote object registry -* tnameserv Tool:: Naming service -* gjdoc Tool:: Documenation generator tool. - -Generating HTML Documentation - -* Invoking the Standard Doclet:: How to generate HTML documentation. -* Invoking a Custom Doclet:: How to run third-party and other - built-in Doclets. - -* Option Summary by Type:: Brief list of all options, grouped by type. -* Gjdoc Option Summary:: List of all options accepted by Gjdoc. - -* Source Set Options:: Select the set of source codes to run Gjdoc on. -* Source Format Options:: Specify the format of the source codes to document. - -* Interlinking Options:: Connection your documentation with other projects. -* Output Control Options:: Specify the target directory and locale, and more. -* Generation Options:: Select which pieces of information to generate. -* Decoration Options:: Add or modify some titles, headers and footers or - override/amend static resources like stylesheets. -* Taglet Options:: Define your own javadoc @tags. - -* Virtual Machine Options:: Controlling the kind of output: - an executable, object files, assembler files, - or preprocessed source. -* Verbosity Options:: -* Doclet Options:: - -* Other Doclets:: Generating Other Output Types. - -* Built-in Doclets:: Using the Built-in Doclets. -* Using XmlDoclet:: -* Using TexiDoclet:: -* Using IspellDoclet:: -* Using DebugDoclet:: - -* Third-party Doclets:: Using Third-Party Doclets. -* DocBook Doclet:: -* PDFDoclet:: -* JUnitDoclet:: - -* Gjdoc Concepts:: Advanced Concepts. -* Writing Doclets:: - -* Doclet Invocation Interface:: Implementing the Doclet Invocation Interface -* Using AbstractDoclet:: Deriving Your Doclet from AbstractDoclet. -* GNU Doclet SPI:: Preparing the GNU Doclet Service Provider - Interface. - -* Taglets:: Adding Custom Tags to the Documentation. -* XHTML Fragments:: Well-Formed Documentation Fragments. -* First Sentence Detector:: How Gjdoc Determines where the First - Sentence Ends. -* Adding Custom Resources:: Adding Images and Other Resources. - -I18N Issues - -* Language Resources:: Where resources are located -* Message Formats:: How messages are internationalized - - - -File: cp-tools.info, Node: Applet Tools, Next: Security Tools, Prev: Top, Up: Top - -1 Applet Tools -************** - -Two Applet Tools are available with GNU Classpath: appletviewer and -gcjwebplugin. - - To avoid conflicts with other implementations, the appletviewer -executable is called "gappletviewer". - -* Menu: - -* appletviewer Tool:: Load applets -* gcjwebplugin:: Load applets in a web browser - - If while using these tools you think you found a bug, then please -report it at classpath-bugs -(http://www.gnu.org/software/classpath/bugs.html). - - -File: cp-tools.info, Node: appletviewer Tool, Next: gcjwebplugin, Prev: Applet Tools, Up: Applet Tools - -1.1 The 'appletviewer' Tool -=========================== - -SYNOPSIS - - appletviewer [OPTION]... URL... - - appletviewer [OPTION]... '-code' CODE - - appletviewer [OPTION]... '-plugin' INPUT,OUTPUT - - DESCRIPTION The 'appletviewer' tool loads and runs an applet. - - Use the first form to test applets specified by tag. The URL should -resolve to an HTML document from which the 'appletviewer' will extract -applet tags. The APPLET, EMBED and OBJECT tags are supported. If a -given document contains multiple applet tags, all the applets will be -loaded, with each applet appearing in its own window. Likewise, when -multiple URLs are specified, each applet tag instance is given its own -window. If a given document contains no recognized tags the -'appletviewer' does nothing. - - appletviewer http://www.gnu.org/software/classpath/ - - Use the second form to test an applet in development. This form -allows applet tag attributes to be supplied on the command line. Only -one applet may be specified using the '-code' option. The '-code' -option overrides the URL form - any URLs specified will be ignored. - - appletviewer -code Test.class -param datafile,data.txt - - 'gcjwebplugin' uses the third form to communicate with the -'appletviewer' through named pipes. - - URL OPTIONS -'-debug' - This option is not yet implemented but is provided for - compatibility. - -'-encoding CHARSET' - Use this option to specify an alternate character encoding for the - specified HTML page. - - APPLET TAG OPTIONS -'-code CODE' - Use the '-code' option to specify the value of the applet tag CODE - attribute. - -'-codebase CODEBASE' - Use the '-codebase' option to specify the value of the applet tag - CODEBASE attribute. - -'-archive ARCHIVE' - Use the '-archive' option to specify the value of the applet tag - ARCHIVE attribute. - -'-width WIDTH' - Use the '-width' option to specify the value of the applet tag - WIDTH attribute. - -'-height HEIGHT' - Use the '-height' option to specify the value of the applet tag - HEIGHT attribute. - -'-param NAME,VALUE' - Use the '-param' option to specify values for the NAME and VALUE - attributes of an applet PARAM tag. - - PLUGIN OPTION -'-plugin INPUT,OUTPUT' - 'gcjwebplugin' uses the '-plugin' option to specify the named pipe - the 'appletviewer' should use for receiving commands (INPUT) and - the one it should use for sending commands to 'gcjwebplugin' - (OUTPUT). - - DEBUGGING OPTION -'-verbose' - Use the '-verbose' option to have the 'appletviewer' print - debugging messages. - - STANDARD OPTIONS - -'-help' - Use the '-help' option to have the 'appletviewer' print a usage - message, then exit. - -'-version' - Use the '-version' option to have the 'appletviewer' print its - version, then exit. - -'-JOPTION' - Use the '-J' option to pass OPTION to the virtual machine that will - run the 'appletviewer'. Unlike other options, there must not be a - space between the '-J' and OPTION. - - -File: cp-tools.info, Node: gcjwebplugin, Prev: appletviewer Tool, Up: Applet Tools - -1.2 The 'gcjwebplugin' Tool -=========================== - -'gcjwebplugin' is a plugin that adds applet support to web browsers. -Currently 'gcjwebplugin' only supports Mozilla-based browsers (e.g., -Firefox, Galeon, Mozilla). - - -File: cp-tools.info, Node: Security Tools, Next: Other Tools, Prev: Applet Tools, Up: Top - -2 Security Tools -**************** - -Two Security Tools are available with GNU Classpath: 'jarsigner' and -'keytool'. - - To avoid conflicts with other implementations, the jarsigner -executable is called 'gjarsigner' and the keytool executable is called -'gkeytool'. - -* Menu: - -* jarsigner Tool:: Sign and verify .JAR files -* keytool Tool:: Manage private keys and public certificates - - If while using these tools you think you found a bug, then please -report it at classpath-bugs -(http://www.gnu.org/software/classpath/bugs.html). - - -File: cp-tools.info, Node: jarsigner Tool, Next: keytool Tool, Prev: Security Tools, Up: Security Tools - -2.1 The 'jarsigner' Tool -======================== - -The 'jarsigner' tool is invoked from the command line, in one of two -forms, as follows: - - jarsigner [OPTION]... FILE ALIAS - - jarsigner -verify [OPTION]... FILE - - When the first form is used, the tool signs the designated JAR file. -The second form, on the other hand, is used to verify a previously -signed JAR file. - - FILE is the .JAR file to process; i.e., to sign if the first syntax -form is used, or to verify if the second syntax form is used instead. - - ALIAS must be a known Alias of a Key Entry in the designated Key -Store. The private key material associated with this Alias is then used -for signing the designated .JAR file. - -* Menu: - -* Common jarsigner Options:: Options used when signing or verifying a file -* Signing Options:: Options only used when signing a .JAR file -* Verification Options:: Options only used when verifying a .JAR file - - -File: cp-tools.info, Node: Common jarsigner Options, Next: Signing Options, Prev: jarsigner Tool, Up: jarsigner Tool - -2.1.1 Common options --------------------- - -The following options may be used when the tool is used for either -signing, or verifying, a .JAR file. - -'-verbose' - Use this option to force the tool to generate more verbose - messages, during its processing. - -'-internalsf' - When present, the tool will include -which otherwise it does not- - the '.SF' file in the '.DSA' generated file. - -'-sectionsonly' - When present, the tool will include in the '.SF' generated file - -which otherwise it does not- a header containing a hash of the - whole manifest file. When that header is included, the tool can - quickly check, during verification, if the hash (in the header) - matches or not the manifest file. - -'-provider PROVIDER_CLASS_NAME' - A fully qualified class name of a Security Provider to add to the - current list of Security Providers already installed in the JVM - in-use. If a provider class is specified with this option, and was - successfully added to the runtime -i.e. it was not already - installed- then the tool will attempt to remove this Security - Provider before exiting. - -'-help' - Prints a help text similar to this one. - - -File: cp-tools.info, Node: Signing Options, Next: Verification Options, Prev: Common jarsigner Options, Up: jarsigner Tool - -2.1.2 Signing options ---------------------- - -The following options may be specified when using the tool for signing -purposes. - -'-keystore URL' - Use this option to specify the location of the key store to use. - The default value is a file URL referencing the file named - '.keystore' located in the path returned by the call to - 'java.lang.System#getProperty(String)' using 'user.home' as - argument. - - If a URL was specified, but was found to be malformed -e.g. missing - protocol element- the tool will attempt to use the URL value as a - file-name (with absolute or relative path-name) of a key store -as - if the protocol was 'file:'. - -'-storetype STORE_TYPE' - Use this option to specify the type of the key store to use. The - default value, if this option is omitted, is that of the property - 'keystore.type' in the security properties file, which is obtained - by invoking the static method call 'getDefaultType()' in - 'java.security.KeyStore'. - -'-storepass PASSWORD' - Use this option to specify the password which will be used to - unlock the key store. If this option is missing, the User will be - prompted to provide a password. - -'-keypass PASSWORD' - Use this option to specify the password which the tool will use to - unlock the Key Entry associated with the designated Alias. - - If this option is omitted, the tool will first attempt to unlock - the Key Entry using the same password protecting the key store. If - this fails, you will then be prompted to provide a password. - -'-sigfile NAME' - Use this option to designate a literal that will be used to - construct file names for both the '.SF' and '.DSA' signature files. - These files will be generated, by the tool, and placed in the - 'META-INF' directory of the signed JAR. Permissible characters for - NAME must be in the range "a-zA-Z0-9_-". All characters will be - converted to upper-case ones. - - If this option is missing, the first eight characters of the ALIAS - argument will be used. When this is the case, any character in - ALIAS that is outside the permissible range of characters will be - replaced by an underscore. - -'-signedjar FILE' - Use this option to specify the file name of the signed JAR. If - this option is omitted, then the signed JAR will be named the same - as FILE; i.e., the input JAR file will be replaced with the signed - copy. - - -File: cp-tools.info, Node: Verification Options, Prev: Signing Options, Up: jarsigner Tool - -2.1.3 Verification options --------------------------- - -The following options may be specified when using the tool for -verification purposes. - -'-verify' - Use this option to indicate that the tool is to be used for - verification purposes. - -'-certs' - This option is used in conjunction with the '-verbose' option. - When present, along with the '-verbose' option, the tool will print - more detailed information about the certificates of the signer(s) - being processed. - - -File: cp-tools.info, Node: keytool Tool, Prev: jarsigner Tool, Up: Security Tools - -2.2 The 'keytool' Tool -====================== - -Cryptographic credentials, in a Java environment, are usually stored in -a Key Store. The Java SDK specifies a Key Store as a persistent -container of two types of objects: Key Entries and Trusted Certificates. -The security tool 'keytool' is a Java-based application for managing -those types of objects. - - A Key Entry represents the private key part of a key-pair used in -Public-Key Cryptography, and a signed X.509 certificate which -authenticates the public key part for a known entity; i.e. the owner of -the key-pair. The X.509 certificate itself contains the public key part -of the key-pair. - - A Trusted Certificate is a signed X.509 certificate issued by a -trusted entity. The Trust in this context is relative to the User of -the 'keytool'. In other words, the existence of a Trusted Certificate -in the Key Store processed by a 'keytool' command implies that the User -trusts the Issuer of that Trusted Certificate to also sign, and hence -authenticates, other Subjects the tool may process. - - Trusted Certificates are important because they allow the tool to -mechanically construct Chains of Trust starting from one of the Trusted -Certificates in a Key Store and ending with a certificate whose Issuer -is potentially unknown. A valid chain is an ordered list, starting with -a Trusted Certificate (also called the anchor), ending with the target -certificate, and satisfying the condition that the Subject of -certificate '#i' is the Issuer of certificate '#i + 1'. - - The 'keytool' is invoked from the command line as follows: - - keytool [COMMAND] ... - - Multiple COMMANDs may be specified at once, each complete with its -own options. 'keytool' will parse all the arguments, before processing, -and executing, each 'COMMAND'. If an exception occurs while executing -one COMMAND 'keytool' will abort. Note however that because the -implementation of the tool uses code to parse command line options that -also supports GNU-style options, you have to separate each command group -with a double-hyphen; e.g - - keytool -list -- -printcert -alias mykey - - Here is a summary of the commands supported by the tool: - - 1. Add/Update commands - '-genkey [OPTION]...' - Generate a new Key Entry, eventually creating a new key store. - - '-import [OPTION]...' - Add, to a key store, Key Entries (private keys and certificate - chains authenticating the public keys) and Trusted - Certificates (3rd party certificates which can be used as - Trust Anchors when building chains-of-trust). - - '-selfcert [OPTION]...' - Generate a new self-signed Trusted Certificate. - - '-cacert [OPTION]...' - Import a CA Trusted Certificate. - - '-identitydb [OPTION]...' - NOT IMPLEMENTED YET. - Import a JDK 1.1 style Identity Database. - - 2. Export commands - '-certreq [OPTION]...' - Issue a Certificate Signing Request (CSR) which can be then - sent to a Certification Authority (CA) to issue a certificate - signed (by the CA) and authenticating the Subject of the - request. - - '-export [OPTION]...' - Export a certificate from a key store. - - 3. Display commands - '-list [OPTION]...' - Print one or all certificates in a key store to 'STDOUT'. - - '-printcert [OPTION]...' - Print a human-readable form of a certificate, in a designated - file, to 'STDOUT'. - - 4. Management commands - '-keyclone [OPTION]...' - Clone a Key Entry in a key store. - - '-storepasswd [OPTION]...' - Change the password protecting a key store. - - '-keypasswd [OPTION]...' - Change the password protecting a Key Entry in a key store. - - '-delete [OPTION]...' - Delete a Key Entry or a Trusted Certificate from a key store. - -* Menu: - -* Getting Help:: How to get help with keytool commands -* Common keytool Options:: Options used in more than one command -* Distinguished Names:: X.500 Distinguished Names used in certificates -* Add/Update Commands:: Commands for adding data to a Key Store -* Export Commands:: Commands for exporting data from a Key Store -* Display Commands:: Commands for displaying data in a Key Store -* Management Commands:: Commands for managing a Key Store - - -File: cp-tools.info, Node: Getting Help, Next: Common keytool Options, Prev: keytool Tool, Up: keytool Tool - -2.2.1 Getting help ------------------- - -To get a general help text about the tool, use the '-help' option; e.g. - - keytool -help - - To get more specific help text about one of the tool's command use -the '-help' option for that command; e.g. - - keytool -genkey -help - - In both instances, the tool will print a help text and then will exit -the running JVM. - - It is worth noting here that the help messages printed by the tool -are I18N-ready. This means that if/when the contents of the tool's -Message Bundle properties file are available in languages other than -English, you may see those messages in that language. - - -File: cp-tools.info, Node: Common keytool Options, Next: Distinguished Names, Prev: Getting Help, Up: keytool Tool - -2.2.2 Common options --------------------- - -The following 'OPTION's are used in more than one 'COMMAND'. They are -described here to reduce redundancy. - -'-alias ALIAS' - Every entry, be it a Key Entry or a Trusted Certificate, in a key - store is uniquely identified by a user-defined ALIAS string. Use - this option to specify the ALIAS to use when referring to an entry - in the key store. Unless specified otherwise, a default value of - 'mykey' shall be used when this option is omitted from the command - line. - -'-keyalg ALGORITHM' - Use this option to specify the canonical name of the key-pair - generation algorithm. The default value for this option is 'DSS' - (a synonym for the Digital Signature Algorithm also known as DSA). - -'-keysize SIZE' - Use this option to specify the number of bits of the shared modulus - (for both the public and private keys) to use when generating new - keys. A default value of '1024' will be used if this option is - omitted from the command line. - -'-validity DAY_COUNT' - Use this option to specify the number of days a newly generated - certificate will be valid for. The default value is '90' (days) if - this option is omitted from the command line. - -'-storetype STORE_TYPE' - Use this option to specify the type of the key store to use. The - default value, if this option is omitted, is that of the property - 'keystore.type' in the security properties file, which is obtained - by invoking the static method call 'getDefaultType()' in - 'java.security.KeyStore'. - -'-storepass PASSWORD' - Use this option to specify the password protecting the key store. - If this option is omitted from the command line, you will be - prompted to provide a password. - -'-keystore URL' - Use this option to specify the location of the key store to use. - The default value is a file URL referencing the file named - '.keystore' located in the path returned by the call to - 'java.lang.System#getProperty(String)' using 'user.home' as - argument. - - If a URL was specified, but was found to be malformed -e.g. missing - protocol element- the tool will attempt to use the URL value as a - file-name (with absolute or relative path-name) of a key store -as - if the protocol was 'file:'. - -'-provider PROVIDER_CLASS_NAME' - A fully qualified class name of a Security Provider to add to the - current list of Security Providers already installed in the JVM - in-use. If a provider class is specified with this option, and was - successfully added to the runtime -i.e. it was not already - installed- then the tool will attempt to removed this Security - Provider before exiting. - -'-file FILE' - Use this option to designate a file to use with a command. When - specified with this option, the value is expected to be the fully - qualified path of a file accessible by the File System. Depending - on the command, the file may be used as input or as output. When - this option is omitted from the command line, 'STDIN' will be used - instead, as the source of input, and 'STDOUT' will be used instead - as the output destination. - -'-v' - Unless specified otherwise, use this option to enable more verbose - output. - - -File: cp-tools.info, Node: Distinguished Names, Next: Add/Update Commands, Prev: Common keytool Options, Up: keytool Tool - -2.2.3 X.500 Distinguished Names -------------------------------- - -A Distinguished Name (or DN) MUST be supplied with some of the -'COMMAND's using a '-dname' option. The syntax of a valid value for -this option MUST follow RFC-2253 specifications. Namely the following -components (with their accepted meaning) will be recognized. Note that -the component name is case-insensitive: - -CN - The Common Name; e.g. 'host.domain.com' -OU - The Organizational Unit; e.g. 'IT Department' -O - The Organization Name; e.g. 'The Sample Company' -L - The Locality Name; e.g. 'Sydney' -ST - The State Name; e.g. 'New South Wales' -C - The 2-letter Country identifier; e.g. 'AU' - - When specified with a '-dname' option, each pair of component/value -will be separated from the other with a comma. Each component and value -pair MUST be separated by an equal sign. For example, the following is -a valid DN value: - -CN=host.domain.com, O=The Sample Company, L=Sydney, ST=NSW, C=AU - - If the Distinguished Name is required, and no valid default value can -be used, the tool will prompt you to enter the information through the -console. - - -File: cp-tools.info, Node: Add/Update Commands, Next: Export Commands, Prev: Distinguished Names, Up: keytool Tool - -2.2.4 Add/Update commands -------------------------- - -* Menu: - -* Command -genkey:: Generate private key and self-signed certificate -* Command -import:: Import certificates and certificate replies -* Command -selfcert:: Generate self-signed certificate -* Command -cacert:: Import a CA Trusted Certificate -* Command -identitydb:: Import JDK-1 style identities - - -File: cp-tools.info, Node: Command -genkey, Next: Command -import, Prev: Add/Update Commands, Up: Add/Update Commands - -2.2.4.1 The '-genkey' command -............................. - -Use this command to generate a new key-pair (both private and public -keys), and save these credentials in the key store as a Key Entry, -associated with the designated (if was specified with the '-alias' -option) or default (if the '-alias' option is omitted) Alias. - - The private key material will be protected with a user-defined -password (see '-keypass' option). The public key on the other hand will -be part of a self-signed X.509 certificate, which will form a 1-element -chain and will be saved in the key store. - -'-alias ALIAS' - For more details *note ALIAS: alias. - -'-keyalg ALGORITHM' - For more details *note ALGORITHM: keyalg. - -'-keysize KEY_SIZE' - For more details *note KEY_SIZE: keysize. - -'-sigalg ALGORITHM' - The canonical name of the digital signature algorithm to use for - signing certificates. If this option is omitted, a default value - will be chosen based on the type of the key-pair; i.e., the - algorithm that ends up being used by the -keyalg option. If the - key-pair generation algorithm is 'DSA', the value for the signature - algorithm will be 'SHA1withDSA'. If on the other hand the key-pair - generation algorithm is 'RSA', then the tool will use 'MD5withRSA' - as the signature algorithm. - -'-dname NAME' - This a mandatory value for the command. If no value is specified - -i.e. the '-dname' option is omitted- the tool will prompt you to - enter a Distinguished Name to use as both the Owner and Issuer of - the generated self-signed certificate. - - For more details *note X.500 DISTINGUISHED NAME: dn. - -'-keypass PASSWORD' - Use this option to specify the password which the tool will use to - protect the newly created Key Entry. - - If this option is omitted, you will be prompted to provide a - password. - -'-validity DAY_COUNT' - For more details *note DAY_COUNT: validity. - -'-storetype STORE_TYPE' - For more details *note STORE_TYPE: storetype. - -'-keystore URL' - For more details *note URL: keystore. - -'-storepass PASSWORD' - For more details *note PASSWORD: storepass. - -'-provider PROVIDER_CLASS_NAME' - For more details *note PROVIDER_CLASS_NAME: provider. - -'-v' - For more details *note verbose::. - - -File: cp-tools.info, Node: Command -import, Next: Command -selfcert, Prev: Command -genkey, Up: Add/Update Commands - -2.2.4.2 The '-import' command -............................. - -Use this command to read an X.509 certificate, or a PKCS#7 Certificate -Reply from a designated input source and incorporate the certificates -into the key store. - - If the Alias does not already exist in the key store, the tool treats -the certificate read from the input source as a new Trusted Certificate. -It then attempts to discover a chain-of-trust, starting from that -certificate and ending at another Trusted Certificate, already stored in -the key store. If the '-trustcacerts' option is present, an additional -key store, of type 'JKS' named 'cacerts', and assumed to be present in -'${JAVA_HOME}/lib/security' will also be consulted if found --'${JAVA_HOME}' refers to the location of an installed Java Runtime -Environment (JRE). If no chain-of-trust can be established, and unless -the '-noprompt' option has been specified, the certificate is printed to -'STDOUT' and the user is prompted for a confirmation. - - If Alias exists in the key store, the tool will treat the -certificate(s) read from the input source as a Certificate Reply, which -can be a chain of certificates, that eventually would replace the chain -of certificates associated with the Key Entry of that Alias. The -substitution of the certificates only occurs if a chain-of-trust can be -established between the bottom certificate of the chain read from the -input file and the Trusted Certificates already present in the key -store. Again, if the '-trustcacerts' option is specified, additional -Trusted Certificates in the same 'cacerts' key store will be considered. -If no chain-of-trust can be established, the operation will abort. - -'-alias ALIAS' - For more details *note ALIAS: alias. - -'-file FILE' - For more details *note FILE: file. - -'-keypass PASSWORD' - Use this option to specify the password which the tool will use to - protect the Key Entry associated with the designated Alias, when - replacing this Alias' chain of certificates with that found in the - certificate reply. - - If this option is omitted, and the chain-of-trust for the - certificate reply has been established, the tool will first attempt - to unlock the Key Entry using the same password protecting the key - store. If this fails, you will then be prompted to provide a - password. - -'-noprompt' - Use this option to prevent the tool from prompting the user. - -'-trustcacerts' - Use this option to indicate to the tool that a key store, of type - 'JKS', named 'cacerts', and usually located in 'lib/security' in an - installed Java Runtime Environment should be considered when trying - to establish chain-of-trusts. - -'-storetype STORE_TYPE' - For more details *note STORE_TYPE: storetype. - -'-keystore URL' - For more details *note URL: keystore. - -'-storepass PASSWORD' - For more details *note PASSWORD: storepass. - -'-provider PROVIDER_CLASS_NAME' - For more details *note PROVIDER_CLASS_NAME: provider. - -'-v' - For more details *note verbose::. - - -File: cp-tools.info, Node: Command -selfcert, Next: Command -cacert, Prev: Command -import, Up: Add/Update Commands - -2.2.4.3 The '-selfcert' command -............................... - -Use this command to generate a self-signed X.509 version 1 certificate. -The newly generated certificate will form a chain of one element which -will replace the previous chain associated with the designated Alias (if -'-alias' option was specified), or the default Alias (if '-alias' option -was omitted). - -'-alias ALIAS' - For more details *note ALIAS: alias. - -'-sigalg ALGORITHM' - The canonical name of the digital signature algorithm to use for - signing the certificate. If this option is omitted, a default - value will be chosen based on the type of the private key - associated with the designated Alias. If the private key is a - 'DSA' one, the value for the signature algorithm will be - 'SHA1withDSA'. If on the other hand the private key is an 'RSA' - one, then the tool will use 'MD5withRSA' as the signature - algorithm. - -'-dname NAME' - Use this option to specify the Distinguished Name of the newly - generated self-signed certificate. If this option is omitted, the - existing Distinguished Name of the base certificate in the chain - associated with the designated Alias will be used instead. - - For more details *note X.500 DISTINGUISHED NAME: dn. - -'-validity DAY_COUNT' - For more details *note DAY_COUNT: validity. - -'-keypass PASSWORD' - Use this option to specify the password which the tool will use to - unlock the Key Entry associated with the designated Alias. - - If this option is omitted, the tool will first attempt to unlock - the Key Entry using the same password protecting the key store. If - this fails, you will then be prompted to provide a password. - -'-storetype STORE_TYPE' - For more details *note STORE_TYPE: storetype. - -'-keystore URL' - For more details *note URL: keystore. - -'-storepass PASSWORD' - For more details *note PASSWORD: storepass. - -'-provider PROVIDER_CLASS_NAME' - For more details *note PROVIDER_CLASS_NAME: provider. - -'-v' - For more details *note verbose::. - - -File: cp-tools.info, Node: Command -cacert, Next: Command -identitydb, Prev: Command -selfcert, Up: Add/Update Commands - -2.2.4.4 The '-cacert' command -............................. - -Use this command to import, a CA certificate and add it to the key store -as a Trusted Certificate. The Alias for this new entry will be -constructed from the FILE's base-name after replacing hyphens and dots -with underscores. - - This command is useful when used in a script that recursively visits -a directory of CA certificates to populate a 'cacerts.gkr' Key Store of -trusted certificates which can then be used commands that specify the -'-trustcacerts' option. - -'-file FILE' - For more details *note FILE: file. - -'-storetype STORE_TYPE' - For more details *note STORE_TYPE: storetype. - -'-keystore URL' - For more details *note URL: keystore. - -'-storepass PASSWORD' - For more details *note PASSWORD: storepass. - -'-provider PROVIDER_CLASS_NAME' - For more details *note PROVIDER_CLASS_NAME: provider. - -'-v' - For more details *note verbose::. - - -File: cp-tools.info, Node: Command -identitydb, Prev: Command -cacert, Up: Add/Update Commands - -2.2.4.5 The '-identitydb' command -................................. - -NOT IMPLEMENTED YET. - - Use this command to import a JDK 1.1 style Identity Database. - -'-file FILE' - For more details *note FILE: file. - -'-storetype STORE_TYPE' - For more details *note STORE_TYPE: storetype. - -'-keystore URL' - For more details *note URL: keystore. - -'-storepass PASSWORD' - For more details *note PASSWORD: storepass. - -'-provider PROVIDER_CLASS_NAME' - For more details *note PROVIDER_CLASS_NAME: provider. - -'-v' - For more details *note verbose::. - - -File: cp-tools.info, Node: Export Commands, Next: Display Commands, Prev: Add/Update Commands, Up: keytool Tool - -2.2.5 Export commands ---------------------- - -* Menu: - -* Command -certreq:: Generate Certificate Signing Requests (CSR) -* Command -export:: Export a certificate in a Key Store - - -File: cp-tools.info, Node: Command -certreq, Next: Command -export, Prev: Export Commands, Up: Export Commands - -2.2.5.1 The '-certreq' command -.............................. - -Use this command to generate a PKCS#10 Certificate Signing Request (CSR) -and write it to a designated output destination. The contents of the -destination should look something like the following: - - -----BEGIN NEW CERTIFICATE REQUEST----- - MI...QAwXzEUMBIGA1UEAwwLcnNuQGdudS5vcmcxGzAZBgNVBAoMElUg - Q2...A0GA1UEBwwGU3lkbmV5MQwwCgYDVQQIDANOU1cxCzAJBgNVBACC - ... - FC...IVwNVOfQLRX+O5kAhQ/a4RTZme2L8PnpvgRwrf7Eg8D6w== - -----END NEW CERTIFICATE REQUEST----- - - IMPORTANT: Some documentation (e.g. RSA examples) claims that the -'Attributes' field, in the CSR is 'OPTIONAL' while RFC-2986 implies the -opposite. This implementation considers this field, by default, as -'OPTIONAL', unless the option '-attributes' is specified on the command -line. - -'-alias ALIAS' - For more details *note ALIAS: alias. - -'-sigalg ALGORITHM' - The canonical name of the digital signature algorithm to use for - signing the certificate. If this option is omitted, a default - value will be chosen based on the type of the private key - associated with the designated Alias. If the private key is a - 'DSA' one, the value for the signature algorithm will be - 'SHA1withDSA'. If on the other hand the private key is an 'RSA' - one, then the tool will use 'MD5withRSA' as the signature - algorithm. - -'-file FILE' - For more details *note FILE: file. - -'-keypass PASSWORD' - Use this option to specify the password which the tool will use to - unlock the Key Entry associated with the designated Alias. - - If this option is omitted, the tool will first attempt to unlock - the Key Entry using the same password protecting the key store. If - this fails, you will then be prompted to provide a password. - -'-storetype STORE_TYPE' - For more details *note STORE_TYPE: storetype. - -'-keystore URL' - For more details *note URL: keystore. - -'-storepass PASSWORD' - For more details *note PASSWORD: storepass. - -'-provider PROVIDER_CLASS_NAME' - For more details *note PROVIDER_CLASS_NAME: provider. - -'-v' - For more details *note verbose::. - -'-attributes' - Use this option to force the tool to encode a 'NULL' DER value in - the CSR as the value of the 'Attributes' field. - - -File: cp-tools.info, Node: Command -export, Prev: Command -certreq, Up: Export Commands - -2.2.5.2 The '-export' command -............................. - -Use this command to export a certificate stored in a key store to a -designated output destination, either in binary format (if the '-v' -option is specified), or in RFC-1421 compliant encoding (if the '-rfc' -option is specified instead). - -'-alias ALIAS' - For more details *note ALIAS: alias. - -'-file FILE' - For more details *note FILE: file. - -'-storetype STORE_TYPE' - For more details *note STORE_TYPE: storetype. - -'-keystore URL' - For more details *note URL: keystore. - -'-storepass PASSWORD' - For more details *note PASSWORD: storepass. - -'-provider PROVIDER_CLASS_NAME' - For more details *note PROVIDER_CLASS_NAME: provider. - -'-rfc' - Use RFC-1421 specifications when encoding the output. - -'-v' - Output the certificate in binary DER encoding. This is the default - output format of the command if neither '-rfc' nor '-v' options - were detected on the command line. If both this option and the - '-rfc' option are detected on the command line, the tool will opt - for the RFC-1421 style encoding. - - -File: cp-tools.info, Node: Display Commands, Next: Management Commands, Prev: Export Commands, Up: keytool Tool - -2.2.6 Display commands ----------------------- - -* Menu: - -* Command -list:: Display information about one or all Aliases -* Command -printcert:: Print a certificate or a certificate fingerprint - - -File: cp-tools.info, Node: Command -list, Next: Command -printcert, Prev: Display Commands, Up: Display Commands - -2.2.6.1 The '-list' command -........................... - -Use this command to print one or all of a key store entries to 'STDOUT'. -Usually this command will only print a fingerprint of the certificate, -unless either the '-rfc' or the '-v' option is specified. - -'-alias ALIAS' - If this option is omitted, the tool will print ALL the entries - found in the key store. - - For more details *note ALIAS: alias. - -'-storetype STORE_TYPE' - For more details *note STORE_TYPE: storetype. - -'-keystore URL' - For more details *note URL: keystore. - -'-storepass PASSWORD' - For more details *note PASSWORD: storepass. - -'-provider PROVIDER_CLASS_NAME' - For more details *note PROVIDER_CLASS_NAME: provider. - -'-rfc' - Use RFC-1421 specifications when encoding the output. - -'-v' - Output the certificate in human-readable format. If both this - option and the '-rfc' option are detected on the command line, the - tool will opt for the human-readable form and will not abort the - command. - - -File: cp-tools.info, Node: Command -printcert, Prev: Command -list, Up: Display Commands - -2.2.6.2 The '-printcert' command -................................ - -Use this command to read a certificate from a designated input source -and print it to 'STDOUT' in a human-readable form. - -'-file FILE' - For more details *note FILE: file. - -'-v' - For more details *note verbose::. - - -File: cp-tools.info, Node: Management Commands, Prev: Display Commands, Up: keytool Tool - -2.2.7 Management commands -------------------------- - -* Menu: - -* Command -keyclone:: Clone a Key Entry in a Key Store -* Command -storepasswd:: Change the password protecting a Key Store -* Command -keypasswd:: Change the password protecting a Key Entry -* Command -delete:: Remove an entry in a Key Store - - -File: cp-tools.info, Node: Command -keyclone, Next: Command -storepasswd, Prev: Management Commands, Up: Management Commands - -2.2.7.1 The '-keyclone' command -............................... - -Use this command to clone an existing Key Entry and store it under a new -(different) Alias protecting, its private key material with possibly a -new password. - -'-alias ALIAS' - For more details *note ALIAS: alias. - -'-dest ALIAS' - Use this option to specify the new Alias which will be used to - identify the cloned copy of the Key Entry. - -'-keypass PASSWORD' - Use this option to specify the password which the tool will use to - unlock the Key Entry associated with the designated Alias. - - If this option is omitted, the tool will first attempt to unlock - the Key Entry using the same password protecting the key store. If - this fails, you will then be prompted to provide a password. - -'-new PASSWORD' - Use this option to specify the password protecting the private key - material of the newly cloned copy of the Key Entry. - -'-storetype STORE_TYPE' - For more details *note STORE_TYPE: storetype. - -'-keystore URL' - For more details *note URL: keystore. - -'-storepass PASSWORD' - For more details *note PASSWORD: storepass. - -'-provider PROVIDER_CLASS_NAME' - For more details *note PROVIDER_CLASS_NAME: provider. - -'-v' - For more details *note verbose::. - - -File: cp-tools.info, Node: Command -storepasswd, Next: Command -keypasswd, Prev: Command -keyclone, Up: Management Commands - -2.2.7.2 The '-storepasswd' command -.................................. - -Use this command to change the password protecting a key store. - -'-new PASSWORD' - The new, and different, password which will be used to protect the - designated key store. - -'-storetype STORE_TYPE' - For more details *note STORE_TYPE: storetype. - -'-keystore URL' - For more details *note URL: keystore. - -'-storepass PASSWORD' - For more details *note PASSWORD: storepass. - -'-provider PROVIDER_CLASS_NAME' - For more details *note PROVIDER_CLASS_NAME: provider. - -'-v' - For more details *note verbose::. - - -File: cp-tools.info, Node: Command -keypasswd, Next: Command -delete, Prev: Command -storepasswd, Up: Management Commands - -2.2.7.3 The '-keypasswd' command -................................ - -Use this command to change the password protecting the private key -material of a designated Key Entry. - -'-alias ALIAS' - For more details *note ALIAS: alias. - - Use this option to specify the password which the tool will use to - unlock the Key Entry associated with the designated Alias. - - If this option is omitted, the tool will first attempt to unlock - the Key Entry using the same password protecting the key store. If - this fails, you will then be prompted to provide a password. - -'-new PASSWORD' - The new, and different, password which will be used to protect the - private key material of the designated Key Entry. - -'-storetype STORE_TYPE' - For more details *note STORE_TYPE: storetype. - -'-keystore URL' - For more details *note URL: keystore. - -'-storepass PASSWORD' - For more details *note PASSWORD: storepass. - -'-provider PROVIDER_CLASS_NAME' - For more details *note PROVIDER_CLASS_NAME: provider. - -'-v' - For more details *note verbose::. - - -File: cp-tools.info, Node: Command -delete, Prev: Command -keypasswd, Up: Management Commands - -2.2.7.4 The '-delete' command -............................. - -Use this command to delete a designated key store entry. - -'-alias ALIAS' - For more details *note ALIAS: alias. - -'-storetype STORE_TYPE' - For more details *note STORE_TYPE: storetype. - -'-keystore URL' - For more details *note URL: keystore. - -'-storepass PASSWORD' - For more details *note PASSWORD: storepass. - -'-provider PROVIDER_CLASS_NAME' - For more details *note PROVIDER_CLASS_NAME: provider. - -'-v' - For more details *note verbose::. - - -File: cp-tools.info, Node: Other Tools, Next: I18N Issues, Prev: Security Tools, Up: Top - -3 Other Tools -************* - -This is a list of currently undocumented classpath tools: jar, javah, -gcjh, native2ascii, orbd, serialver, rmid, rmiregistry and tnameserv. - -* Menu: - -* jar Tool:: Archive tool for Java archives -* javah Tool:: A java header compiler -* gcjh Tool:: A java header compiler (old version) -* native2ascii Tool:: An encoding converter -* orbd Tool:: An object request broker daemon -* serialver Tool:: A serial version command -* rmid Tool:: RMI activation daemon -* rmiregistry Tool:: Remote object registry -* tnameserv Tool:: Naming service -* gjdoc Tool:: A documentation generator - - -File: cp-tools.info, Node: jar Tool, Next: javah Tool, Up: Other Tools - -3.1 The 'jar' Tool -================== - -'gjar' is an implementation of Sun's jar utility that comes with the -JDK. - - If any file is a directory then it is processed recursively. The -manifest file name and the archive file name needs to be specified in -the same order the '-m' and '-f' flags are specified. - - Operation mode: - -'-c' - Create new archive. - -'-t' - List table of contents for archive. - -'-x' - Extract named (or all) files from archive. - -'-u' - Update existing archive. - -'-i FILE' - Compute archive index. - - Operation modifiers: - -'-f FILE' - Specify archive file name. - -'-0' - Store only; use no ZIP compression. - -'-v' - Generate verbose output on standard output. - -'-M' - Do not create a manifest file for the entries. - -'-m MANIFEST' - Include manifest information from specified MANIFEST file. - - File name selection: - -'-C DIR FILE' - Change to the DIR and include the following FILE. - -'-@' - Read the names of the files to add to the archive from stdin. This - option is supported only in combination with '-c' or '-u'. Non - standard option added in the GCC version. - - Standard options: - -'-help' - Print help text, then exit. -'-version' - Print version number, then exit. -'-JOPTION' - Pass argument to the Java runtime. - - java(1), ... - - -File: cp-tools.info, Node: javah Tool, Next: gcjh Tool, Prev: jar Tool, Up: Other Tools - -3.2 The 'javah' Tool -==================== - -The 'gjavah' program is used to generate header files from class files. -It can generate both CNI and JNI header files, as well as stub -implementation files which can be used as a basis for implementing the -required native methods. - -'-d DIR' - Set output directory. - -'-o FILE' - Set output file (only one of '-d' or '-o' may be used). - -'-cmdfile FILE' - Read command file. - -'-all DIR' - Operate on all class files under directory DIR. - -'-stubs' - Emit stub implementation. - -'-jni' - Emit JNI stubs or header (default). - -'-cni' - Emit CNI stubs or header (default JNI). - -'-verbose' - Set verbose mode. - -'-force' - Output files should always be written. - - Class path options: -'-classpath PATH' - Set the class path. - -'-IDIR' - Add directory to class path. - -'-bootclasspath PATH' - Set the boot class path. - -'-extdirs PATH' - Set the extension directory path. - - Standard options: -'-help' - Print help text, then exit. -'-version' - Print version number, then exit. -'-JOPTION' - Pass argument to the Java runtime. - - javac(1), ... - - -File: cp-tools.info, Node: gcjh Tool, Next: native2ascii Tool, Prev: javah Tool, Up: Other Tools - -3.3 The 'gcjh' Tool -=================== - -The 'gcjh' program is used to generate header files from class files. -It can generate both CNI and JNI header files, as well as stub -implementation files which can be used as a basis for implementing the -required native methods. It is similar to 'javah' but has slightly -different command line options, and defaults to CNI. - - See 'javah' for a full description; this page only lists the -additional options provided by 'gcjh'. - - CNI text options -'-add TEXT' - Insert TEXT into class body. -'-append TEXT' - Append TEXT after class declaration. -'-friend TEXT' - Insert TEXT as a 'friend' declaration. -'-prepend TEXT' - Insert TEXT before start of class. - - Compatibility options (unused) -'-td DIR' -'-M' -'-MM' -'-MD' -'-MMD' - Unused compatibility option. - - Standard options: -'-help' - Print help text, then exit. -'-version' - Print version number, then exit. -'-JOPTION' - Pass argument to the Java runtime. - - javac(1), javah(1), ... - - -File: cp-tools.info, Node: native2ascii Tool, Next: orbd Tool, Prev: gcjh Tool, Up: Other Tools - -3.4 The 'native2ascii' Tool -=========================== - -To be written ... - -'-encoding NAME' - Set the encoding to use. - -'-reversed' - Convert from encoding to native. - - Standard options: -'-help' - Print help text, then exit. -'-version' - Print version number, then exit. -'-JOPTION' - Pass argument to the Java runtime. - - javac(1), ... - - -File: cp-tools.info, Node: orbd Tool, Next: serialver Tool, Prev: native2ascii Tool, Up: Other Tools - -3.5 The 'orbd' object request broker daemon -=========================================== - -To be written ... - -'-ORBInitialPort PORT' - Port on which persistent naming service is to be started. - -'-ior FILE' - File in which to store persistent naming service's IOR reference - -'-directory DIR' - Directory in which to store persistent data. - -'-restart' - Restart persistent naming service, clearing persistent naming - database. - - Standard options: -'-help' - Print help text, then exit. -'-version' - Print version number, then exit. -'-JOPTION' - Pass argument to the Java runtime. - - java(1), ... - - -File: cp-tools.info, Node: serialver Tool, Next: rmid Tool, Prev: orbd Tool, Up: Other Tools - -3.6 The 'serialver' version command -=================================== - -Print the serialVersionUID of the specified classes. - -'-classpath PATH' - Class path to use to find classes. - - Standard options: -'-help' - Print help text, then exit. -'-version' - Print version number, then exit. -'-JOPTION' - Pass argument to the Java runtime. - - javac(1), ... - - -File: cp-tools.info, Node: rmid Tool, Next: rmiregistry Tool, Prev: serialver Tool, Up: Other Tools - -3.7 The 'rmid' RMI activation system daemon -=========================================== - -'rmiregistry' starts a remote object registry on the current host. If -no port number is specified, then port 1099 is used. - - Activation process control: -'-port PORT' - Port on which activation system is to be started. - -'-restart' - Restart activation system, clearing persistent naming database, if - any. - -'-stop' - Stop activation system. - - Persistence: -'-persistent' - Make activation system persistent. - -'-directory DIR' - Directory in which to store persistent data. - - Debugging: -'-verbose' - Log binding events to standard out. - - Standard options: -'-help' - Print help text, then exit. -'-version' - Print version number, then exit. -'-JOPTION' - Pass argument to the Java runtime. - - java(1), ... - - -File: cp-tools.info, Node: rmiregistry Tool, Next: tnameserv Tool, Prev: rmid Tool, Up: Other Tools - -3.8 The 'rmiregistry' Tool -========================== - -'grmiregistry' starts a remote object registry on the current host. If -no port number is specified, then port 1099 is used. - - Registry process control: -'-restart' - Restart RMI naming service, clearing persistent naming database, if - any. - -'-stop' - Stop RMI naming service. - - Persistence: -'-persistent' - Make RMI naming service persistent. - -'-directory DIR' - Directory in which to store persistent data. - - Debugging: -'-verbose' - Log binding events to standard out. - - Standard options: -'-help' - Print help text, then exit. -'-version' - Print version number, then exit. -'-JOPTION' - Pass argument to the Java runtime. - - java(1), ... - - -File: cp-tools.info, Node: tnameserv Tool, Next: gjdoc Tool, Prev: rmiregistry Tool, Up: Other Tools - -3.9 The 'tnameserv' Tool -======================== - -To be written ... - -'-ORBInitialPort PORT' - Port on which naming service is to be started. - -'-ior FILE' - File in which to store naming service's IOR reference. - - Standard options: -'-help' - Print help text, then exit. -'-version' - Print version number, then exit. -'-JOPTION' - Pass argument to the Java runtime. - - java(1), ... - - Info entry for 'gjdoc'. Please report bugs to -<http://savannah.gnu.org/bugs/?group=classpath>. Julian Scheid - - -File: cp-tools.info, Node: gjdoc Tool, Prev: tnameserv Tool, Up: Other Tools - -4 Generating HTML Documentation -******************************* - -Gjdoc can be used in two ways: as a stand-alone documentation tool, or -as a driver for a user-specified Doclet. *Note Other Doclets::. - - In the default mode, Gjdoc will use the Standard Doclet 'HtmlDoclet' -to generate a set of HTML pages. The canonical usage is: - - gjdoc -s src/java/ -all -d api-docs/ - - Here, 'src/java/' is the root of your source code class hierarchy, -'-all' means that all valid Java files found under this root directory -should be processed, and 'api-docs/' is the directory where the -generated documentation should be placed. - - To learn more about running Doclets other than the Standard Doclet, -refer to the manual. *Note Invoking a Custom Doclet::. - -* Menu: - -* Invoking the Standard Doclet:: How to generate HTML documentation. -* Invoking a Custom Doclet:: How to run third-party and other - built-in Doclets. - -* Option Summary by Type:: Brief list of all options, grouped by type. -* Gjdoc Option Summary:: List of all options accepted by Gjdoc. - -* Source Set Options:: Select the set of source codes to run Gjdoc on. -* Source Format Options:: Specify the format of the source codes to document. - -* Interlinking Options:: Connection your documentation with other projects. -* Output Control Options:: Specify the target directory and locale, and more. -* Generation Options:: Select which pieces of information to generate. -* Decoration Options:: Add or modify some titles, headers and footers or - override/amend static resources like stylesheets. -* Taglet Options:: Define your own javadoc @tags - -* Virtual Machine Options:: -* Verbosity Options:: -* Doclet Options:: - -* Other Doclets:: Generating Other Output Types -* Gjdoc Concepts:: Advanced Concepts - - -File: cp-tools.info, Node: Invoking the Standard Doclet, Next: Invoking a Custom Doclet, Up: gjdoc Tool - -4.1 Invoking the Standard Doclet -================================ - -Running the Gjdoc Standard Doclet 'HtmlDoclet' is the default mode of -operation for Gjdoc. This section lists the command line options you -can specify in this mode. It doesn't distinguish between general Gjdoc -options and options specific to the Standard Doclet. - - If you want to learn which options are accepted when Gjdoc is used as -a doclet driver, *Note Invoking a Custom Doclet::. - -* Menu: - -* Source Set Options:: Select the set of source codes to run Gjdoc on. -* Source Format Options:: Specify the format of the source codes to document. - -* Output Control Options:: Specify the target directory and locale, and more. -* Generation Options:: Select which pieces of information to generate. -* Decoration Options:: Add or modify some titles, headers and footers or - override/amend static resources like stylesheets. -* Taglet Options:: Define your own javadoc @tags - -* Virtual Machine Options:: -* Doclet Options:: - - -File: cp-tools.info, Node: Option Summary by Type, Next: Gjdoc Option Summary, Prev: Invoking a Custom Doclet, Up: gjdoc Tool - -4.2 Option Summary by Type -========================== - -Here is a summary of all the options of both Gjdoc and the Standard -Doclet, grouped by type. Explanations are in the following sections. - -_Source Set Options_ - *Note Options For Specifying the Source Files To Operate on: Source - Set Options. - -sourcepath PATHLIST -subpackages PKGLIST -exclude PKGLIST - -_Source Format Options_ - *Note Options For Specifying the Source Format: Source Format - Options. - -source RELEASE -encoding ENCODING -breakiterator - -_Interlinking Options_ - *Note Options For Specifying the Source Files To Operate on: - Interlinking Options. - -link URL -linkoffline URL FILE -noqualifier PKG:PKG:... - -_Generation Options_ - *Note Options Controlling What is Included in the Output: - Generation Options. - -author -licensetext -use -version -splitindex -noindex - -nodeprecated -nodeprecatedlist -nohelp -nonavbar - -nosince -notree -public -protected -package -private - -docfilessubdirs -excludedocfilessubdir DIRNAME - -linksource - -_Output Options_ - *Note Options Controlling the Output: Generation Options. - -d -locale NAME -charset CHARSET -docencoding CHARSET - -validhtml -baseurl URL - -_Decoration Options_ - -windowtitle TEXT -doctitle TEXT -title TEXT - -header TEXT -footer TEXT -bottom TEXT - -helpfile FILE -stylesheetfile FILE -addstylesheet FILE - -group GROUPHEADING PKGPATTERN:PKGPATTERN:... - -_Taglet Options_ - *Note Options For Specifying user-defined Taglets: Taglet Options. - -tagletpath -taglet CLASSNAME -tag TAGSPEC - -_Doclet Options_ - *Note Options For Specifying the Doclet to use: Doclet Options. - -docletpath -doclet CLASSNAME - -_Verbosity Options_ - *Note Options Controlling Gjdoc Behavior: Verbosity Options. - -quiet -verbose - -_Virtual Machine Options_ - *Note Options Controlling Gjdoc Behavior: Virtual Machine Options. - -classpath -bootclasspath -J VMOPT - -* Menu: - -* Virtual Machine Options:: Controlling the kind of output: - an executable, object files, assembler files, - or preprocessed source. - - -File: cp-tools.info, Node: Source Set Options, Next: Source Format Options, Prev: Gjdoc Option Summary, Up: gjdoc Tool - -4.3 Selecting which Source Files to Process -=========================================== - -'-s PATHLIST' -'-sourcepath PATHLIST' - Look for source files in the specified directory or directories. - - PATHLIST should be one or more directory paths separated by your - platform's path separator (usually ':' or ';'). - - If this option is not given, 'gjdoc' will look for source files in - the current directory. - - The directories specified should be root directories in terms of - the Java package system. For example, if you want to generate - documentation for classes in package 'foo.bar', you must specify - the directory containing the top-level ''foo'' sub-directory, not - the directory ''foo/bar/'' in which the Java source files reside. - - The short-hand alias '-s' is specific to 'gjdoc' and not compatible - to Sun 'javadoc'. - -'-all' - _[EXPERIMENTAL]_ Process all valid Java source files found in the - directories listed in the source path and their sub-directories. - - This is an option specific to 'gjdoc' and not compatible to Sun - 'javadoc'. - -'-subpackages PKG:PKG:...' - Process the classes in the given Java packages and all - sub-packages, recursively. Note that multiple package names must - be separated with colons instead of whitespace. - -'-exclude PKG:PKG:...' - Do not process classes in the given Java packages and all - sub-packages, recursively. This option can be used in conjunction - with '-all' or '-subpackages' in order to exclude individual - packages or package sub-trees from the output. - -'PACKAGES...' - Process all classes in the given Java packages. - -'SOURCEFILES...' - Process the classes in the given Java source files. - - -File: cp-tools.info, Node: Source Format Options, Next: Interlinking Options, Prev: Source Set Options, Up: gjdoc Tool - -4.4 Specifying the Format of Input Files -======================================== - -'-source RELEASE' - Assume that the source files are targeted at the given release of - the Java platform. - - RELEASE should be the version number of a Java platform release in - the format MAJOR.MINOR, for example '1.4'. - - This option is currently ignored except that an error is raised if - a release number other than '1.2', '1.3' or '1.4' is specified. - -'-encoding CHARSET' - Assume that the source files are encoded using CHARSET. - - Examples for CHARSET are 'US-ASCII', 'ISO-8859-1' or 'UTF-8'. - - The semantics of CHARSET are identical to those of - 'java.nio.charset.Charset.forName(String)'. - -'-breakiterator' - Use the locale's java.text.BreakIterator instead of the internal - first sentence detector. - - By default, 'gjdoc' uses an internal algorithm to determine where a - sentence ends. When this option is given, it will instead use the - 'java.text.BreakIterator' instance for the locale given with - '-locale' (or the default locale). - - This option should be specified when applying 'gjdoc' to source - code commented in a non-latin language for which the default first - sentence detector does not work. For all other cases, the default - (do not use BreakIterator) produces better results at the time of - this writing. - - -File: cp-tools.info, Node: Interlinking Options, Next: Output Control Options, Prev: Source Format Options, Up: gjdoc Tool - -4.5 Interlinking with other Documentation Sets -============================================== - -'-link URL' - - Create hyperlinks to another documentation set. - - By default, 'gjdoc' will only create hyperlinks to classes in the - source set. Use this option to additionally create hyperlinks to - classes covered by the specified documentation set. - - URL should be the root URL of the other documentation set. For - example, to add hyperlinks to GNU Classpath, specify the following: - - -link http://developer.classpath.org/doc/ - - The '-link' option can be specified multiple times. - - Note that specifying the '-link' option will cause an HTTP access - every time gjdoc is invoked. You can use '-linkoffline' instead to - avoid this access. - -'-linkoffline URL FILE' - - Create hyperlinks to another documentation set which is also - present on the local file system. - - This option works exactly like '-link', except that it accesses the - local file system instead of the network for determining which - classes are covered by the linked documentation set. - - When using '-linkoffline' the remote documentation set is not - accessed at all, which can significantly speed up generation time - depending on your network connection. The generated hyperlinks to - the documentation set however refer to the remote set, not to the - local one, so that you can distribute the documentation without any - further dependencies. - - The '-linkoffline' option can be specified multiple times. - -'-noqualifier PKG:PKG:...' - - Do not qualify names of classes in the given packages with their - package name. - - By default, a class name is displayed unqualified only if the class - is part of the source set or a linked documentation set, and - qualified with the name of its containing package if it is not. - You can use this option to force unqualified names for classes even - if they are not part of the documentation set. - - For example, usually a reference to the String class is represented - fully-qualified as 'java.lang.String' (unless you link to the - appropriate documentation set using '-link') because it isn't part - of the documentation set. You can specify '-noqualifier java.lang' - to render the same references just as 'String'. - - Note that for all unqualified class names, a tooltip is provided - when you place your mouse pointer over it in the HTML - documentation. - -'-noqualifier 'all'' - Omit package name qualifier from all class names. - - Specify this option to omit package name qualifiers altogether, - - -File: cp-tools.info, Node: Generation Options, Next: Decoration Options, Prev: Output Control Options, Up: gjdoc Tool - -4.6 Selecting which Information to Generate -=========================================== - -'-public' - Only include public members of public classes in the output. By - default, protected class members are included as well. - -'-protected' - - Include public or protected members of public classes in the - output. This is the default. - -'-package' - - Include public, protected and package-private members of public and - package-private classes. - -'-private' - - Include all classes and class members regardless of their access - level. - -'-splitindex' - Generate one index page per letter instead of a single, monolithic - index page. - - By default, the index created by the Standard Doclet contains all - entries on a single page. This is fine for small documentation - sets, but for large sets you should specify this option. - -'-nosince' - Ignore '@since' tags in javadoc comments. - - By default, the generated output contains sections listing the - version of your API since which the package, class or class member - in question exists when this tag is encountered. Specify this - option to omit this information. - -'-notree' - Do not generate any tree pages. - - By default, the generated output includes one inheritance tree per - package, and - if the documentation set consists of multiple - packages - a page with the full inheritance tree. Specify this - option to omit generation of these pages. - -'-noindex' - Do not output the alphabetical index. - - By default, gjdoc generates an alphabetical index of all program - elements in the documentation set (packages, classes, inner - classes, constructors, methods, and fields). Specify this option - to omit this information. - -'-nohelp' - Do not generate the help page. - - This option is currently ignored as the Standard Doclet doesn't - provide a help page. - -'-nodeprecated' - Do not output inline information about deprecated packages, classes - or class members. - - By default, the Standard Doclet adds a highlighted paragraph with - deprecation information to the description of each deprecated - program element. Specify this option to omit this information. - -'-nodeprecatedlist' - Do not output the summary page for deprecated API elements. - - By default, the Standard Doclet generates a page listing all - deprecated API elements along with a deprecation description which - usually includes the reason for deprecation and possible - alternatives. Specify this option to omit this information. - -'-nonavbar' - Do not output the navigation bar, header, and footer. - - By default, each output page is equipped with a top navigation bar - (which may include a user-specified header) and a bottom navigation - bar (which may include a user-specified footer). Specify this - option to omit this decoration. - -'-nocomment' - - Omit all documentation text from the generated files and output - only declarations and program element relationships. - - This option is here for compatibility with 'javadoc'. If you plan - on extracting information about your project via 'gjdoc', you - should consider using a different Doclet for your purposes instead, - for example XmlDoclet. You could also use the Doclet API directly - by implementing a new Doclet. - -'-linksource' - - Generate a page with syntax-highlighted source code for each class. - By default, this page is not generated. - - The source code can be accessed by clicking on the button labelled - "Source" in the navigation bar, or by clicking on the name of a - constructor, field, method, or inner class in the detail section of - a class documentation page. - -'-use' - - Generate a page with cross-reference information. By default, this - page is not generated. - - The cross-reference information can be accessed by clicking on the - button labelled 'Use' in the navigation bar. - - The 'Use' page lists all classes/interfaces in the documentation - set that extend/implement the class (type) in question; fields of - the type; methods or constructors accepting a parameter of the - type; methods returning the type; and methods or constructors - throwing the type. - -'-author' - Include author information in the output. - - When specified, author information as specified using the '@author' - tag in javadoc comments is incorporated into the output. By - default, '@author' tags are ignored. - -'-version' - Include version information in the output. - - When specified, version information as specified using the - '@version' tag in javadoc comments is incorporated into the output. - By default, '@version' tags are ignored. - -'-licensetext' - - Assume that the first comment in each source file contains the - license text, and add license information to the footer of each - generated class page. - - This is an option specific to 'gjdoc' and not compatible to Sun - 'javadoc'. - - This option is intended for use with free and open source projects - where source code is typically prefixed with a boilerplate license - comment, when there are legal reasons for including the license in - the documentation. - -'-docfilessubdirs' - - Recursively copy all files in the 'doc-files' sub-directory of each - package directory. - - Usually, only the files in the 'doc-files' sub-directory are copied - without descending recursively. - - *Note Adding Custom Resources::. - -'-excludedocfilessubdir NAME:NAME:...' - - Do not copy some directories directly under the 'doc-files' - sub-directories when descending recursively. - - The argument to this option should be a colon-separated list of - directory names. - - This option only makes sense if '-docfilessubdirs' is also - specified. In this case, any sub-directory located directly - beneath a 'doc-files' directory is omitted if listed. - - -File: cp-tools.info, Node: Taglet Options, Next: Virtual Machine Options, Prev: Decoration Options, Up: gjdoc Tool - -4.7 Custom Documentation Tags -============================= - -'-tagletpath PATHLIST' - Search PATHLIST when loading subsequent Taglet classes specified - using '-taglet'. - - PATHLIST should be one or more paths to a directory or jar file, - separated by your platform's path separator (usually ':' or ';'). - -'-taglet CLASSNAME' - Register a Taglet. - - CLASSNAME should be the fully-qualified name of a Java class - implementing 'com.sun.tools.doclets.Taglet'. - - The Taglet classes will be loaded from the classpath specified - using '-tagletpath', from the classpath specified using - '-classpath' and from the default classpath. - - See the documentation of 'com.sun.tools.doclets.Taglet' for further - information. - - Note that for simple tags, there is also '-tag'. - -'-tag TAGSPEC' - Register a generic Taglet. - - The format of TAGSPEC must be '<tagname>:<flags>:"<taghead>"'. - - TAGNAME is the tag name to match, without the leading @ sign. - - FLAGS is one or more of the following characters, where each - character specifies a source code context in which the tag is to be - recognized. - - 'a' - all contexts - 'c' - constructors - 'f' - fields - 'm' - methods - 'o' - overview - 'p' - packages - 't' - types (classes, interfaces, exceptions, errors) - 'X' - special character which temporarily disables the Taglet - altogether. - - TAGHEAD is the string to display in the header of the section - devoted to the tag in question. - - For example, to define a tag matching '@cvsid' which is to be - accepted in overview, package and type pages and which is labelled - with the header 'CVS ID', you would specify: - - -tag cvsid:tpo:"CVS ID" - - Let's say that a class javadoc comment contains - - @cvsid $Id: cp-tools.texinfo,v 1.9 2012-03-07 15:27:27 gnu_andrew Exp $ - - Then the HTML output will contain something like - - CVS ID: - $Id: cp-tools.texinfo,v 1.9 2012-03-07 15:27:27 gnu_andrew Exp $ - - -File: cp-tools.info, Node: Doclet Options, Next: Other Doclets, Prev: Verbosity Options, Up: gjdoc Tool - -4.8 Running Other Doclets -========================= - -'-docletpath PATHLIST' - Search PATHLIST when loading classes for the Doclet specified using - '-doclet'. - - PATHLIST should be one or more paths to a directory or jar file, - separated by your platform's path separator (usually ':' or ';'). - -'-doclet CLASSNAME' - Run the specified doclet instead of the standard HtmlDoclet. - - CLASSNAME should be the fully-qualified name of a class which has a - public default constructor and contain a method with the following - signature: - - import com.sun.javadoc.RootDoc; - public static boolean start(RootDoc rootDoc) - - The Doclet classes will be loaded from the classpath specified - using '-docletpath', from the classpath specified using - '-classpath' and from the default classpath. - - The 'start' method should process the information exposed by the - Doclet API via 'rootDoc' and return 'true' on success, 'false' on - failure. - - If you are using a third-party doclet, refer to its documentation - for further instructions. Note that support for third-party - doclets is experimental. Please report any problems you encounter, - or provide feedback when successfully running third-party applets. - - This option can be specified multiple times, in which case all - doclets are executed with the same information tree exposed via the - Doclet API for each Doclet run. - - -File: cp-tools.info, Node: Decoration Options, Next: Taglet Options, Prev: Generation Options, Up: gjdoc Tool - -4.9 Adding Information to the Output -==================================== - -'-windowtitle TEXT' - Use TEXT as the browser window title prefix. - - When specified, the browser window title for each page will be - prefixed with TEXT instead of the default string 'Generated API - Documentation'. - - TEXT should be plain text (it should not contain HTML tags). - -'-doctitle TEXT' - Set the header text of the overview page to TEXT. - - TEXT should be a short plain text string. - - When generating documentation for a single package, specifying this - option forces generation of the overview page. - -'-header HTMLTEXT' - - Add HTMLTEXT to the right upper corner of every generated page. - HTMLTEXT is usually set to the name of the project being - documented. - -'-footer HTMLTEXT' - - Add HTMLTEXT to the right bottom corner of every generated page. - HTMLTEXT is often set to the same value as for '-header'. - -'-bottom HTMLTEXT' - - Add HTMLTEXT to the very bottom of every generated page, spanning - the whole width of the page. When specified, HTMLTEXT usually - consists of a copyright notice and/or links to other project pages. - -'-addstylesheet FILE' - - Augment the default CSS style sheets with the user-specified - stylesheet FILE. - - The given stylesheet is simply loaded by each HTML page in addition - to the default ones, as the last stylesheet. - - Note that the CSS cascading rules apply. That is, your style - properties will only be assigned if they have a higher cascading - order than 'gjdoc''s default style. One simple way to make sure - that this is the case is to declare your overrides '!important'. - - See <http://www.w3.org/TR/REC-CSS2/cascade.html#cascading-order>. - -'-group HEADING PKGWILDCARD:PKGWILDCARD:...' - - Arrange the given packages in a separate group on the overview - page. - - The first argument should be a short plain text which is used as - the title of the package group. The second argument should be a - colon-separated list of package wildcards. The group will consist - of all packages in the documentation set whose name matches any of - the given wildcards. - - There is only one wildcard character, '*', which matches both - letters in package name components and the '.' separating package - name components. For example, 'j*regex' would match package - 'java.util.regex'. A more useful example would be 'javax.swing*' - to match 'javax.swing' and all of its sub-packages. - - This option can be given multiple times. - - FIXME: Information about group nesting here. - - gjdoc -group "Core Classes" 'java*' \ - -group "Swing" 'javax.swing*' \ - -group "XML APIs" 'javax.xml*' \ - -group "Other Extensions" javax* \ - ... - -'-overview FILE' - - Add the XHTML body fragment from FILE to the overview page. - - FILE should contain an XHTML fragment with the HTML 'body' tag as - the root node. *Note XHTML Fragments::. - - This option can be used to supply a description of the - documentation set as a whole. - - When specified, the first sentence of the fragment will be put - above the tables listing the documented packages, along with a link - to the full copy of the fragment which is put below the tables. - *Note First Sentence Detector::. - - When generating documentation for a single package, specifying this - option forces generation of the overview page. - -'-stylesheetfile FILE' - - Use the CSS stylesheet in FILE instead of the default CSS - stylesheets. - - If you only want to override parts of the default stylesheets, use - '-addstylesheet' instead. - -'-title TEXT' - - _Deprecated._ Use '-doctitle' TEXT instead. - -'-helpfile FILE' - - This option is currently ignored. - - When implemented, it will use the XHTML fragment in FILE for the - help page contents instead of the default help text. - - -File: cp-tools.info, Node: Output Control Options, Next: Generation Options, Prev: Interlinking Options, Up: gjdoc Tool - -4.10 Controlling the Output. -============================ - -'-d DIRECTORY' - Place all output files into DIRECTORY (and sub-directories). - DIRECTORY will be created if it does not exist, including all - non-existing parent directories and all required sub-directories. - - If not specified, output will be placed into the current directory. - -'-locale NAME' - - Use locale NAME instead of the default locale for all purposes. - - NAME should be a locale specifier in the form 'll_CC[_VAR]' where - 'll' is a lowercase two-letter ISO-639 language code, 'CC' is an - optional uppercase two-letter ISO-3166 country code, and 'VAR' is - an optional variant code. For example, 'en' specifies English, - 'en_US' specifies US English, and 'en_US_WIN' specifies a deviant - variant of the US English locale. - - Note that the semantics of this option correspond exactly to those - of the constructors of class 'java.util.Locale'. - - This option currently only determines which Collator is being used - for sorting output elements. This means that the locale will only - have an effect when you are using non-ASCII characters in - identifiers. - -'-charset CHARSET' - - _Deprecated._ Override the specified encoding in output XHTML - files with the one given by 'charset'. - - If this option is not given, the encoding specification in output - XHTML is chosen to match the encoding used when writing the file - (the encoding given with '-docencoding', or your platform's default - encoding). - - The semantics for CHARSET are specified here: - <http://www.w3.org/TR/2000/REC-xml-20001006#NT-EncName>. For all - practical purposes, they are identical to those of the other - options accepting charset parameters. - - This option is here for compatibility with 'javadoc' and should be - avoided. - -'-docencoding CHARSET' - - Use the given charset encoding when writing output files instead of - your platform's default encoding. - - Examples for CHARSET are 'US-ASCII', 'ISO-8859-1' or 'UTF-8'. - - The semantics of this option correspond exactly to those of the - constructors of class 'java.util.Locale'. - -'-validhtml' - - Force generation of valid XHTML code. This breaks compatibility to - the traditional Javadoc tool to some extent. - - If this option is specified, anchor names will be mangled so that - they are valid according to the XHTML 1.1 specification. However, - a documentation set generated with this option cannot be linked to - properly using the traditional Javadoc tool. It can be linked to - just fine using Gjdoc, though. - - Without this option, anchor names for executable class members use - the traditional format, for example: "foo(String,int[])". This is - compatible to the traditional Javadoc tool, but according to both - the HTML 4.0 and XHTML 1.0 and 1.1 specifications, this format - includes illegal characters. Parentheses, square brackets, and the - comma are not allowed in anchor names. - -'-baseurl URL' - - Hardwire a page URL relative to URL into each generated page. - - If you are generating documentation which will exclusively be - available at a certain URL, you should use this option to specify - this URL. - - This can help avoid certain redirect attacks used by spammers, and - it can be helpful for certain web clients. - - -File: cp-tools.info, Node: Verbosity Options, Next: Doclet Options, Prev: Virtual Machine Options, Up: gjdoc Tool - -4.11 Verbosity Options -====================== - -'-quiet' - Suppress all output except for warnings and error messages. - -'-verbose' - Be very verbose about what 'gjdoc' is doing. - - This option is currently ignored. - - -File: cp-tools.info, Node: Virtual Machine Options, Next: Verbosity Options, Prev: Taglet Options, Up: gjdoc Tool - -4.12 Virtual Machine Options -============================ - -Sun's 'javadoc' tool seems to be based on 'javac' and as such it seems -to operate on the VM level. 'gjdoc', in contrast, is a pure Java -application. - - Therefore, 'gjdoc' can only fake, or simulate, the following VM-level -options. - -'-classpath PATHLIST' - Set the Virtual Machine 'classpath' to PATHLIST. - - In most cases you should use '-docletpath' or '-tagletpath' instead - of this option. - - PATHLIST should be one or more paths to a directory or jar file, - separated by your platform's path separator (usually ':' or ';'). - - If this option is not intercepted at the wrapper level, 'gjdoc' - currently fakes it by calling - 'System.setProperty("java.class.path", PATHLIST);' and outputs a - warning. - -'-bootclasspath PATHLIST' - Set the Virtual Machine 'bootclasspath' to PATHLIST. - - If this option is not intercepted at the wrapper level, 'gjdoc' - outputs a warning. - -'-JVMOPT' - - Pass an arbitrary parameter to the Virtual Machine 'gjdoc' runs on. - - If this option is not intercepted at the wrapper level, 'gjdoc' - tries to emulate the option and outputs a warning. - - Currently, only the VM option '-D' for setting system properties is - emulated. - - -File: cp-tools.info, Node: Invoking a Custom Doclet, Next: Option Summary by Type, Prev: Invoking the Standard Doclet, Up: gjdoc Tool - -4.13 Invoking a Custom Doclet -============================= - -For invoking one of the other doclets shipping with 'gjdoc' or a -third-party doclet, the canonical usage is: - - gjdoc -s src/java/ -all \ - -docletpath /path/to/doclet.jar -doclet foo.BarDoclet \ - (more Gjdoc core options and Doclet-specific options here) - - '/path/to/doclet.jar' is a placeholder for a class path specifying -where the Doclet classes and dependencies can be found and -'foo.BarDoclet' is the fully-qualified name of the Doclet's main class. - - -File: cp-tools.info, Node: Gjdoc Option Summary, Next: Source Set Options, Prev: Option Summary by Type, Up: gjdoc Tool - -4.14 Gjdoc Option Summary -========================= - - -File: cp-tools.info, Node: Other Doclets, Next: Gjdoc Concepts, Prev: Doclet Options, Up: gjdoc Tool - -5 Generating Other Output Types -******************************* - -* Menu: - -* Built-in Doclets:: -* Third-party Doclets:: - - -File: cp-tools.info, Node: Built-in Doclets, Next: Third-party Doclets, Up: Other Doclets - -5.1 Using the Built-in Doclets -============================== - -* Menu: - -* Using XmlDoclet:: -* Using TexiDoclet:: -* Using IspellDoclet:: -* Using DebugDoclet:: - - -File: cp-tools.info, Node: Using TexiDoclet, Next: Using XmlDoclet, Up: Built-in Doclets - -5.1.1 TexiDoclet: Generating Info, PDF, and other formats ---------------------------------------------------------- - -Missing. - - -File: cp-tools.info, Node: Using XmlDoclet, Next: Using IspellDoclet, Prev: Using TexiDoclet, Up: Built-in Doclets - -5.1.2 XmlDoclet: Generating XML Documentation ---------------------------------------------- - -Missing. - - -File: cp-tools.info, Node: Using IspellDoclet, Next: Using DebugDoclet, Prev: Using XmlDoclet, Up: Built-in Doclets - -5.1.3 IspellDoclet: Spell-checking Source Code ----------------------------------------------- - -Missing. - - -File: cp-tools.info, Node: Using DebugDoclet, Prev: Using IspellDoclet, Up: Built-in Doclets - -5.1.4 DebugDoclet: Inspecting the Doclet API --------------------------------------------- - -Missing. - - -File: cp-tools.info, Node: Third-party Doclets, Prev: Built-in Doclets, Up: Other Doclets - -5.2 Using Third-Party Doclets -============================= - -* Menu: - -* DocBook Doclet:: -* PDFDoclet:: -* JUnitDoclet:: - - -File: cp-tools.info, Node: DocBook Doclet, Next: PDFDoclet, Up: Third-party Doclets - -5.2.1 DocBook Doclet --------------------- - -Missing. - - -File: cp-tools.info, Node: PDFDoclet, Next: JUnitDoclet, Prev: DocBook Doclet, Up: Third-party Doclets - -5.2.2 PDFDoclet ---------------- - -Missing. - - -File: cp-tools.info, Node: JUnitDoclet, Prev: PDFDoclet, Up: Third-party Doclets - -5.2.3 JUnitDoclet ------------------ - -Missing. - - -File: cp-tools.info, Node: Gjdoc Concepts, Prev: Other Doclets, Up: gjdoc Tool - -6 Advanced Concepts -******************* - -* Menu: - -* Writing Doclets:: -* Taglets:: -* XHTML Fragments:: -* First Sentence Detector:: -* Adding Custom Resources:: - - -File: cp-tools.info, Node: Taglets, Next: Writing Doclets, Up: Gjdoc Concepts - -6.1 Adding Custom Tags to the Documentation -=========================================== - -Missing. - - -File: cp-tools.info, Node: Writing Doclets, Next: XHTML Fragments, Prev: Taglets, Up: Gjdoc Concepts - -6.2 Writing Doclets -=================== - -If the various Doclets already available don't suit your needs, you can -write a custom Doclet yourself. - -* Menu: - -* Doclet Invocation Interface:: -* Using AbstractDoclet:: -* GNU Doclet SPI:: - - -File: cp-tools.info, Node: Doclet Invocation Interface, Next: Using AbstractDoclet, Up: Writing Doclets - -6.2.1 Implementing the Doclet Invocation Interface --------------------------------------------------- - -A Doclet is a class that contains a method with the following signature: - - public static boolean start(RootDoc rootDoc); - - ROOTDOC is the root of an object hierarchy containing the information -'gjdoc' extracted from the source files. See the Doclet API for more -details. - - 'start' should process all the information and return 'true' on -success, 'false' on failure. - - For printing status information, the Doclet should use methods -'printNotice', 'printWarning' and 'printError' instead of 'System.err'. -The Doclet can opt to use 'System.out' for redirectable output. - - -File: cp-tools.info, Node: Using AbstractDoclet, Next: GNU Doclet SPI, Prev: Doclet Invocation Interface, Up: Writing Doclets - -6.2.2 Deriving Your Doclet from AbstractDoclet ----------------------------------------------- - -You may want your Doclet to provide functionality similar to HtmlDoclet. -For example, you may want it to support Taglets, generate Index, Tree, -and Uses pages, or show other cross-reference information like -'Overrides' and 'All Implementing Classes'. - - This information is not directly provided by the Doclet API, so your -Doclet would normally have to assemble it itself. For example, it would -have to add the names of all program elements to a list and sort this -list in order to create the Index page. - - If you want to provide this information or part of it, you should -consider deriving your class from -'gnu.classpath.tools.doclets.AbstractDoclet'. This class provides the -following benefits: - - * Handles options '-tag', '-taglet', '-tagletpath' (Taglets) - - * Provides standard taglets for @version, @author, @since, @serial, - @deprecated, @see, @param, @return and handles all related options - ('-version', '-author', '-nosince', '-nodeprecated') - - * Handles option '-d' (destination directory) - - * Handles option '-noqualifier' (classes to omit qualifier for) - - * Handles options '-docfilessubdirs' and '-excludedocfilessubdir' - (resource copying) - - * Can generate a full index or an index split by first letter - - * Can generate a full tree and package trees - - * Can generate cross-reference information - - * Can aggregate interface information (all superinterfaces, all - subinterfaces, all implementing classes) - - * Provides convenient access to constructors, fields, methods, and - inner classes sorted by name/signature instead of the default sort - order. - - * Provides various other convenience methods - - If you derive from 'AbstractDoclet', there are a number of things you -need to take care of: - - * - you should not implement the 'start(RootDoc)' method as it is already -defined by 'AbstractDoclet' so that it can care about parsing the -options. - - Instead, you implement method 'run()', 'getOptions()' and the other -abstract methods to define your Doclet's behavior. - - Note that all information provided by 'AbstractDoclet' is evaluated -lazily. That is, if your Doclet doesn't need to create an Index page, -then 'AbstractDoclet' will not spend resources on creating the -corresponding information. - - See the API documentation for -'gnu.classpath.tools.doclets.AbstractDoclet' for more details. - - You should be aware that if you base your Doclet on 'AbstractDoclet' -then you have to bundle this and all related classes with your Doclet, -with all implications such as possible licensing issues. Otherwise, -your Doclet will only be runnable on 'gjdoc' and not on other -documentation systems. Also note that 'AbstractDoclet' has not been -extensively tested in environments other than 'gjdoc'. - - -File: cp-tools.info, Node: GNU Doclet SPI, Prev: Using AbstractDoclet, Up: Writing Doclets - -6.2.3 Preparing for the GNU Doclet Service Provider Interface -------------------------------------------------------------- - -In addition to the standard Doclet invocation interface described above, -'gjdoc' also offers a Service Provider Interface conforming to the Java -standard. Adding support for this interface to your Doclet simplifies -usage for 'gjdoc' users because it makes your Doclet "discoverable". - - In order to provide the alternate interface, you have to add a class -implementing 'gnu.classpath.tools.gjdoc.spi.DocletSpi' to your Doclet -classes, and bundle all Doclet classes in a Jar file along with a file -named 'META_INF/services/gnu.classpath.tools.gjdoc.spi.DocletSpi' which -contains the name of your class implementing DocletSpi on a single line. - - Note that if your Doclet depends on third-party classes bundled in -separate Jar files, you can link in these classes using the -'Class-path:' Manifest attribute of your Doclet Jar. - - Your Doclet can then be invoked in one of the following ways: - gjdoc -docletjar /path/to/doclet.jar - gjdoc -docletpath /path/to/doclet.jar -docletname DOCLETNAME - gjdoc -docletname DOCLETNAME - - Here, DOCLETNAME is the name of your doclet as returned by -'DocletSpi.getDocletName()'. - - The last example will only work if your Doclet Jar is in 'gjdoc''s -'doclets' directory or if it is on the classpath. - - -File: cp-tools.info, Node: XHTML Fragments, Next: First Sentence Detector, Prev: Writing Doclets, Up: Gjdoc Concepts - -6.3 Well-formed Documentation Fragments -======================================= - -For many Doclets it is advantagous if the HTML code in the comments and -HTML code passed via the command line is well-formed. For example, -HtmlDoclet outputs XHTML code, and XmlDoclet XML code, both of which -results in invalid files if the user-specified HTML isn't wellformed. - - Unfortunately, comments were never required to contain well-formed -HTML code, which means that every Doclet must deal with non-wellformed -code as well. - - The 'gjdoc' built-in Doclets deal with this problem by "fixing" the -HTML code - making sure that all tags are closed, attribute values are -provided and quoted, tags are properly nested, etc. - - This approach works OK in most instances, but since it uses some -crude heuristics it can sometimes produce undesirable result. - - Therefore, in order to make sure that your comments are always -properly formatted, make sure they are well-formed as described in -XHTML 1.0: Documents must be well-formed (http://www.w3.org/TR/xhtml1/#h-4.1). - - In addition, you should use meaningful tags instead of text -formatting tags to make your output look better in other output formats -derived from your HTML code. For example, you should use the <em> tag -instead of <b> if you want to emphasize text. - - -File: cp-tools.info, Node: First Sentence Detector, Next: Adding Custom Resources, Prev: XHTML Fragments, Up: Gjdoc Concepts - -6.4 How Gjdoc Determines where the First Sentence Ends -====================================================== - -For a package, class or member summary, 'gjdoc' only shows the first -sentence of the documentation comment in question. Because 'gjdoc' is -not human, it is not always obvious to 'gjdoc' where the first sentence -ends. - - You might be tempted to say that the first sentence ends at the first -occurrence of a punctuation character like '.' or '!'. However, -consider examples like this: - This work, by Thomas J. Shahan et al., is about the middle ages. - - As you can see, it is not trivial to determine the end of the -sentence. - - 'gjdoc' gives you the choice between two approaches. By default it -uses built-in heuristics which should be compatible to Sun's 'javadoc' -tool. This approach works quiet well in most cases, at least for -english comments. - - Alternatively, you can specify option '-breakiterator' in which case -'gjdoc' will use -'java.text.BreakIterator.getSentenceInstance(LOCALE).next()' to find the -end of sentence, where LOCALE is the locale specified by option -'-locale' or the default locale if none specified. - - _NOT YET IMPLEMENTED:_ - - 'gjdoc' also allows you to explicitly delineate the first sentence by -putting it in a '<span>' tag with the CSS class 'first-sentence'. For -example: - /** - * <span class="first-sentence">This. is. the. first. - * sentence.</span> This is the second sentence. - */ - - Note that this will only work with 'gjdoc', but shouldn't hurt when -using another documentation system since the '<span>' tag usually -doesn't show up in the output. - - -File: cp-tools.info, Node: Adding Custom Resources, Prev: First Sentence Detector, Up: Gjdoc Concepts - -6.5 Adding Images and Other Resources -===================================== - -Sometimes you want to decorate your documentation with secondary -resources such as images, SVG graphics, applets, and so on. To do so, -simply put the required files in a subdirectory 'doc-files' in the -package directory corresponding to the documentation entry you want to -decorate, and refer to it with the URL 'doc-files/FILENAME'. - - For example, if you want to add an image to the description of class -'baz.FooBar', create a directory 'doc-files' in the directory 'baz' -containing 'FooBar.java' and put your file, say 'diagram.png', into that -directory. Then, add the HTML code like this to a comment in -'FooBar.java': - <img src="doc-files/diagram.png" width="200" height="150" - alt="Foo Diagram"/> - - This works because the 'doc-files' subdirectories will be copied to -the target documentation directory every time you generate the -documentation. - - Note however that by default, the 'doc-files' directory will not be -copied deeply. In other words, if you create subdirectories under -'doc-files' they will not be copied and any resources located in these -subdirectories will not be accessible in your generated documentation. -You can specify option '-docfilessubdirs' to remove this limitation. - - Sometimes you want to use option '-docfilessubdirs', but there are -certain directories which you don't want to be copied, for example -because they contain source files for the resources in 'doc-files'. For -cases like this, use '-excludedocfilessubdir' to specify directories to -be omitted. - - -File: cp-tools.info, Node: I18N Issues, Prev: Other Tools, Up: Top - -7 I18N Issues -************* - -Some tools -*note Security Tools::- allow using other than the English -language when prompting the User for input, and outputting messages. -This chapter describes the elements used to offer this support and how -they can be adapted for use with specific languages. - -* Menu: - -* Language Resources:: Where resources are located -* Message Formats:: How messages are internationalized - - -File: cp-tools.info, Node: Language Resources, Next: Message Formats, Prev: I18N Issues, Up: I18N Issues - -7.1 Language-specific resources -=============================== - -The Tools use Java 'ResourceBundle's to store messages, and message -templates they use at runtime to generate the message text itself, -depending on the locale in use at the time. - - The Resource Bundles these tools use are essentially Java Properties -files consisting of a set of Name/Value pairs. The Name is the Property -Name and the Value is a substitution string that is used when the code -references the associated Name. For example the following is a line in -a Resource Bundle used by the 'keytool' Tool: - - Command.23=A correct key password MUST be provided - - When the tool needs to signal a mandatory but missing key password, -it would reference the property named 'Command.23' and the message "'A -correct key password MUST be provided'" will be used instead. This -indirect referencing of "resources" permits replacing, as late as -possible, the English strings with strings in other languages, provided -of course Resource Bundles in those languages are provided. - - For the GNU Classpath Tools described in this Guide, the Resource -Bundles are files named 'messages[_ll[_CC[_VV]]].properties' where: - -LL - Is the 2-letter code for the Language, -CC - Is the 2-letter code for the Region, and -VV - Is the 2-letter code for the Variant of the language. - - The complete list of language codes can be found at Code for the -representation of names of languages -(http://ftp.ics.uci.edu/pub/ietf/http/related/iso639.txt). A similar -list for the region codes can be found at ISO 3166 Codes (Countries) -(http://userpage.chemie.fu-berlin.de/diverse/doc/ISO_3166.html). - - The location of the Resource Bundles for the GNU Classpath Tools is -specific to each tool. The next table shows where these files are found -in a standard GNU Classpath distribution: - -'jarsigner' - 'gnu/classpath/tools/jarsigner' -'keytool' - 'gnu/classpath/tools/keytool' - - The collection of Resource Bundles in a location act as an inverted -tree with a parent-child relationship. For example suppose in the -'gnu/classpath/tools/keytool' there are 3 message bundles named: - - 1. 'messages.properties' - 2. 'messages_fr.properties' - 3. 'messages_fr_FR.properties' - - In the above example, bundle #1 will act as the parent of bundle #2, -which in turn will act as the parent for bundle #3. This ordering is -used by the Java runtime to choose which file to load based on the set -Locale. For example if the Locale is 'fr_CH', 'messages_fr.properties' -will be used because (a) 'messages_fr_CH.properties' does not exist, but -(b) 'messages_fr.properties' is the parent for the required bundle, and -it exists. As another example, suppose the Locale was set to 'en_AU'; -then the tool will end up using 'messages.properties' because (a) -'messages_en_AU.properties' does not exist, (b) 'messages_en.properties' -which is the parent for the required bundle does not exist, but (c) -'messages.properties' exists and is the root of the hierarchy. - - You can see from the examples above that 'messages.properties' is the -safety net that the Java runtime falls back to when failing to find a -specific bundle and its parent(s). This file is always provided with -the Tool. In time, more localized versions will be included to cater -for other languages. - - In the meantime, if you are willing to contribute localized versions -of these resources, grab the 'messages.properties' for a specific tool; -translate it; save it with the appropriate language and region suffix -and mail it to 'classpath@gnu.org'. - - -File: cp-tools.info, Node: Message Formats, Prev: Language Resources, Up: I18N Issues - -7.2 Message formats -=================== - -If you open any of the 'messages.properties' described in the previous -section, you may see properties that look like so: - - Command.67=Issuer: {0} - Command.68=Serial number: {0,number} - Command.69=Valid from: {0,date,full} - {0,time,full} - Command.70=\ \ \ \ \ until: {0,date,full} - {0,time,full} - - These are Message Formats used by the tools to customize a text -string that will then be used either as a prompt for User input or as -output. - - If you are translating a 'messages.properties' be careful not to -alter text between curly braces. - - - -Tag Table: -Node: Top1103 -Node: Applet Tools6822 -Node: appletviewer Tool7395 -Node: gcjwebplugin10513 -Node: Security Tools10825 -Node: jarsigner Tool11478 -Node: Common jarsigner Options12525 -Node: Signing Options13840 -Node: Verification Options16426 -Node: keytool Tool17013 -Node: Getting Help21462 -Node: Common keytool Options22203 -Ref: alias22477 -Ref: keyalg22861 -Ref: keysize23092 -Ref: validity23358 -Ref: storetype23574 -Ref: storepass23906 -Ref: keystore24103 -Ref: provider24646 -Ref: file25054 -Ref: verbose25528 -Node: Distinguished Names25619 -Ref: dn25813 -Node: Add/Update Commands26880 -Node: Command -genkey27408 -Node: Command -import29821 -Node: Command -selfcert32968 -Node: Command -cacert35151 -Node: Command -identitydb36204 -Node: Export Commands36861 -Node: Command -certreq37177 -Node: Command -export39588 -Node: Display Commands40786 -Node: Command -list41118 -Node: Command -printcert42251 -Node: Management Commands42634 -Node: Command -keyclone43066 -Node: Command -storepasswd44469 -Node: Command -keypasswd45197 -Node: Command -delete46391 -Node: Other Tools47013 -Node: jar Tool47855 -Node: javah Tool49245 -Node: gcjh Tool50462 -Node: native2ascii Tool51570 -Node: orbd Tool52029 -Node: serialver Tool52757 -Node: rmid Tool53224 -Node: rmiregistry Tool54163 -Node: tnameserv Tool55001 -Node: gjdoc Tool55623 -Node: Invoking the Standard Doclet57612 -Node: Option Summary by Type58767 -Node: Source Set Options61196 -Node: Source Format Options63059 -Node: Interlinking Options64575 -Node: Generation Options67356 -Node: Taglet Options73463 -Node: Doclet Options75691 -Node: Decoration Options77261 -Node: Output Control Options81360 -Node: Verbosity Options84897 -Node: Virtual Machine Options85242 -Node: Invoking a Custom Doclet86638 -Node: Gjdoc Option Summary87313 -Node: Other Doclets87493 -Node: Built-in Doclets87721 -Node: Using TexiDoclet87976 -Node: Using XmlDoclet88198 -Node: Using IspellDoclet88423 -Node: Using DebugDoclet88651 -Node: Third-party Doclets88851 -Node: DocBook Doclet89067 -Node: PDFDoclet89210 -Node: JUnitDoclet89363 -Node: Gjdoc Concepts89497 -Node: Taglets89741 -Node: Writing Doclets89924 -Node: Doclet Invocation Interface90264 -Node: Using AbstractDoclet91056 -Node: GNU Doclet SPI94049 -Node: XHTML Fragments95521 -Node: First Sentence Detector96954 -Node: Adding Custom Resources98718 -Node: I18N Issues100415 -Node: Language Resources100917 -Node: Message Formats104587 - -End Tag Table |