1/* 2 * Copyright (c) 1998, 2016, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26package jdk.javadoc.internal.doclets.formats.html; 27 28import jdk.javadoc.internal.doclets.formats.html.markup.HtmlConstants; 29import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle; 30import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTag; 31import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree; 32import jdk.javadoc.internal.doclets.formats.html.markup.StringContent; 33import jdk.javadoc.internal.doclets.toolkit.Content; 34import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException; 35import jdk.javadoc.internal.doclets.toolkit.util.DocPath; 36import jdk.javadoc.internal.doclets.toolkit.util.DocPaths; 37 38 39/** 40 * Generate the Help File for the generated API documentation. The help file 41 * contents are helpful for browsing the generated documentation. 42 * 43 * <p><b>This is NOT part of any supported API. 44 * If you write code that depends on this, you do so at your own risk. 45 * This code and its internal interfaces are subject to change or 46 * deletion without notice.</b> 47 * 48 * @author Atul M Dambalkar 49 */ 50public class HelpWriter extends HtmlDocletWriter { 51 52 HtmlTree mainTree = HtmlTree.MAIN(); 53 54 /** 55 * Constructor to construct HelpWriter object. 56 * @param filename File to be generated. 57 */ 58 public HelpWriter(ConfigurationImpl configuration, 59 DocPath filename) { 60 super(configuration, filename); 61 } 62 63 /** 64 * Construct the HelpWriter object and then use it to generate the help 65 * file. The name of the generated file is "help-doc.html". The help file 66 * will get generated if and only if "-helpfile" and "-nohelp" is not used 67 * on the command line. 68 * 69 * @throws DocFileIOException if there is a problem while generating the documentation 70 */ 71 public static void generate(ConfigurationImpl configuration) throws DocFileIOException { 72 DocPath filename = DocPaths.HELP_DOC; 73 HelpWriter helpgen = new HelpWriter(configuration, filename); 74 helpgen.generateHelpFile(); 75 } 76 77 /** 78 * Generate the help file contents. 79 * 80 * @throws DocFileIOException if there is a problem while generating the documentation 81 */ 82 protected void generateHelpFile() throws DocFileIOException { 83 String title = configuration.getText("doclet.Window_Help_title"); 84 HtmlTree body = getBody(true, getWindowTitle(title)); 85 HtmlTree htmlTree = (configuration.allowTag(HtmlTag.HEADER)) 86 ? HtmlTree.HEADER() 87 : body; 88 addTop(htmlTree); 89 addNavLinks(true, htmlTree); 90 if (configuration.allowTag(HtmlTag.HEADER)) { 91 body.addContent(htmlTree); 92 } 93 addHelpFileContents(body); 94 if (configuration.allowTag(HtmlTag.FOOTER)) { 95 htmlTree = HtmlTree.FOOTER(); 96 } 97 addNavLinks(false, htmlTree); 98 addBottom(htmlTree); 99 if (configuration.allowTag(HtmlTag.FOOTER)) { 100 body.addContent(htmlTree); 101 } 102 printHtmlDocument(null, true, body); 103 } 104 105 /** 106 * Add the help file contents from the resource file to the content tree. While adding the 107 * help file contents it also keeps track of user options. If "-notree" 108 * is used, then the "overview-tree.html" will not get added and hence 109 * help information also will not get added. 110 * 111 * @param contentTree the content tree to which the help file contents will be added 112 */ 113 protected void addHelpFileContents(Content contentTree) { 114 Content heading = HtmlTree.HEADING(HtmlConstants.TITLE_HEADING, false, HtmlStyle.title, 115 contents.getContent("doclet.Help_line_1")); 116 Content div = HtmlTree.DIV(HtmlStyle.header, heading); 117 Content line2 = HtmlTree.DIV(HtmlStyle.subTitle, 118 contents.getContent("doclet.Help_line_2")); 119 div.addContent(line2); 120 if (configuration.allowTag(HtmlTag.MAIN)) { 121 mainTree.addContent(div); 122 } else { 123 contentTree.addContent(div); 124 } 125 HtmlTree htmlTree; 126 HtmlTree ul = new HtmlTree(HtmlTag.UL); 127 ul.addStyle(HtmlStyle.blockList); 128 if (configuration.createoverview) { 129 Content overviewHeading = HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING, 130 contents.overviewLabel); 131 htmlTree = (configuration.allowTag(HtmlTag.SECTION)) 132 ? HtmlTree.SECTION(overviewHeading) 133 : HtmlTree.LI(HtmlStyle.blockList, overviewHeading); 134 Content line3 = contents.getContent("doclet.Help_line_3", 135 getHyperLink(DocPaths.overviewSummary(configuration.frames), 136 configuration.getText("doclet.Overview"))); 137 Content overviewPara = HtmlTree.P(line3); 138 htmlTree.addContent(overviewPara); 139 if (configuration.allowTag(HtmlTag.SECTION)) { 140 ul.addContent(HtmlTree.LI(HtmlStyle.blockList, htmlTree)); 141 } else { 142 ul.addContent(htmlTree); 143 } 144 } 145 Content packageHead = HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING, 146 contents.packageLabel); 147 htmlTree = (configuration.allowTag(HtmlTag.SECTION)) 148 ? HtmlTree.SECTION(packageHead) 149 : HtmlTree.LI(HtmlStyle.blockList, packageHead); 150 Content line4 = contents.getContent("doclet.Help_line_4"); 151 Content packagePara = HtmlTree.P(line4); 152 htmlTree.addContent(packagePara); 153 HtmlTree ulPackage = new HtmlTree(HtmlTag.UL); 154 ulPackage.addContent(HtmlTree.LI( 155 contents.interfacesItalic)); 156 ulPackage.addContent(HtmlTree.LI( 157 contents.classes)); 158 ulPackage.addContent(HtmlTree.LI( 159 contents.enums)); 160 ulPackage.addContent(HtmlTree.LI( 161 contents.exceptions)); 162 ulPackage.addContent(HtmlTree.LI( 163 contents.errors)); 164 ulPackage.addContent(HtmlTree.LI( 165 contents.annotationTypes)); 166 htmlTree.addContent(ulPackage); 167 if (configuration.allowTag(HtmlTag.SECTION)) { 168 ul.addContent(HtmlTree.LI(HtmlStyle.blockList, htmlTree)); 169 } else { 170 ul.addContent(htmlTree); 171 } 172 Content classHead = HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING, 173 contents.getContent("doclet.Help_line_5")); 174 htmlTree = (configuration.allowTag(HtmlTag.SECTION)) 175 ? HtmlTree.SECTION(classHead) 176 : HtmlTree.LI(HtmlStyle.blockList, classHead); 177 Content line6 = contents.getContent("doclet.Help_line_6"); 178 Content classPara = HtmlTree.P(line6); 179 htmlTree.addContent(classPara); 180 HtmlTree ul1 = new HtmlTree(HtmlTag.UL); 181 ul1.addContent(HtmlTree.LI( 182 contents.getContent("doclet.Help_line_7"))); 183 ul1.addContent(HtmlTree.LI( 184 contents.getContent("doclet.Help_line_8"))); 185 ul1.addContent(HtmlTree.LI( 186 contents.getContent("doclet.Help_line_9"))); 187 ul1.addContent(HtmlTree.LI( 188 contents.getContent("doclet.Help_line_10"))); 189 ul1.addContent(HtmlTree.LI( 190 contents.getContent("doclet.Help_line_11"))); 191 ul1.addContent(HtmlTree.LI( 192 contents.getContent("doclet.Help_line_12"))); 193 htmlTree.addContent(ul1); 194 HtmlTree ul2 = new HtmlTree(HtmlTag.UL); 195 ul2.addContent(HtmlTree.LI(contents.nestedClassSummary)); 196 ul2.addContent(HtmlTree.LI(contents.fieldSummaryLabel)); 197 ul2.addContent(HtmlTree.LI(contents.constructorSummaryLabel)); 198 ul2.addContent(HtmlTree.LI(contents.methodSummary)); 199 htmlTree.addContent(ul2); 200 HtmlTree ul3 = new HtmlTree(HtmlTag.UL); 201 ul3.addContent(HtmlTree.LI(contents.fieldDetailsLabel)); 202 ul3.addContent(HtmlTree.LI(contents.constructorDetailsLabel)); 203 ul3.addContent(HtmlTree.LI(contents.methodDetailLabel)); 204 htmlTree.addContent(ul3); 205 Content line13 = contents.getContent("doclet.Help_line_13"); 206 Content para = HtmlTree.P(line13); 207 htmlTree.addContent(para); 208 if (configuration.allowTag(HtmlTag.SECTION)) { 209 ul.addContent(HtmlTree.LI(HtmlStyle.blockList, htmlTree)); 210 } else { 211 ul.addContent(htmlTree); 212 } 213 //Annotation Types 214 Content aHead = HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING, 215 contents.annotationType); 216 htmlTree = (configuration.allowTag(HtmlTag.SECTION)) 217 ? HtmlTree.SECTION(aHead) 218 : HtmlTree.LI(HtmlStyle.blockList, aHead); 219 Content aline1 = contents.getContent("doclet.Help_annotation_type_line_1"); 220 Content aPara = HtmlTree.P(aline1); 221 htmlTree.addContent(aPara); 222 HtmlTree aul = new HtmlTree(HtmlTag.UL); 223 aul.addContent(HtmlTree.LI( 224 contents.getContent("doclet.Help_annotation_type_line_2"))); 225 aul.addContent(HtmlTree.LI( 226 contents.getContent("doclet.Help_annotation_type_line_3"))); 227 aul.addContent(HtmlTree.LI( 228 contents.annotateTypeRequiredMemberSummaryLabel)); 229 aul.addContent(HtmlTree.LI( 230 contents.annotateTypeOptionalMemberSummaryLabel)); 231 aul.addContent(HtmlTree.LI( 232 contents.annotationTypeMemberDetail)); 233 htmlTree.addContent(aul); 234 if (configuration.allowTag(HtmlTag.SECTION)) { 235 ul.addContent(HtmlTree.LI(HtmlStyle.blockList, htmlTree)); 236 } else { 237 ul.addContent(htmlTree); 238 } 239 //Enums 240 Content enumHead = HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING, 241 contents.enum_); 242 htmlTree = (configuration.allowTag(HtmlTag.SECTION)) 243 ? HtmlTree.SECTION(enumHead) 244 : HtmlTree.LI(HtmlStyle.blockList, enumHead); 245 Content eline1 = contents.getContent("doclet.Help_enum_line_1"); 246 Content enumPara = HtmlTree.P(eline1); 247 htmlTree.addContent(enumPara); 248 HtmlTree eul = new HtmlTree(HtmlTag.UL); 249 eul.addContent(HtmlTree.LI( 250 contents.getContent("doclet.Help_enum_line_2"))); 251 eul.addContent(HtmlTree.LI( 252 contents.getContent("doclet.Help_enum_line_3"))); 253 eul.addContent(HtmlTree.LI( 254 contents.enumConstantSummary)); 255 eul.addContent(HtmlTree.LI( 256 contents.enumConstantDetailLabel)); 257 htmlTree.addContent(eul); 258 if (configuration.allowTag(HtmlTag.SECTION)) { 259 ul.addContent(HtmlTree.LI(HtmlStyle.blockList, htmlTree)); 260 } else { 261 ul.addContent(htmlTree); 262 } 263 if (configuration.classuse) { 264 Content useHead = HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING, 265 contents.getContent("doclet.Help_line_14")); 266 htmlTree = (configuration.allowTag(HtmlTag.SECTION)) 267 ? HtmlTree.SECTION(useHead) 268 : HtmlTree.LI(HtmlStyle.blockList, useHead); 269 Content line15 = contents.getContent("doclet.Help_line_15"); 270 Content usePara = HtmlTree.P(line15); 271 htmlTree.addContent(usePara); 272 if (configuration.allowTag(HtmlTag.SECTION)) { 273 ul.addContent(HtmlTree.LI(HtmlStyle.blockList, htmlTree)); 274 } else { 275 ul.addContent(htmlTree); 276 } 277 } 278 if (configuration.createtree) { 279 Content treeHead = HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING, 280 contents.getContent("doclet.Help_line_16")); 281 htmlTree = (configuration.allowTag(HtmlTag.SECTION)) 282 ? HtmlTree.SECTION(treeHead) 283 : HtmlTree.LI(HtmlStyle.blockList, treeHead); 284 Content line17 = contents.getContent("doclet.Help_line_17_with_tree_link", 285 getHyperLink(DocPaths.OVERVIEW_TREE, 286 configuration.getText("doclet.Class_Hierarchy")), 287 HtmlTree.CODE(new StringContent("java.lang.Object"))); 288 Content treePara = HtmlTree.P(line17); 289 htmlTree.addContent(treePara); 290 HtmlTree tul = new HtmlTree(HtmlTag.UL); 291 tul.addContent(HtmlTree.LI( 292 contents.getContent("doclet.Help_line_18"))); 293 tul.addContent(HtmlTree.LI( 294 contents.getContent("doclet.Help_line_19"))); 295 htmlTree.addContent(tul); 296 if (configuration.allowTag(HtmlTag.SECTION)) { 297 ul.addContent(HtmlTree.LI(HtmlStyle.blockList, htmlTree)); 298 } else { 299 ul.addContent(htmlTree); 300 } 301 } 302 if (!(configuration.nodeprecatedlist || 303 configuration.nodeprecated)) { 304 Content dHead = HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING, 305 contents.deprecatedAPI); 306 htmlTree = (configuration.allowTag(HtmlTag.SECTION)) 307 ? HtmlTree.SECTION(dHead) 308 : HtmlTree.LI(HtmlStyle.blockList, dHead); 309 Content line20 = contents.getContent("doclet.Help_line_20_with_deprecated_api_link", 310 getHyperLink(DocPaths.DEPRECATED_LIST, 311 configuration.getText("doclet.Deprecated_API"))); 312 Content dPara = HtmlTree.P(line20); 313 htmlTree.addContent(dPara); 314 if (configuration.allowTag(HtmlTag.SECTION)) { 315 ul.addContent(HtmlTree.LI(HtmlStyle.blockList, htmlTree)); 316 } else { 317 ul.addContent(htmlTree); 318 } 319 } 320 if (configuration.createindex) { 321 Content indexlink; 322 if (configuration.splitindex) { 323 indexlink = getHyperLink(DocPaths.INDEX_FILES.resolve(DocPaths.indexN(1)), 324 configuration.getText("doclet.Index")); 325 } else { 326 indexlink = getHyperLink(DocPaths.INDEX_ALL, 327 configuration.getText("doclet.Index")); 328 } 329 Content indexHead = HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING, 330 contents.getContent("doclet.Help_line_21")); 331 htmlTree = (configuration.allowTag(HtmlTag.SECTION)) 332 ? HtmlTree.SECTION(indexHead) 333 : HtmlTree.LI(HtmlStyle.blockList, indexHead); 334 Content line22 = contents.getContent("doclet.Help_line_22", indexlink); 335 Content indexPara = HtmlTree.P(line22); 336 htmlTree.addContent(indexPara); 337 if (configuration.allowTag(HtmlTag.SECTION)) { 338 ul.addContent(HtmlTree.LI(HtmlStyle.blockList, htmlTree)); 339 } else { 340 ul.addContent(htmlTree); 341 } 342 } 343 Content prevHead = HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING, 344 contents.getContent("doclet.Help_line_23")); 345 htmlTree = (configuration.allowTag(HtmlTag.SECTION)) 346 ? HtmlTree.SECTION(prevHead) 347 : HtmlTree.LI(HtmlStyle.blockList, prevHead); 348 Content line24 = contents.getContent("doclet.Help_line_24"); 349 Content prevPara = HtmlTree.P(line24); 350 htmlTree.addContent(prevPara); 351 if (configuration.allowTag(HtmlTag.SECTION)) { 352 ul.addContent(HtmlTree.LI(HtmlStyle.blockList, htmlTree)); 353 } else { 354 ul.addContent(htmlTree); 355 } 356 357 if (configuration.frames) { 358 Content frameHead = HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING, 359 contents.getContent("doclet.Help_line_25")); 360 htmlTree = (configuration.allowTag(HtmlTag.SECTION)) 361 ? HtmlTree.SECTION(frameHead) 362 : HtmlTree.LI(HtmlStyle.blockList, frameHead); 363 Content line26 = contents.getContent("doclet.Help_line_26"); 364 Content framePara = HtmlTree.P(line26); 365 htmlTree.addContent(framePara); 366 } 367 368 if (configuration.allowTag(HtmlTag.SECTION)) { 369 ul.addContent(HtmlTree.LI(HtmlStyle.blockList, htmlTree)); 370 } else { 371 ul.addContent(htmlTree); 372 } 373 374 Content allclassesHead = HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING, 375 contents.allClassesLabel); 376 htmlTree = (configuration.allowTag(HtmlTag.SECTION)) 377 ? HtmlTree.SECTION(allclassesHead) 378 : HtmlTree.LI(HtmlStyle.blockList, allclassesHead); 379 Content line27 = contents.getContent("doclet.Help_line_27", 380 getHyperLink(DocPaths.AllClasses(configuration.frames), 381 resources.getText("doclet.All_Classes"))); 382 Content allclassesPara = HtmlTree.P(line27); 383 htmlTree.addContent(allclassesPara); 384 if (configuration.allowTag(HtmlTag.SECTION)) { 385 ul.addContent(HtmlTree.LI(HtmlStyle.blockList, htmlTree)); 386 } else { 387 ul.addContent(htmlTree); 388 } 389 Content sHead = HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING, 390 contents.serializedForm); 391 htmlTree = (configuration.allowTag(HtmlTag.SECTION)) 392 ? HtmlTree.SECTION(sHead) 393 : HtmlTree.LI(HtmlStyle.blockList, sHead); 394 Content line28 = contents.getContent("doclet.Help_line_28"); 395 Content serialPara = HtmlTree.P(line28); 396 htmlTree.addContent(serialPara); 397 if (configuration.allowTag(HtmlTag.SECTION)) { 398 ul.addContent(HtmlTree.LI(HtmlStyle.blockList, htmlTree)); 399 } else { 400 ul.addContent(htmlTree); 401 } 402 Content constHead = HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING, 403 contents.constantsSummaryTitle); 404 htmlTree = (configuration.allowTag(HtmlTag.SECTION)) 405 ? HtmlTree.SECTION(constHead) 406 : HtmlTree.LI(HtmlStyle.blockList, constHead); 407 Content line29 = contents.getContent("doclet.Help_line_29", 408 getHyperLink(DocPaths.CONSTANT_VALUES, 409 resources.getText("doclet.Constants_Summary"))); 410 Content constPara = HtmlTree.P(line29); 411 htmlTree.addContent(constPara); 412 if (configuration.allowTag(HtmlTag.SECTION)) { 413 ul.addContent(HtmlTree.LI(HtmlStyle.blockList, htmlTree)); 414 } else { 415 ul.addContent(htmlTree); 416 } 417 Content divContent = HtmlTree.DIV(HtmlStyle.contentContainer, ul); 418 Content line30 = HtmlTree.SPAN(HtmlStyle.emphasizedPhrase, contents.getContent("doclet.Help_line_30")); 419 divContent.addContent(line30); 420 if (configuration.allowTag(HtmlTag.MAIN)) { 421 mainTree.addContent(divContent); 422 contentTree.addContent(mainTree); 423 } else { 424 contentTree.addContent(divContent); 425 } 426 } 427 428 /** 429 * Get the help label. 430 * 431 * @return a content tree for the help label 432 */ 433 @Override 434 protected Content getNavLinkHelp() { 435 Content li = HtmlTree.LI(HtmlStyle.navBarCell1Rev, contents.helpLabel); 436 return li; 437 } 438} 439