1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 1.2 +++ b/src/share/classes/com/sun/tools/doclets/formats/html/HelpWriter.java Wed Apr 27 01:34:52 2016 +0800 1.3 @@ -0,0 +1,334 @@ 1.4 +/* 1.5 + * Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved. 1.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 1.7 + * 1.8 + * This code is free software; you can redistribute it and/or modify it 1.9 + * under the terms of the GNU General Public License version 2 only, as 1.10 + * published by the Free Software Foundation. Oracle designates this 1.11 + * particular file as subject to the "Classpath" exception as provided 1.12 + * by Oracle in the LICENSE file that accompanied this code. 1.13 + * 1.14 + * This code is distributed in the hope that it will be useful, but WITHOUT 1.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 1.16 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 1.17 + * version 2 for more details (a copy is included in the LICENSE file that 1.18 + * accompanied this code). 1.19 + * 1.20 + * You should have received a copy of the GNU General Public License version 1.21 + * 2 along with this work; if not, write to the Free Software Foundation, 1.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 1.23 + * 1.24 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 1.25 + * or visit www.oracle.com if you need additional information or have any 1.26 + * questions. 1.27 + */ 1.28 + 1.29 +package com.sun.tools.doclets.formats.html; 1.30 + 1.31 +import java.io.*; 1.32 + 1.33 +import com.sun.tools.doclets.formats.html.markup.*; 1.34 +import com.sun.tools.doclets.internal.toolkit.*; 1.35 +import com.sun.tools.doclets.internal.toolkit.util.*; 1.36 + 1.37 +/** 1.38 + * Generate the Help File for the generated API documentation. The help file 1.39 + * contents are helpful for browsing the generated documentation. 1.40 + * 1.41 + * <p><b>This is NOT part of any supported API. 1.42 + * If you write code that depends on this, you do so at your own risk. 1.43 + * This code and its internal interfaces are subject to change or 1.44 + * deletion without notice.</b> 1.45 + * 1.46 + * @author Atul M Dambalkar 1.47 + */ 1.48 +public class HelpWriter extends HtmlDocletWriter { 1.49 + 1.50 + /** 1.51 + * Constructor to construct HelpWriter object. 1.52 + * @param filename File to be generated. 1.53 + */ 1.54 + public HelpWriter(ConfigurationImpl configuration, 1.55 + DocPath filename) throws IOException { 1.56 + super(configuration, filename); 1.57 + } 1.58 + 1.59 + /** 1.60 + * Construct the HelpWriter object and then use it to generate the help 1.61 + * file. The name of the generated file is "help-doc.html". The help file 1.62 + * will get generated if and only if "-helpfile" and "-nohelp" is not used 1.63 + * on the command line. 1.64 + * @throws DocletAbortException 1.65 + */ 1.66 + public static void generate(ConfigurationImpl configuration) { 1.67 + HelpWriter helpgen; 1.68 + DocPath filename = DocPath.empty; 1.69 + try { 1.70 + filename = DocPaths.HELP_DOC; 1.71 + helpgen = new HelpWriter(configuration, filename); 1.72 + helpgen.generateHelpFile(); 1.73 + helpgen.close(); 1.74 + } catch (IOException exc) { 1.75 + configuration.standardmessage.error( 1.76 + "doclet.exception_encountered", 1.77 + exc.toString(), filename); 1.78 + throw new DocletAbortException(exc); 1.79 + } 1.80 + } 1.81 + 1.82 + /** 1.83 + * Generate the help file contents. 1.84 + */ 1.85 + protected void generateHelpFile() throws IOException { 1.86 + String title = configuration.getText("doclet.Window_Help_title"); 1.87 + Content body = getBody(true, getWindowTitle(title)); 1.88 + addTop(body); 1.89 + addNavLinks(true, body); 1.90 + addHelpFileContents(body); 1.91 + addNavLinks(false, body); 1.92 + addBottom(body); 1.93 + printHtmlDocument(null, true, body); 1.94 + } 1.95 + 1.96 + /** 1.97 + * Add the help file contents from the resource file to the content tree. While adding the 1.98 + * help file contents it also keeps track of user options. If "-notree" 1.99 + * is used, then the "overview-tree.html" will not get added and hence 1.100 + * help information also will not get added. 1.101 + * 1.102 + * @param contentTree the content tree to which the help file contents will be added 1.103 + */ 1.104 + protected void addHelpFileContents(Content contentTree) { 1.105 + Content heading = HtmlTree.HEADING(HtmlConstants.TITLE_HEADING, false, HtmlStyle.title, 1.106 + getResource("doclet.Help_line_1")); 1.107 + Content div = HtmlTree.DIV(HtmlStyle.header, heading); 1.108 + Content line2 = HtmlTree.DIV(HtmlStyle.subTitle, 1.109 + getResource("doclet.Help_line_2")); 1.110 + div.addContent(line2); 1.111 + contentTree.addContent(div); 1.112 + HtmlTree ul = new HtmlTree(HtmlTag.UL); 1.113 + ul.addStyle(HtmlStyle.blockList); 1.114 + if (configuration.createoverview) { 1.115 + Content overviewHeading = HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING, 1.116 + getResource("doclet.Overview")); 1.117 + Content liOverview = HtmlTree.LI(HtmlStyle.blockList, overviewHeading); 1.118 + Content line3 = getResource("doclet.Help_line_3", 1.119 + getHyperLink(DocPaths.OVERVIEW_SUMMARY, 1.120 + configuration.getText("doclet.Overview"))); 1.121 + Content overviewPara = HtmlTree.P(line3); 1.122 + liOverview.addContent(overviewPara); 1.123 + ul.addContent(liOverview); 1.124 + } 1.125 + Content packageHead = HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING, 1.126 + getResource("doclet.Package")); 1.127 + Content liPackage = HtmlTree.LI(HtmlStyle.blockList, packageHead); 1.128 + Content line4 = getResource("doclet.Help_line_4"); 1.129 + Content packagePara = HtmlTree.P(line4); 1.130 + liPackage.addContent(packagePara); 1.131 + HtmlTree ulPackage = new HtmlTree(HtmlTag.UL); 1.132 + ulPackage.addContent(HtmlTree.LI( 1.133 + getResource("doclet.Interfaces_Italic"))); 1.134 + ulPackage.addContent(HtmlTree.LI( 1.135 + getResource("doclet.Classes"))); 1.136 + ulPackage.addContent(HtmlTree.LI( 1.137 + getResource("doclet.Enums"))); 1.138 + ulPackage.addContent(HtmlTree.LI( 1.139 + getResource("doclet.Exceptions"))); 1.140 + ulPackage.addContent(HtmlTree.LI( 1.141 + getResource("doclet.Errors"))); 1.142 + ulPackage.addContent(HtmlTree.LI( 1.143 + getResource("doclet.AnnotationTypes"))); 1.144 + liPackage.addContent(ulPackage); 1.145 + ul.addContent(liPackage); 1.146 + Content classHead = HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING, 1.147 + getResource("doclet.Help_line_5")); 1.148 + Content liClass = HtmlTree.LI(HtmlStyle.blockList, classHead); 1.149 + Content line6 = getResource("doclet.Help_line_6"); 1.150 + Content classPara = HtmlTree.P(line6); 1.151 + liClass.addContent(classPara); 1.152 + HtmlTree ul1 = new HtmlTree(HtmlTag.UL); 1.153 + ul1.addContent(HtmlTree.LI( 1.154 + getResource("doclet.Help_line_7"))); 1.155 + ul1.addContent(HtmlTree.LI( 1.156 + getResource("doclet.Help_line_8"))); 1.157 + ul1.addContent(HtmlTree.LI( 1.158 + getResource("doclet.Help_line_9"))); 1.159 + ul1.addContent(HtmlTree.LI( 1.160 + getResource("doclet.Help_line_10"))); 1.161 + ul1.addContent(HtmlTree.LI( 1.162 + getResource("doclet.Help_line_11"))); 1.163 + ul1.addContent(HtmlTree.LI( 1.164 + getResource("doclet.Help_line_12"))); 1.165 + liClass.addContent(ul1); 1.166 + HtmlTree ul2 = new HtmlTree(HtmlTag.UL); 1.167 + ul2.addContent(HtmlTree.LI( 1.168 + getResource("doclet.Nested_Class_Summary"))); 1.169 + ul2.addContent(HtmlTree.LI( 1.170 + getResource("doclet.Field_Summary"))); 1.171 + ul2.addContent(HtmlTree.LI( 1.172 + getResource("doclet.Constructor_Summary"))); 1.173 + ul2.addContent(HtmlTree.LI( 1.174 + getResource("doclet.Method_Summary"))); 1.175 + liClass.addContent(ul2); 1.176 + HtmlTree ul3 = new HtmlTree(HtmlTag.UL); 1.177 + ul3.addContent(HtmlTree.LI( 1.178 + getResource("doclet.Field_Detail"))); 1.179 + ul3.addContent(HtmlTree.LI( 1.180 + getResource("doclet.Constructor_Detail"))); 1.181 + ul3.addContent(HtmlTree.LI( 1.182 + getResource("doclet.Method_Detail"))); 1.183 + liClass.addContent(ul3); 1.184 + Content line13 = getResource("doclet.Help_line_13"); 1.185 + Content para = HtmlTree.P(line13); 1.186 + liClass.addContent(para); 1.187 + ul.addContent(liClass); 1.188 + //Annotation Types 1.189 + Content aHead = HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING, 1.190 + getResource("doclet.AnnotationType")); 1.191 + Content liAnnotation = HtmlTree.LI(HtmlStyle.blockList, aHead); 1.192 + Content aline1 = getResource("doclet.Help_annotation_type_line_1"); 1.193 + Content aPara = HtmlTree.P(aline1); 1.194 + liAnnotation.addContent(aPara); 1.195 + HtmlTree aul = new HtmlTree(HtmlTag.UL); 1.196 + aul.addContent(HtmlTree.LI( 1.197 + getResource("doclet.Help_annotation_type_line_2"))); 1.198 + aul.addContent(HtmlTree.LI( 1.199 + getResource("doclet.Help_annotation_type_line_3"))); 1.200 + aul.addContent(HtmlTree.LI( 1.201 + getResource("doclet.Annotation_Type_Required_Member_Summary"))); 1.202 + aul.addContent(HtmlTree.LI( 1.203 + getResource("doclet.Annotation_Type_Optional_Member_Summary"))); 1.204 + aul.addContent(HtmlTree.LI( 1.205 + getResource("doclet.Annotation_Type_Member_Detail"))); 1.206 + liAnnotation.addContent(aul); 1.207 + ul.addContent(liAnnotation); 1.208 + //Enums 1.209 + Content enumHead = HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING, 1.210 + getResource("doclet.Enum")); 1.211 + Content liEnum = HtmlTree.LI(HtmlStyle.blockList, enumHead); 1.212 + Content eline1 = getResource("doclet.Help_enum_line_1"); 1.213 + Content enumPara = HtmlTree.P(eline1); 1.214 + liEnum.addContent(enumPara); 1.215 + HtmlTree eul = new HtmlTree(HtmlTag.UL); 1.216 + eul.addContent(HtmlTree.LI( 1.217 + getResource("doclet.Help_enum_line_2"))); 1.218 + eul.addContent(HtmlTree.LI( 1.219 + getResource("doclet.Help_enum_line_3"))); 1.220 + eul.addContent(HtmlTree.LI( 1.221 + getResource("doclet.Enum_Constant_Summary"))); 1.222 + eul.addContent(HtmlTree.LI( 1.223 + getResource("doclet.Enum_Constant_Detail"))); 1.224 + liEnum.addContent(eul); 1.225 + ul.addContent(liEnum); 1.226 + if (configuration.classuse) { 1.227 + Content useHead = HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING, 1.228 + getResource("doclet.Help_line_14")); 1.229 + Content liUse = HtmlTree.LI(HtmlStyle.blockList, useHead); 1.230 + Content line15 = getResource("doclet.Help_line_15"); 1.231 + Content usePara = HtmlTree.P(line15); 1.232 + liUse.addContent(usePara); 1.233 + ul.addContent(liUse); 1.234 + } 1.235 + if (configuration.createtree) { 1.236 + Content treeHead = HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING, 1.237 + getResource("doclet.Help_line_16")); 1.238 + Content liTree = HtmlTree.LI(HtmlStyle.blockList, treeHead); 1.239 + Content line17 = getResource("doclet.Help_line_17_with_tree_link", 1.240 + getHyperLink(DocPaths.OVERVIEW_TREE, 1.241 + configuration.getText("doclet.Class_Hierarchy")), 1.242 + HtmlTree.CODE(new StringContent("java.lang.Object"))); 1.243 + Content treePara = HtmlTree.P(line17); 1.244 + liTree.addContent(treePara); 1.245 + HtmlTree tul = new HtmlTree(HtmlTag.UL); 1.246 + tul.addContent(HtmlTree.LI( 1.247 + getResource("doclet.Help_line_18"))); 1.248 + tul.addContent(HtmlTree.LI( 1.249 + getResource("doclet.Help_line_19"))); 1.250 + liTree.addContent(tul); 1.251 + ul.addContent(liTree); 1.252 + } 1.253 + if (!(configuration.nodeprecatedlist || 1.254 + configuration.nodeprecated)) { 1.255 + Content dHead = HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING, 1.256 + getResource("doclet.Deprecated_API")); 1.257 + Content liDeprecated = HtmlTree.LI(HtmlStyle.blockList, dHead); 1.258 + Content line20 = getResource("doclet.Help_line_20_with_deprecated_api_link", 1.259 + getHyperLink(DocPaths.DEPRECATED_LIST, 1.260 + configuration.getText("doclet.Deprecated_API"))); 1.261 + Content dPara = HtmlTree.P(line20); 1.262 + liDeprecated.addContent(dPara); 1.263 + ul.addContent(liDeprecated); 1.264 + } 1.265 + if (configuration.createindex) { 1.266 + Content indexlink; 1.267 + if (configuration.splitindex) { 1.268 + indexlink = getHyperLink(DocPaths.INDEX_FILES.resolve(DocPaths.indexN(1)), 1.269 + configuration.getText("doclet.Index")); 1.270 + } else { 1.271 + indexlink = getHyperLink(DocPaths.INDEX_ALL, 1.272 + configuration.getText("doclet.Index")); 1.273 + } 1.274 + Content indexHead = HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING, 1.275 + getResource("doclet.Help_line_21")); 1.276 + Content liIndex = HtmlTree.LI(HtmlStyle.blockList, indexHead); 1.277 + Content line22 = getResource("doclet.Help_line_22", indexlink); 1.278 + Content indexPara = HtmlTree.P(line22); 1.279 + liIndex.addContent(indexPara); 1.280 + ul.addContent(liIndex); 1.281 + } 1.282 + Content prevHead = HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING, 1.283 + getResource("doclet.Help_line_23")); 1.284 + Content liPrev = HtmlTree.LI(HtmlStyle.blockList, prevHead); 1.285 + Content line24 = getResource("doclet.Help_line_24"); 1.286 + Content prevPara = HtmlTree.P(line24); 1.287 + liPrev.addContent(prevPara); 1.288 + ul.addContent(liPrev); 1.289 + Content frameHead = HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING, 1.290 + getResource("doclet.Help_line_25")); 1.291 + Content liFrame = HtmlTree.LI(HtmlStyle.blockList, frameHead); 1.292 + Content line26 = getResource("doclet.Help_line_26"); 1.293 + Content framePara = HtmlTree.P(line26); 1.294 + liFrame.addContent(framePara); 1.295 + ul.addContent(liFrame); 1.296 + Content allclassesHead = HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING, 1.297 + getResource("doclet.All_Classes")); 1.298 + Content liAllClasses = HtmlTree.LI(HtmlStyle.blockList, allclassesHead); 1.299 + Content line27 = getResource("doclet.Help_line_27", 1.300 + getHyperLink(DocPaths.ALLCLASSES_NOFRAME, 1.301 + configuration.getText("doclet.All_Classes"))); 1.302 + Content allclassesPara = HtmlTree.P(line27); 1.303 + liAllClasses.addContent(allclassesPara); 1.304 + ul.addContent(liAllClasses); 1.305 + Content sHead = HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING, 1.306 + getResource("doclet.Serialized_Form")); 1.307 + Content liSerial = HtmlTree.LI(HtmlStyle.blockList, sHead); 1.308 + Content line28 = getResource("doclet.Help_line_28"); 1.309 + Content serialPara = HtmlTree.P(line28); 1.310 + liSerial.addContent(serialPara); 1.311 + ul.addContent(liSerial); 1.312 + Content constHead = HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING, 1.313 + getResource("doclet.Constants_Summary")); 1.314 + Content liConst = HtmlTree.LI(HtmlStyle.blockList, constHead); 1.315 + Content line29 = getResource("doclet.Help_line_29", 1.316 + getHyperLink(DocPaths.CONSTANT_VALUES, 1.317 + configuration.getText("doclet.Constants_Summary"))); 1.318 + Content constPara = HtmlTree.P(line29); 1.319 + liConst.addContent(constPara); 1.320 + ul.addContent(liConst); 1.321 + Content divContent = HtmlTree.DIV(HtmlStyle.contentContainer, ul); 1.322 + Content line30 = HtmlTree.SPAN(HtmlStyle.emphasizedPhrase, getResource("doclet.Help_line_30")); 1.323 + divContent.addContent(line30); 1.324 + contentTree.addContent(divContent); 1.325 + } 1.326 + 1.327 + /** 1.328 + * Get the help label. 1.329 + * 1.330 + * @return a content tree for the help label 1.331 + */ 1.332 + @Override 1.333 + protected Content getNavLinkHelp() { 1.334 + Content li = HtmlTree.LI(HtmlStyle.navBarCell1Rev, helpLabel); 1.335 + return li; 1.336 + } 1.337 +}