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