Использование JavaHelp для документации конечного пользователя по приложениям, инструментам или плагинам на основе NetBeans, чтобы облегчить задачу?

Короткий верхний раздел этого поста - это то, что я пытаюсь сделать. Вторая часть - то, что было сделано до сих пор. Это действительно долго, но вы должны быть в состоянии увидеть, что я делаю из верхней части здесь. Просто проверьте заметки, если вы заинтересованы в более подробной информации.

Я создаю приложение, используя платформу NetBeans в качестве отправной точки. Предыдущая версия использовала JavaHelp для документации конечного пользователя. Я в порядке, продолжая практику, когда я пишу всю новую документацию, но я нахожу недостаток, если информация о ее использовании.

Я понял достаточно далеко, как создать новый HelpSet и отношения XML к HTML. Я могу передать код в новых документах и ​​применить скриншоты, но это кажется очень ручным, и мне интересно, есть ли какие-нибудь плагины или инструменты для облегчения создания?

Делая гугл-фу, я нахожу несколько постов по этой теме, но большинство из них относятся к 2003 году и сейчас находятся в тупике. Использование JavaHelp устарело? Ниже я обрисовываю в общих чертах, что я сделал для любого назидания людей, ищущих ту же самую вещь, и, возможно, кто-то может указать на неэффективность того, как я это делаю.

Это не страшный подход, но необходимость добавлять строки в два XML-файла для каждого загружаемого мной файла, а затем иметь длинный URL-адрес кода, на который нужно указывать каждый раз, становится неудобным для быстрой записи этого материала.

Спасибо за прочтение.

Изменить: одна вещь, с которой у меня есть проблема. Я не знаю, как изменить начальную целевую страницу для JavaHelp. Прямо сейчас написано "В этом списке перечислены все документы, загруженные с помощью IDE, щелкните слева, чтобы прочитать их". Это ничего не значит для моих конечных пользователей.

Кроме того, я не знаю, как изменить порядок тем слева. Прямо сейчас они не находятся в каком-либо полезном порядке. Я хотел бы расположить их в алфавитном порядке или поместить в какой-нибудь полезный порядок.

В Netbeans щелкните правой кнопкой мыши на модуле New->Other, выберите Module Development и выберите JavaHelp Help Set. Это создаст новый пакет под модулем. Он будет следовать соглашению об именах вашего модуля и добавит.docs к концу. Например, org.netbeans.newmodule.docs.

При этом он создаст 6 файлов:

package-info.java (package info file)
<modulename>-about.html (As seen HTML help file)

<modulename>-map.xml (creates a connection to the HTML pages (E.G about) to a target, used in making links & building the hierarchy for the table of contents)
<modulename>-toc.xml (Table of contents XML)
<modulename>-hs.xml (Specifies the Table of contents view & javax control, & index)
<modulename>-idx.xml (Controls the index)

Первый файл HTML является начальной информационной страницей. Это файл справки, который будет читать конечный пользователь. Это просто обычный HTML в определенном формате.

<modulename>-about.html
<!--
To change this template, choose Tools | Templates
and open the template in the editor.
-->
<html>
    <head>
        <title>About Module</title>
        <link rel="stylesheet" href="nbdocs:/org/netbeans/modules/usersguide/ide.css" type="text/css">
        <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
    </head>
    <body>
        <h2>About Module</h2>
        <p>
            <!-- TODO describe your module, add more pages... -->
        </p>
    </body>
</html>
<!--
Tip: to create a link which will open in an external web browser, try:
<object classid="java:org.netbeans.modules.javahelp.BrowserDisplayer">
    <param name="content" value="http://www.netbeans.org/">
    <param name="text" value="<html><u>http://www.netbeans.org/</u></html>">
    <param name="textFontSize" value="medium">
    <param name="textColor" value="blue">
</object>
To create a link to a help set from another module, you need to know the code name base and path, e.g.:
<a href="nbdocs://org.netbeans.modules.usersguide/org/netbeans/modules/usersguide/configure/configure_options.html">Using the Options Window</a>
(This link will behave sanely if that module is disabled or missing.)
-->

Все может быть добавлено в <body> раздел документа. Я работал с простым встроенным CSS и использованием <FONT> теги работали до сих пор. Он также ссылается на внешний CSS-файл, поэтому я предполагаю, что это тоже сработает. Вы можете ссылаться на другие файлы справки, указав путь. Путь всегда будет начинаться с nbdocs:/<yorumodulepath>

НАПРИМЕР: Any event added here will show up on the <a href="nbdocs:/com/mymodule/mod1/start/docs/start-about.html">start page</a>

Изображения могут быть связаны относительно, если они находятся в том же исходном пакете, что и javahelp.

НАПРИМЕР: <img src="startPageLogo.png">

Файлы XML важны, потому что они устанавливают структуру справочной документации.

 <modulename>-map.xml

Этот файл связывает файлы HTML с файлами nbdocs. Это позволит вам создавать ссылки внутри HTML-файлов на другие местоположения файлов справки и правильно открывать и закрывать дерево JavaHelp. Структура выглядит так: <mapID target="<com.yoruproject.modname" url="<htmlfilename/.html"/>

