HelpWriter.java revision 3233:b5d08bc0d224 
1219820Sjeff/*
2219820Sjeff * Copyright (c) 1998, 2015, Oracle and/or its affiliates. All rights reserved.
3219820Sjeff * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4219820Sjeff *
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 java.io.*;
29
30import jdk.javadoc.internal.doclets.formats.html.markup.HtmlConstants;
31import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle;
32import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTag;
33import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree;
34import jdk.javadoc.internal.doclets.formats.html.markup.StringContent;
35import jdk.javadoc.internal.doclets.toolkit.Content;
36import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
37import jdk.javadoc.internal.doclets.toolkit.util.DocPaths;
38import jdk.javadoc.internal.doclets.toolkit.util.DocletAbortException;
39
40
41/**
42 * Generate the Help File for the generated API documentation. The help file
43 * contents are helpful for browsing the generated documentation.
44 *
45 *  <p><b>This is NOT part of any supported API.
46 *  If you write code that depends on this, you do so at your own risk.
47 *  This code and its internal interfaces are subject to change or
48 *  deletion without notice.</b>
49 *
50 * @author Atul M Dambalkar
51 */
52public class HelpWriter extends HtmlDocletWriter {
53
54    HtmlTree mainTree = HtmlTree.MAIN();
55
56    /**
57     * Constructor to construct HelpWriter object.
58     * @param filename File to be generated.
59     */
60    public HelpWriter(ConfigurationImpl configuration,
61                      DocPath filename) throws IOException {
62        super(configuration, filename);
63    }
64
65    /**
66     * Construct the HelpWriter object and then use it to generate the help
67     * file. The name of the generated file is "help-doc.html". The help file
68     * will get generated if and only if "-helpfile" and "-nohelp" is not used
69     * on the command line.
70     * @throws DocletAbortException
71     */
72    public static void generate(ConfigurationImpl configuration) {
73        HelpWriter helpgen;
74        DocPath filename = DocPath.empty;
75        try {
76            filename = DocPaths.HELP_DOC;
77            helpgen = new HelpWriter(configuration, filename);
78            helpgen.generateHelpFile();
79            helpgen.close();
80        } catch (IOException exc) {
81            configuration.standardmessage.error(
82                        "doclet.exception_encountered",
83                        exc.toString(), filename);
84            throw new DocletAbortException(exc);
85        }
86    }
87
88    /**
89     * Generate the help file contents.
90     */
91    protected void generateHelpFile() throws IOException {
92        String title = configuration.getText("doclet.Window_Help_title");
93        HtmlTree body = getBody(true, getWindowTitle(title));
94        HtmlTree htmlTree = (configuration.allowTag(HtmlTag.HEADER))
95                ? HtmlTree.HEADER()
96                : body;
97        addTop(htmlTree);
98        addNavLinks(true, htmlTree);
99        if (configuration.allowTag(HtmlTag.HEADER)) {
100            body.addContent(htmlTree);
101        }
102        addHelpFileContents(body);
103        if (configuration.allowTag(HtmlTag.FOOTER)) {
104            htmlTree = HtmlTree.FOOTER();
105        }
106        addNavLinks(false, htmlTree);
107        addBottom(htmlTree);
108        if (configuration.allowTag(HtmlTag.FOOTER)) {
109            body.addContent(htmlTree);
110        }
111        printHtmlDocument(null, true, body);
112    }
113
114    /**
115     * Add the help file contents from the resource file to the content tree. While adding the
116     * help file contents it also keeps track of user options. If "-notree"
117     * is used, then the "overview-tree.html" will not get added and hence
118     * help information also will not get added.
119     *
120     * @param contentTree the content tree to which the help file contents will be added
121     */
122    protected void addHelpFileContents(Content contentTree) {
123        Content heading = HtmlTree.HEADING(HtmlConstants.TITLE_HEADING, false, HtmlStyle.title,
124                getResource("doclet.Help_line_1"));
125        Content div = HtmlTree.DIV(HtmlStyle.header, heading);
126        Content line2 = HtmlTree.DIV(HtmlStyle.subTitle,
127                getResource("doclet.Help_line_2"));
128        div.addContent(line2);
129        if (configuration.allowTag(HtmlTag.MAIN)) {
130            mainTree.addContent(div);
131        } else {
132            contentTree.addContent(div);
133        }
134        HtmlTree htmlTree;
135        HtmlTree ul = new HtmlTree(HtmlTag.UL);
136        ul.addStyle(HtmlStyle.blockList);
137        if (configuration.createoverview) {
138            Content overviewHeading = HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING,
139                getResource("doclet.Overview"));
140            htmlTree = (configuration.allowTag(HtmlTag.SECTION))
141                    ? HtmlTree.SECTION(overviewHeading)
142                    : HtmlTree.LI(HtmlStyle.blockList, overviewHeading);
143            Content line3 = getResource("doclet.Help_line_3",
144                    getHyperLink(DocPaths.OVERVIEW_SUMMARY,
145                    configuration.getText("doclet.Overview")));
146            Content overviewPara = HtmlTree.P(line3);
147            htmlTree.addContent(overviewPara);
148            if (configuration.allowTag(HtmlTag.SECTION)) {
149                ul.addContent(HtmlTree.LI(HtmlStyle.blockList, htmlTree));
150            } else {
151                ul.addContent(htmlTree);
152            }
153        }
154        Content packageHead = HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING,
155                getResource("doclet.Package"));
156        htmlTree = (configuration.allowTag(HtmlTag.SECTION))
157                ? HtmlTree.SECTION(packageHead)
158                : HtmlTree.LI(HtmlStyle.blockList, packageHead);
159        Content line4 = getResource("doclet.Help_line_4");
160        Content packagePara = HtmlTree.P(line4);
161        htmlTree.addContent(packagePara);
162        HtmlTree ulPackage = new HtmlTree(HtmlTag.UL);
163        ulPackage.addContent(HtmlTree.LI(
164                getResource("doclet.Interfaces_Italic")));
165        ulPackage.addContent(HtmlTree.LI(
166                getResource("doclet.Classes")));
167        ulPackage.addContent(HtmlTree.LI(
168                getResource("doclet.Enums")));
169        ulPackage.addContent(HtmlTree.LI(
170                getResource("doclet.Exceptions")));
171        ulPackage.addContent(HtmlTree.LI(
172                getResource("doclet.Errors")));
173        ulPackage.addContent(HtmlTree.LI(
174                getResource("doclet.AnnotationTypes")));
175        htmlTree.addContent(ulPackage);
176        if (configuration.allowTag(HtmlTag.SECTION)) {
177            ul.addContent(HtmlTree.LI(HtmlStyle.blockList, htmlTree));
178        } else {
179            ul.addContent(htmlTree);
180        }
181        Content classHead = HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING,
182                getResource("doclet.Help_line_5"));
183        htmlTree = (configuration.allowTag(HtmlTag.SECTION))
184                ? HtmlTree.SECTION(classHead)
185                : HtmlTree.LI(HtmlStyle.blockList, classHead);
186        Content line6 = getResource("doclet.Help_line_6");
187        Content classPara = HtmlTree.P(line6);
188        htmlTree.addContent(classPara);
189        HtmlTree ul1 = new HtmlTree(HtmlTag.UL);
190        ul1.addContent(HtmlTree.LI(
191                getResource("doclet.Help_line_7")));
192        ul1.addContent(HtmlTree.LI(
193                getResource("doclet.Help_line_8")));
194        ul1.addContent(HtmlTree.LI(
195                getResource("doclet.Help_line_9")));
196        ul1.addContent(HtmlTree.LI(
197                getResource("doclet.Help_line_10")));
198        ul1.addContent(HtmlTree.LI(
199                getResource("doclet.Help_line_11")));
200        ul1.addContent(HtmlTree.LI(
201                getResource("doclet.Help_line_12")));
202        htmlTree.addContent(ul1);
203        HtmlTree ul2 = new HtmlTree(HtmlTag.UL);
204        ul2.addContent(HtmlTree.LI(
205                getResource("doclet.Nested_Class_Summary")));
206        ul2.addContent(HtmlTree.LI(
207                getResource("doclet.Field_Summary")));
208        ul2.addContent(HtmlTree.LI(
209                getResource("doclet.Constructor_Summary")));
210        ul2.addContent(HtmlTree.LI(
211                getResource("doclet.Method_Summary")));
212        htmlTree.addContent(ul2);
213        HtmlTree ul3 = new HtmlTree(HtmlTag.UL);
214        ul3.addContent(HtmlTree.LI(
215                getResource("doclet.Field_Detail")));
216        ul3.addContent(HtmlTree.LI(
217                getResource("doclet.Constructor_Detail")));
218        ul3.addContent(HtmlTree.LI(
219                getResource("doclet.Method_Detail")));
220        htmlTree.addContent(ul3);
221        Content line13 = getResource("doclet.Help_line_13");
222        Content para = HtmlTree.P(line13);
223        htmlTree.addContent(para);
224        if (configuration.allowTag(HtmlTag.SECTION)) {
225            ul.addContent(HtmlTree.LI(HtmlStyle.blockList, htmlTree));
226        } else {
227            ul.addContent(htmlTree);
228        }
229        //Annotation Types
230        Content aHead = HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING,
231                getResource("doclet.AnnotationType"));
232        htmlTree = (configuration.allowTag(HtmlTag.SECTION))
233                ? HtmlTree.SECTION(aHead)
234                : HtmlTree.LI(HtmlStyle.blockList, aHead);
235        Content aline1 = getResource("doclet.Help_annotation_type_line_1");
236        Content aPara = HtmlTree.P(aline1);
237        htmlTree.addContent(aPara);
238        HtmlTree aul = new HtmlTree(HtmlTag.UL);
239        aul.addContent(HtmlTree.LI(
240                getResource("doclet.Help_annotation_type_line_2")));
241        aul.addContent(HtmlTree.LI(
242                getResource("doclet.Help_annotation_type_line_3")));
243        aul.addContent(HtmlTree.LI(
244                getResource("doclet.Annotation_Type_Required_Member_Summary")));
245        aul.addContent(HtmlTree.LI(
246                getResource("doclet.Annotation_Type_Optional_Member_Summary")));
247        aul.addContent(HtmlTree.LI(
248                getResource("doclet.Annotation_Type_Member_Detail")));
249        htmlTree.addContent(aul);
250        if (configuration.allowTag(HtmlTag.SECTION)) {
251            ul.addContent(HtmlTree.LI(HtmlStyle.blockList, htmlTree));
252        } else {
253            ul.addContent(htmlTree);
254        }
255        //Enums
256        Content enumHead = HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING,
257                getResource("doclet.Enum"));
258        htmlTree = (configuration.allowTag(HtmlTag.SECTION))
259                ? HtmlTree.SECTION(enumHead)
260                : HtmlTree.LI(HtmlStyle.blockList, enumHead);
261        Content eline1 = getResource("doclet.Help_enum_line_1");
262        Content enumPara = HtmlTree.P(eline1);
263        htmlTree.addContent(enumPara);
264        HtmlTree eul = new HtmlTree(HtmlTag.UL);
265        eul.addContent(HtmlTree.LI(
266                getResource("doclet.Help_enum_line_2")));
267        eul.addContent(HtmlTree.LI(
268                getResource("doclet.Help_enum_line_3")));
269        eul.addContent(HtmlTree.LI(
270                getResource("doclet.Enum_Constant_Summary")));
271        eul.addContent(HtmlTree.LI(
272                getResource("doclet.Enum_Constant_Detail")));
273        htmlTree.addContent(eul);
274        if (configuration.allowTag(HtmlTag.SECTION)) {
275            ul.addContent(HtmlTree.LI(HtmlStyle.blockList, htmlTree));
276        } else {
277            ul.addContent(htmlTree);
278        }
279        if (configuration.classuse) {
280            Content useHead = HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING,
281                    getResource("doclet.Help_line_14"));
282            htmlTree = (configuration.allowTag(HtmlTag.SECTION))
283                    ? HtmlTree.SECTION(useHead)
284                    : HtmlTree.LI(HtmlStyle.blockList, useHead);
285            Content line15 = getResource("doclet.Help_line_15");
286            Content usePara = HtmlTree.P(line15);
287            htmlTree.addContent(usePara);
288            if (configuration.allowTag(HtmlTag.SECTION)) {
289                ul.addContent(HtmlTree.LI(HtmlStyle.blockList, htmlTree));
290            } else {
291                ul.addContent(htmlTree);
292            }
293        }
294        if (configuration.createtree) {
295            Content treeHead = HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING,
296                    getResource("doclet.Help_line_16"));
297            htmlTree = (configuration.allowTag(HtmlTag.SECTION))
298                    ? HtmlTree.SECTION(treeHead)
299                    : HtmlTree.LI(HtmlStyle.blockList, treeHead);
300            Content line17 = getResource("doclet.Help_line_17_with_tree_link",
301                    getHyperLink(DocPaths.OVERVIEW_TREE,
302                    configuration.getText("doclet.Class_Hierarchy")),
303                    HtmlTree.CODE(new StringContent("java.lang.Object")));
304            Content treePara = HtmlTree.P(line17);
305            htmlTree.addContent(treePara);
306            HtmlTree tul = new HtmlTree(HtmlTag.UL);
307            tul.addContent(HtmlTree.LI(
308                    getResource("doclet.Help_line_18")));
309            tul.addContent(HtmlTree.LI(
310                    getResource("doclet.Help_line_19")));
311            htmlTree.addContent(tul);
312            if (configuration.allowTag(HtmlTag.SECTION)) {
313                ul.addContent(HtmlTree.LI(HtmlStyle.blockList, htmlTree));
314            } else {
315                ul.addContent(htmlTree);
316            }
317        }
318        if (!(configuration.nodeprecatedlist ||
319                  configuration.nodeprecated)) {
320            Content dHead = HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING,
321                    getResource("doclet.Deprecated_API"));
322            htmlTree = (configuration.allowTag(HtmlTag.SECTION))
323                    ? HtmlTree.SECTION(dHead)
324                    : HtmlTree.LI(HtmlStyle.blockList, dHead);
325            Content line20 = getResource("doclet.Help_line_20_with_deprecated_api_link",
326                    getHyperLink(DocPaths.DEPRECATED_LIST,
327                    configuration.getText("doclet.Deprecated_API")));
328            Content dPara = HtmlTree.P(line20);
329            htmlTree.addContent(dPara);
330            if (configuration.allowTag(HtmlTag.SECTION)) {
331                ul.addContent(HtmlTree.LI(HtmlStyle.blockList, htmlTree));
332            } else {
333                ul.addContent(htmlTree);
334            }
335        }
336        if (configuration.createindex) {
337            Content indexlink;
338            if (configuration.splitindex) {
339                indexlink = getHyperLink(DocPaths.INDEX_FILES.resolve(DocPaths.indexN(1)),
340                        configuration.getText("doclet.Index"));
341            } else {
342                indexlink = getHyperLink(DocPaths.INDEX_ALL,
343                        configuration.getText("doclet.Index"));
344            }
345            Content indexHead = HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING,
346                    getResource("doclet.Help_line_21"));
347            htmlTree = (configuration.allowTag(HtmlTag.SECTION))
348                    ? HtmlTree.SECTION(indexHead)
349                    : HtmlTree.LI(HtmlStyle.blockList, indexHead);
350            Content line22 = getResource("doclet.Help_line_22", indexlink);
351            Content indexPara = HtmlTree.P(line22);
352            htmlTree.addContent(indexPara);
353            if (configuration.allowTag(HtmlTag.SECTION)) {
354                ul.addContent(HtmlTree.LI(HtmlStyle.blockList, htmlTree));
355            } else {
356                ul.addContent(htmlTree);
357            }
358        }
359        Content prevHead = HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING,
360                getResource("doclet.Help_line_23"));
361        htmlTree = (configuration.allowTag(HtmlTag.SECTION))
362                ? HtmlTree.SECTION(prevHead)
363                : HtmlTree.LI(HtmlStyle.blockList, prevHead);
364        Content line24 = getResource("doclet.Help_line_24");
365        Content prevPara = HtmlTree.P(line24);
366        htmlTree.addContent(prevPara);
367        if (configuration.allowTag(HtmlTag.SECTION)) {
368            ul.addContent(HtmlTree.LI(HtmlStyle.blockList, htmlTree));
369        } else {
370            ul.addContent(htmlTree);
371        }
372        Content frameHead = HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING,
373                getResource("doclet.Help_line_25"));
374        htmlTree = (configuration.allowTag(HtmlTag.SECTION))
375                ? HtmlTree.SECTION(frameHead)
376                : HtmlTree.LI(HtmlStyle.blockList, frameHead);
377        Content line26 = getResource("doclet.Help_line_26");
378        Content framePara = HtmlTree.P(line26);
379        htmlTree.addContent(framePara);
380        if (configuration.allowTag(HtmlTag.SECTION)) {
381            ul.addContent(HtmlTree.LI(HtmlStyle.blockList, htmlTree));
382        } else {
383            ul.addContent(htmlTree);
384        }
385        Content allclassesHead = HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING,
386                getResource("doclet.All_Classes"));
387        htmlTree = (configuration.allowTag(HtmlTag.SECTION))
388                ? HtmlTree.SECTION(allclassesHead)
389                : HtmlTree.LI(HtmlStyle.blockList, allclassesHead);
390        Content line27 = getResource("doclet.Help_line_27",
391                getHyperLink(DocPaths.ALLCLASSES_NOFRAME,
392                configuration.getText("doclet.All_Classes")));
393        Content allclassesPara = HtmlTree.P(line27);
394        htmlTree.addContent(allclassesPara);
395        if (configuration.allowTag(HtmlTag.SECTION)) {
396            ul.addContent(HtmlTree.LI(HtmlStyle.blockList, htmlTree));
397        } else {
398            ul.addContent(htmlTree);
399        }
400        Content sHead = HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING,
401                getResource("doclet.Serialized_Form"));
402        htmlTree = (configuration.allowTag(HtmlTag.SECTION))
403                ? HtmlTree.SECTION(sHead)
404                : HtmlTree.LI(HtmlStyle.blockList, sHead);
405        Content line28 = getResource("doclet.Help_line_28");
406        Content serialPara = HtmlTree.P(line28);
407        htmlTree.addContent(serialPara);
408        if (configuration.allowTag(HtmlTag.SECTION)) {
409            ul.addContent(HtmlTree.LI(HtmlStyle.blockList, htmlTree));
410        } else {
411            ul.addContent(htmlTree);
412        }
413        Content constHead = HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING,
414                getResource("doclet.Constants_Summary"));
415        htmlTree = (configuration.allowTag(HtmlTag.SECTION))
416                ? HtmlTree.SECTION(constHead)
417                : HtmlTree.LI(HtmlStyle.blockList, constHead);
418        Content line29 = getResource("doclet.Help_line_29",
419                getHyperLink(DocPaths.CONSTANT_VALUES,
420                configuration.getText("doclet.Constants_Summary")));
421        Content constPara = HtmlTree.P(line29);
422        htmlTree.addContent(constPara);
423        if (configuration.allowTag(HtmlTag.SECTION)) {
424            ul.addContent(HtmlTree.LI(HtmlStyle.blockList, htmlTree));
425        } else {
426            ul.addContent(htmlTree);
427        }
428        Content divContent = HtmlTree.DIV(HtmlStyle.contentContainer, ul);
429        Content line30 = HtmlTree.SPAN(HtmlStyle.emphasizedPhrase, getResource("doclet.Help_line_30"));
430        divContent.addContent(line30);
431        if (configuration.allowTag(HtmlTag.MAIN)) {
432            mainTree.addContent(divContent);
433            contentTree.addContent(mainTree);
434        } else {
435            contentTree.addContent(divContent);
436        }
437    }
438
439    /**
440     * Get the help label.
441     *
442     * @return a content tree for the help label
443     */
444    @Override
445    protected Content getNavLinkHelp() {
446        Content li = HtmlTree.LI(HtmlStyle.navBarCell1Rev, helpLabel);
447        return li;
448    }
449}
450