|
1 /* |
|
2 * Copyright (c) 1998, 2013, 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 |
|
26 package com.sun.tools.doclets.formats.html; |
|
27 |
|
28 import java.io.*; |
|
29 |
|
30 import com.sun.tools.doclets.formats.html.markup.*; |
|
31 import com.sun.tools.doclets.internal.toolkit.*; |
|
32 import com.sun.tools.doclets.internal.toolkit.util.*; |
|
33 |
|
34 /** |
|
35 * Generate the Help File for the generated API documentation. The help file |
|
36 * contents are helpful for browsing the generated documentation. |
|
37 * |
|
38 * <p><b>This is NOT part of any supported API. |
|
39 * If you write code that depends on this, you do so at your own risk. |
|
40 * This code and its internal interfaces are subject to change or |
|
41 * deletion without notice.</b> |
|
42 * |
|
43 * @author Atul M Dambalkar |
|
44 */ |
|
45 public class HelpWriter extends HtmlDocletWriter { |
|
46 |
|
47 /** |
|
48 * Constructor to construct HelpWriter object. |
|
49 * @param filename File to be generated. |
|
50 */ |
|
51 public HelpWriter(ConfigurationImpl configuration, |
|
52 DocPath filename) throws IOException { |
|
53 super(configuration, filename); |
|
54 } |
|
55 |
|
56 /** |
|
57 * Construct the HelpWriter object and then use it to generate the help |
|
58 * file. The name of the generated file is "help-doc.html". The help file |
|
59 * will get generated if and only if "-helpfile" and "-nohelp" is not used |
|
60 * on the command line. |
|
61 * @throws DocletAbortException |
|
62 */ |
|
63 public static void generate(ConfigurationImpl configuration) { |
|
64 HelpWriter helpgen; |
|
65 DocPath filename = DocPath.empty; |
|
66 try { |
|
67 filename = DocPaths.HELP_DOC; |
|
68 helpgen = new HelpWriter(configuration, filename); |
|
69 helpgen.generateHelpFile(); |
|
70 helpgen.close(); |
|
71 } catch (IOException exc) { |
|
72 configuration.standardmessage.error( |
|
73 "doclet.exception_encountered", |
|
74 exc.toString(), filename); |
|
75 throw new DocletAbortException(exc); |
|
76 } |
|
77 } |
|
78 |
|
79 /** |
|
80 * Generate the help file contents. |
|
81 */ |
|
82 protected void generateHelpFile() throws IOException { |
|
83 String title = configuration.getText("doclet.Window_Help_title"); |
|
84 Content body = getBody(true, getWindowTitle(title)); |
|
85 addTop(body); |
|
86 addNavLinks(true, body); |
|
87 addHelpFileContents(body); |
|
88 addNavLinks(false, body); |
|
89 addBottom(body); |
|
90 printHtmlDocument(null, true, body); |
|
91 } |
|
92 |
|
93 /** |
|
94 * Add the help file contents from the resource file to the content tree. While adding the |
|
95 * help file contents it also keeps track of user options. If "-notree" |
|
96 * is used, then the "overview-tree.html" will not get added and hence |
|
97 * help information also will not get added. |
|
98 * |
|
99 * @param contentTree the content tree to which the help file contents will be added |
|
100 */ |
|
101 protected void addHelpFileContents(Content contentTree) { |
|
102 Content heading = HtmlTree.HEADING(HtmlConstants.TITLE_HEADING, false, HtmlStyle.title, |
|
103 getResource("doclet.Help_line_1")); |
|
104 Content div = HtmlTree.DIV(HtmlStyle.header, heading); |
|
105 Content line2 = HtmlTree.DIV(HtmlStyle.subTitle, |
|
106 getResource("doclet.Help_line_2")); |
|
107 div.addContent(line2); |
|
108 contentTree.addContent(div); |
|
109 HtmlTree ul = new HtmlTree(HtmlTag.UL); |
|
110 ul.addStyle(HtmlStyle.blockList); |
|
111 if (configuration.createoverview) { |
|
112 Content overviewHeading = HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING, |
|
113 getResource("doclet.Overview")); |
|
114 Content liOverview = HtmlTree.LI(HtmlStyle.blockList, overviewHeading); |
|
115 Content line3 = getResource("doclet.Help_line_3", |
|
116 getHyperLink(DocPaths.OVERVIEW_SUMMARY, |
|
117 configuration.getText("doclet.Overview"))); |
|
118 Content overviewPara = HtmlTree.P(line3); |
|
119 liOverview.addContent(overviewPara); |
|
120 ul.addContent(liOverview); |
|
121 } |
|
122 Content packageHead = HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING, |
|
123 getResource("doclet.Package")); |
|
124 Content liPackage = HtmlTree.LI(HtmlStyle.blockList, packageHead); |
|
125 Content line4 = getResource("doclet.Help_line_4"); |
|
126 Content packagePara = HtmlTree.P(line4); |
|
127 liPackage.addContent(packagePara); |
|
128 HtmlTree ulPackage = new HtmlTree(HtmlTag.UL); |
|
129 ulPackage.addContent(HtmlTree.LI( |
|
130 getResource("doclet.Interfaces_Italic"))); |
|
131 ulPackage.addContent(HtmlTree.LI( |
|
132 getResource("doclet.Classes"))); |
|
133 ulPackage.addContent(HtmlTree.LI( |
|
134 getResource("doclet.Enums"))); |
|
135 ulPackage.addContent(HtmlTree.LI( |
|
136 getResource("doclet.Exceptions"))); |
|
137 ulPackage.addContent(HtmlTree.LI( |
|
138 getResource("doclet.Errors"))); |
|
139 ulPackage.addContent(HtmlTree.LI( |
|
140 getResource("doclet.AnnotationTypes"))); |
|
141 liPackage.addContent(ulPackage); |
|
142 ul.addContent(liPackage); |
|
143 Content classHead = HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING, |
|
144 getResource("doclet.Help_line_5")); |
|
145 Content liClass = HtmlTree.LI(HtmlStyle.blockList, classHead); |
|
146 Content line6 = getResource("doclet.Help_line_6"); |
|
147 Content classPara = HtmlTree.P(line6); |
|
148 liClass.addContent(classPara); |
|
149 HtmlTree ul1 = new HtmlTree(HtmlTag.UL); |
|
150 ul1.addContent(HtmlTree.LI( |
|
151 getResource("doclet.Help_line_7"))); |
|
152 ul1.addContent(HtmlTree.LI( |
|
153 getResource("doclet.Help_line_8"))); |
|
154 ul1.addContent(HtmlTree.LI( |
|
155 getResource("doclet.Help_line_9"))); |
|
156 ul1.addContent(HtmlTree.LI( |
|
157 getResource("doclet.Help_line_10"))); |
|
158 ul1.addContent(HtmlTree.LI( |
|
159 getResource("doclet.Help_line_11"))); |
|
160 ul1.addContent(HtmlTree.LI( |
|
161 getResource("doclet.Help_line_12"))); |
|
162 liClass.addContent(ul1); |
|
163 HtmlTree ul2 = new HtmlTree(HtmlTag.UL); |
|
164 ul2.addContent(HtmlTree.LI( |
|
165 getResource("doclet.Nested_Class_Summary"))); |
|
166 ul2.addContent(HtmlTree.LI( |
|
167 getResource("doclet.Field_Summary"))); |
|
168 ul2.addContent(HtmlTree.LI( |
|
169 getResource("doclet.Constructor_Summary"))); |
|
170 ul2.addContent(HtmlTree.LI( |
|
171 getResource("doclet.Method_Summary"))); |
|
172 liClass.addContent(ul2); |
|
173 HtmlTree ul3 = new HtmlTree(HtmlTag.UL); |
|
174 ul3.addContent(HtmlTree.LI( |
|
175 getResource("doclet.Field_Detail"))); |
|
176 ul3.addContent(HtmlTree.LI( |
|
177 getResource("doclet.Constructor_Detail"))); |
|
178 ul3.addContent(HtmlTree.LI( |
|
179 getResource("doclet.Method_Detail"))); |
|
180 liClass.addContent(ul3); |
|
181 Content line13 = getResource("doclet.Help_line_13"); |
|
182 Content para = HtmlTree.P(line13); |
|
183 liClass.addContent(para); |
|
184 ul.addContent(liClass); |
|
185 //Annotation Types |
|
186 Content aHead = HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING, |
|
187 getResource("doclet.AnnotationType")); |
|
188 Content liAnnotation = HtmlTree.LI(HtmlStyle.blockList, aHead); |
|
189 Content aline1 = getResource("doclet.Help_annotation_type_line_1"); |
|
190 Content aPara = HtmlTree.P(aline1); |
|
191 liAnnotation.addContent(aPara); |
|
192 HtmlTree aul = new HtmlTree(HtmlTag.UL); |
|
193 aul.addContent(HtmlTree.LI( |
|
194 getResource("doclet.Help_annotation_type_line_2"))); |
|
195 aul.addContent(HtmlTree.LI( |
|
196 getResource("doclet.Help_annotation_type_line_3"))); |
|
197 aul.addContent(HtmlTree.LI( |
|
198 getResource("doclet.Annotation_Type_Required_Member_Summary"))); |
|
199 aul.addContent(HtmlTree.LI( |
|
200 getResource("doclet.Annotation_Type_Optional_Member_Summary"))); |
|
201 aul.addContent(HtmlTree.LI( |
|
202 getResource("doclet.Annotation_Type_Member_Detail"))); |
|
203 liAnnotation.addContent(aul); |
|
204 ul.addContent(liAnnotation); |
|
205 //Enums |
|
206 Content enumHead = HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING, |
|
207 getResource("doclet.Enum")); |
|
208 Content liEnum = HtmlTree.LI(HtmlStyle.blockList, enumHead); |
|
209 Content eline1 = getResource("doclet.Help_enum_line_1"); |
|
210 Content enumPara = HtmlTree.P(eline1); |
|
211 liEnum.addContent(enumPara); |
|
212 HtmlTree eul = new HtmlTree(HtmlTag.UL); |
|
213 eul.addContent(HtmlTree.LI( |
|
214 getResource("doclet.Help_enum_line_2"))); |
|
215 eul.addContent(HtmlTree.LI( |
|
216 getResource("doclet.Help_enum_line_3"))); |
|
217 eul.addContent(HtmlTree.LI( |
|
218 getResource("doclet.Enum_Constant_Summary"))); |
|
219 eul.addContent(HtmlTree.LI( |
|
220 getResource("doclet.Enum_Constant_Detail"))); |
|
221 liEnum.addContent(eul); |
|
222 ul.addContent(liEnum); |
|
223 if (configuration.classuse) { |
|
224 Content useHead = HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING, |
|
225 getResource("doclet.Help_line_14")); |
|
226 Content liUse = HtmlTree.LI(HtmlStyle.blockList, useHead); |
|
227 Content line15 = getResource("doclet.Help_line_15"); |
|
228 Content usePara = HtmlTree.P(line15); |
|
229 liUse.addContent(usePara); |
|
230 ul.addContent(liUse); |
|
231 } |
|
232 if (configuration.createtree) { |
|
233 Content treeHead = HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING, |
|
234 getResource("doclet.Help_line_16")); |
|
235 Content liTree = HtmlTree.LI(HtmlStyle.blockList, treeHead); |
|
236 Content line17 = getResource("doclet.Help_line_17_with_tree_link", |
|
237 getHyperLink(DocPaths.OVERVIEW_TREE, |
|
238 configuration.getText("doclet.Class_Hierarchy")), |
|
239 HtmlTree.CODE(new StringContent("java.lang.Object"))); |
|
240 Content treePara = HtmlTree.P(line17); |
|
241 liTree.addContent(treePara); |
|
242 HtmlTree tul = new HtmlTree(HtmlTag.UL); |
|
243 tul.addContent(HtmlTree.LI( |
|
244 getResource("doclet.Help_line_18"))); |
|
245 tul.addContent(HtmlTree.LI( |
|
246 getResource("doclet.Help_line_19"))); |
|
247 liTree.addContent(tul); |
|
248 ul.addContent(liTree); |
|
249 } |
|
250 if (!(configuration.nodeprecatedlist || |
|
251 configuration.nodeprecated)) { |
|
252 Content dHead = HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING, |
|
253 getResource("doclet.Deprecated_API")); |
|
254 Content liDeprecated = HtmlTree.LI(HtmlStyle.blockList, dHead); |
|
255 Content line20 = getResource("doclet.Help_line_20_with_deprecated_api_link", |
|
256 getHyperLink(DocPaths.DEPRECATED_LIST, |
|
257 configuration.getText("doclet.Deprecated_API"))); |
|
258 Content dPara = HtmlTree.P(line20); |
|
259 liDeprecated.addContent(dPara); |
|
260 ul.addContent(liDeprecated); |
|
261 } |
|
262 if (configuration.createindex) { |
|
263 Content indexlink; |
|
264 if (configuration.splitindex) { |
|
265 indexlink = getHyperLink(DocPaths.INDEX_FILES.resolve(DocPaths.indexN(1)), |
|
266 configuration.getText("doclet.Index")); |
|
267 } else { |
|
268 indexlink = getHyperLink(DocPaths.INDEX_ALL, |
|
269 configuration.getText("doclet.Index")); |
|
270 } |
|
271 Content indexHead = HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING, |
|
272 getResource("doclet.Help_line_21")); |
|
273 Content liIndex = HtmlTree.LI(HtmlStyle.blockList, indexHead); |
|
274 Content line22 = getResource("doclet.Help_line_22", indexlink); |
|
275 Content indexPara = HtmlTree.P(line22); |
|
276 liIndex.addContent(indexPara); |
|
277 ul.addContent(liIndex); |
|
278 } |
|
279 Content prevHead = HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING, |
|
280 getResource("doclet.Help_line_23")); |
|
281 Content liPrev = HtmlTree.LI(HtmlStyle.blockList, prevHead); |
|
282 Content line24 = getResource("doclet.Help_line_24"); |
|
283 Content prevPara = HtmlTree.P(line24); |
|
284 liPrev.addContent(prevPara); |
|
285 ul.addContent(liPrev); |
|
286 Content frameHead = HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING, |
|
287 getResource("doclet.Help_line_25")); |
|
288 Content liFrame = HtmlTree.LI(HtmlStyle.blockList, frameHead); |
|
289 Content line26 = getResource("doclet.Help_line_26"); |
|
290 Content framePara = HtmlTree.P(line26); |
|
291 liFrame.addContent(framePara); |
|
292 ul.addContent(liFrame); |
|
293 Content allclassesHead = HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING, |
|
294 getResource("doclet.All_Classes")); |
|
295 Content liAllClasses = HtmlTree.LI(HtmlStyle.blockList, allclassesHead); |
|
296 Content line27 = getResource("doclet.Help_line_27", |
|
297 getHyperLink(DocPaths.ALLCLASSES_NOFRAME, |
|
298 configuration.getText("doclet.All_Classes"))); |
|
299 Content allclassesPara = HtmlTree.P(line27); |
|
300 liAllClasses.addContent(allclassesPara); |
|
301 ul.addContent(liAllClasses); |
|
302 Content sHead = HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING, |
|
303 getResource("doclet.Serialized_Form")); |
|
304 Content liSerial = HtmlTree.LI(HtmlStyle.blockList, sHead); |
|
305 Content line28 = getResource("doclet.Help_line_28"); |
|
306 Content serialPara = HtmlTree.P(line28); |
|
307 liSerial.addContent(serialPara); |
|
308 ul.addContent(liSerial); |
|
309 Content constHead = HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING, |
|
310 getResource("doclet.Constants_Summary")); |
|
311 Content liConst = HtmlTree.LI(HtmlStyle.blockList, constHead); |
|
312 Content line29 = getResource("doclet.Help_line_29", |
|
313 getHyperLink(DocPaths.CONSTANT_VALUES, |
|
314 configuration.getText("doclet.Constants_Summary"))); |
|
315 Content constPara = HtmlTree.P(line29); |
|
316 liConst.addContent(constPara); |
|
317 ul.addContent(liConst); |
|
318 Content divContent = HtmlTree.DIV(HtmlStyle.contentContainer, ul); |
|
319 Content line30 = HtmlTree.SPAN(HtmlStyle.emphasizedPhrase, getResource("doclet.Help_line_30")); |
|
320 divContent.addContent(line30); |
|
321 contentTree.addContent(divContent); |
|
322 } |
|
323 |
|
324 /** |
|
325 * Get the help label. |
|
326 * |
|
327 * @return a content tree for the help label |
|
328 */ |
|
329 @Override |
|
330 protected Content getNavLinkHelp() { |
|
331 Content li = HtmlTree.LI(HtmlStyle.navBarCell1Rev, helpLabel); |
|
332 return li; |
|
333 } |
|
334 } |