НАПРИМЕР

  <?xml version="1.0" encoding="UTF-8"?>
<!--
To change this template, choose Tools | Templates
and open the template in the editor.
-->
<!DOCTYPE map PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp Map Version 2.0//EN" "http://java.sun.com/products/javahelp/map_2_0.dtd">
<map version="2.0">
    <mapID target="com.mymodule.mod1.start.about" url="start-about.html"/>
    <mapID target="com.mymodule.mod1.start.calevents" url="start-calevents.html"/>
    <mapID target="com.mymodule.mod1.start.backupreminder" url="start-backupreminder.html"/>

</map>




<modulename>-toc.xml

Этот файл управляет структурой в левой части JavaHelp, которую пользователь может использовать для перехода к различным областям справочной документации. Формат выглядит так:

 <toc version="2.0">
        <tocitem text="Top Category">
            <tocitem text="SubItem" target="com.mymod.mod1.start.about"/>
            <tocitem text="SubCategory">
                <tocitem text="SubCategoryItem1" target="com.mymod.mod1.start.backupreminder"/>
                <tocitem text="SubCategory2" target="com.mymod.mod1.start.about">
                    <tocitem text="SubCategoryItem2" target="com.mymod.mod1.start.classifyreminder"/>
                </tocitem>
     </tocitem>
    </tocitem>
</toc>

Вот пример полного файла:

    <?xml version="1.0" encoding="UTF-8"?>
<!--
To change this template, choose Tools | Templates
and open the template in the editor.
-->
<!DOCTYPE toc PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp TOC Version 2.0//EN" "http://java.sun.com/products/javahelp/toc_2_0.dtd">
<toc version="2.0">
    <tocitem text="Start Page">
        <tocitem text="Getting Started" target="com.mymodule.mod1.start.about"/>
        <tocitem text="Calendar Events" target="com.mymodule.mod1.start.calevents"/>
        <tocitem text="Notification Pane">
            <tocitem text="Backup Reminders" target="com.mymodule.mod1.start.backupreminder"/>
            <tocitem text="New Classification Downloads" target="com.mymodule.mod1.start.backupreminder"/>
        </tocitem>
    </tocitem>
</toc>







<modulename>-hs.xml

Я еще не связывался с этим файлом. Кажется, что он очерчивает расположение оглавления, файла IDX для индекса и файла SearchView (который был местоположением Java по умолчанию).

    <?xml version="1.0" encoding="UTF-8"?>
<!--
To change this template, choose Tools | Templates
and open the template in the editor.
-->
<!DOCTYPE helpset PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp HelpSet Version 2.0//EN" "http://java.sun.com/products/javahelp/helpset_2_0.dtd">
<helpset version="2.0">
    <title>HMSStart Help</title>
    <maps>
        <homeID>com.mymodule.mod1.start.about</homeID>
        <mapref location="start-map.xml"/>
    </maps>
    <view mergetype="javax.help.AppendMerge">
        <name>TOC</name>
        <label>Table of Contents</label>
        <type>javax.help.TOCView</type>
        <data>start-toc.xml</data>
    </view>
    <view mergetype="javax.help.AppendMerge">
        <name>Index</name>
        <label>Index</label>
        <type>javax.help.IndexView</type>
        <data>start-idx.xml</data>
    </view>
    <view>
        <name>Search</name>
        <label>Search</label>
        <type>javax.help.SearchView</type>
        <data engine="com.sun.java.help.search.DefaultSearchEngine">JavaHelpSearch</data>
    </view>
</helpset>
Источник

1 ответ

Решение

В чем проблема номер один? Является ли текущий процесс слишком трудоемким? Я думаю, что было бы легче помочь, если бы вы задавали один четкий вопрос за один раз. Во всяком случае, вот несколько советов, которые могут помочь.

Насколько я могу сказать, разработка Sun JavaHelp прекратилась. Вы можете попробовать Oracle Help. Это очень похоже на JavaHelp, но более активно поддерживается.

Существуют коммерческие средства разработки, которые помогают избавиться от рутинной работы по созданию JavaHelp (или справки Oracle). Примеры:

  • Хелен: инструмент только для JavaHelp, последний выпуск которого был выпущен в апреле 2012 года (поэтому JavaHelp не может быть мертвым в конце концов...)
  • WebWorks ePublisher: инструмент, который может генерировать гораздо больше форматов справки, кроме JavaHelp

Другими вариантами являются бесплатные основанные на XML каркасы документации DocBook и DITA, которые предоставляют таблицы стилей (см. Здесь и здесь), которые генерируют JavaHelp из источников XML (я думаю, что очень мало нужно для того, чтобы это работало и для справки Oracle).

Есть и другие (не JavaHelp) альтернативы. Например, DocBook также предоставляет сетевой формат справки: WebHelp. Возможно, вы найдете это интересным.

Источник
Другие вопросы по тегам