Более короткая верхняя часть этого поста — это то, что я пытаюсь сделать. Вторая часть - это то, что было сделано до сих пор. Это очень долго, но вы должны увидеть, что я делаю, из верхней части здесь. Просто проверьте примечания, если вы заинтересованы в более подробной информации.
Я создаю приложение, используя платформу NetBeans в качестве отправной точки. Предыдущая версия использовала JavaHelp для документации конечного пользователя. Я согласен продолжать практику, поскольку я пишу всю новую документацию, но я нахожу нехватку информации о ее использовании.
Я достаточно понял, как создать новый HelpSet и отношения XML к HTML. Я могу передать код в новые документы и применить скриншоты, но это кажется очень ручным, и мне интересно, есть ли какие-либо плагины или инструменты для облегчения создания?
Покопавшись в Google-foo, я нашел несколько сообщений по этой теме, но большинство из них относятся к 2003 году и теперь являются тупиковыми. Использование JavaHelp устарело? Ниже я описываю, что я сделал для назидания людей, ищущих одно и то же, и, возможно, кто-то может указать на неэффективность того, как я это делаю.
Это неплохой подход, но необходимость добавлять строки в два XML-файла для каждого файла, который я загружаю, а затем наличие длинного URL-адреса кода, на который нужно указывать каждый раз, кажется громоздким для быстрого написания этого материала.
Спасибо за прочтение.
Редактировать: У меня есть одна проблема. Я не знаю, как изменить начальную целевую страницу JavaHelp. Прямо сейчас он говорит: «Это список всей документации, загруженной с IDE, щелкните слева, чтобы прочитать ее». Это ничего не будет значить для моих конечных пользователей.
Кроме того, я не знаю, как изменить порядок тем слева. Прямо сейчас они, кажется, не находятся в каком-либо полезном порядке. Я хотел бы расположить их в алфавитном порядке или в каком-то полезном порядке.
В Netbeans щелкните правой кнопкой мыши модуль «Создать» -> «Другое», щелкните «Разработка модуля», выберите «Набор справки JavaHelp». Это создаст новый пакет под модулем. Он будет следовать соглашению об именах вашего модуля и добавит в конец .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>
E.G: Any event added here will show up on the <a href="nbdocs:/com/mymodule/mod1/start/docs/start-about.html">start page</a>
Изображения могут быть связаны относительными ссылками, если они находятся в том же исходном пакете, что и javahelp.
E.G: <img src="startPageLogo.png">
Файлы XML важны, потому что они устанавливают структуру справочной документации.
<modulename>-map.xml
Этот файл связывает файлы HTML с файлами nbdocs. Это позволит вам создавать ссылки внутри файлов HTML на другие местоположения файлов справки и правильно открывать и закрывать дерево JavaHelp. Структура выглядит так: <mapID target="<com.yoruproject.modname" url="<htmlfilename/.html"/>
E.G
<?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>
