JDK-4756688 : stddoclet: Combine -docencoding and -charset options
  • Type: Enhancement
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 1.4.0
  • Priority: P4
  • Status: Resolved
  • Resolution: Duplicate
  • OS: generic
  • CPU: generic
  • Submitted: 2002-10-02
  • Updated: 2018-01-25
  • Resolved: 2018-01-25
Related Reports
Duplicate :  
JDK-8183582 - Rationalize doclet -docencoding and -charset options
Duplicate :  
JDK-4753019 - stddoclet: "No character encoding detected" warning from HTML validator
Description
Name: dk30142			Date: 10/02/2002

The standard doclet currently has two separate but related options:
-charset and -docencoding, which, if they both take values, should 
take the same value.  The -docencoding option tells the standard doclet 
which encoding to use when writing the HTML files.  The -charset option 
independently creates the following META tag which identifies the encoding 
used when reading the HTML files:

  <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">

To play things safe, the charset should really be derived from the
character encoding named in the -docencoding option (or the default used
if this option isn't given), in the manner described in my evaluation.
Letting the caller specify -charset and -docencoding separately just
opens the door to inconsistent settings. Can we remove the -charset
option? Or just provide an option to turn off the charset specification?

This RFE was inspired by this RFE:
4753019 : "No character encoding detected" warning from HTML validator
Comments
Superseded by JDK-8183582.
25-01-2018
CONVERTED DATA BugTraq+ Release Management Values COMMIT TO FIX: dragon
28-08-2004
EVALUATION For maximum compatibility: - Allow the options to work as they always have, except that if both are passed in with different values, throw an error (or warning). The question is: "Are setting the encoding and setting the META tag so closely related that they should always both be set with a single option?" If the answer is yes, then that presents a drawback with the previous choice (which requires both options to be used to get both operations). Deprecating an option is not desirable, as deprecation should be used only in the most extreme cases. Slightly less compatible is: - Allow either option to perform both operations. Throw an error if both options are supplied (even if they contain the same value). However, if we didn't need to worry so much about compatibility, it might make more sense to do this: - If -docencoding is specified, always insert the corresponding META tag. Remove -charset or make it a no-op. If we do this, a relevant question to ask is: - Do we need to control whether the META tag gets inserted or not? If we need to be able to suppress the meta tag, then add -nocharset option to do this. Even less compatible choices are to modify one or both options, such as: - Remove the -docencoding option (or make it a no-op) and have -charset perform both operations. (Or vice-versa) Note that a typical charset META tag looks like this: <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-5"> The tag must either be complete or not used -- it would make no sense to print it missing the charset attribute, for instance. ###@###.### 2003-08-20 Name: nl37777 Date: 12/24/2003 In additional discussions between ###@###.###, ###@###.###, and ###@###.### on 2003-08-21, we agreed on the following solution: - The META tag is always set. It is set as specified by -charset if that is given, or to the document's actual encoding if not. - If -charset is given and differs from the document's actual encoding, issue a warning. - If you want to allow the META tag to be omitted, go for "-charset none". - If -docencoding is not given, the document encoding is derived from -encoding, as in the past. The charset setting must use the MIME-preferred name from the IANA registry, while -docencoding and -encoding probably accept any encoding name that the J2RE knows about. You can map the -docencoding name to a valid charset name using java.nio.charset.Charset.forName(docencodingName).name() ======================================================================
28-08-2004