Jep, agree. I also tried DocBook and broke my neck on it. Did cost too
much time.
Too keep it simply we could go with the standard Online help but with an
offline option so the help can be read if not connected. Conversion
would be minimal as one "only" would need to migrate the control XML
files deciding the book order (topics etc.) but most of the core text
stays the same as they already are in HTML.
Bernd
On 9/23/2018 8:55 AM, Tim Boudreau wrote:
On Sun, Sep 23, 2018 at 5:18 AM Oliver Rettig <oliver.ret...@orat.de> wrote:
Hi Jan,
this sound interesting for me. In the past I have also thought about
DocBook
Having written two books using DocBook, one word: Don't.
Something simple and text-based, especially something you can fill the gaps
in with HTML markup if you've just GOT to do something fancy, is more than
enough. Markdown or one of the many cousins it has is simple and noise free.
With DocBook, on the other hand, you get
- A gargantuan DTD you have to pick a subset of to keep your sanity, and
then police that uses stay within that subset - you don't need something
that includes every subvariant of a footnote or endnote ever invented for
an academic paper
- Last time I dealt with it, there were no Java XML parsers that could
actually handle the stylesheets
- Markup that is far less suggestive of what the end result is going to
look like
You could do most of the structuring of help with a simple convention for
naming and nestling subfolders, with a very simple markup language.
DocBook for this is kind of like launching an aircraft carrier to swat a
fly.
-Tim
. Can you share
the XSLT stylesheets to get an idea how it works and how looks?
There exist some ant tasks
http://ant4docbook.sourceforge.net/
maybe based on we can create some default procedure to integreate help
into our platform
apps.
At the moment I also use docuwiki to make documentation for my patform
apps availble:
http://upperlimb.orat.de/doku.php
There is a plugin to create the tox.xml and map.xml file from java-help
https://github.com/i-net-software/dokuwiki-plugin-siteexport
So at the moment I create my documentation by dokuwiki ant than I create
my java-help
based on this. The advantage is that some custumers inclusive me can easy
write together
on the documentation and from time to time I update ma java-doc from this.
Any ideas are welcome:-)
best regards
Oliver
Btw, not NB related, we switched from JavaHelp to a set of static HTML
pages
(generated using custom XSLT stylesheets from DocBook XML source): + no
internet access is required
+ preserving context help linking
+ easier styling
+ responsive layout
- limited search capabilities (keywords processed by lucene are exported
into simple text file, no complex queries can be used)
That search can be hardly improved without serving HTML pages via local
webserver (which was rejected by lead developers). Without webserver
there
are many security constraints like inability to load external content
dynamically or problematic cookie/local storage management.
We also publish same document to online CMS portal, here with the full
search capabilities. It is available there as a set of pages with
advanced
navigation (outline, breadcrumbs, prev/next buttons), but also as a
single
PDF file (which is stil requested by many users - it can be stored as
single file and printed easily). These outputs we produce again from
single
DocBook XML source.
It is up to the user if he choose online/offline (context) help. The
default
option is online help. That offline variant is considered as a fallback
in
case of none or poor internet connection.
Jan
-----Original Message-----
From: Bernd Ruehlicke <bernd.ruehli...@eriksfiord.com>
Sent: Saturday, September 22, 2018 5:22 PM
To: dev@netbeans.incubator.apache.org
Subject: Re: Future of JavaHelp (or a replacement) in NetBeans?
Uh ... my application is often used in areas without any network
connection. Even though the UI is not the most beautiful in the world
it
is a very helpful tool and I use JavaHelp quite extensively. Of course
I
am in line with Time, a chance is needed but we should have the case in
mind for off-line users. With JavaHelp I like that it is integrated to
my application and not some website - it ships with it integrated
nicely. This could of course be solve easy by simply add a Help->Update
Offline Help and it simply dumps the current online help to disk for
offline usage. Maybe even automatically avoiding a menu item, using the
same idea as the Update Server that on startup the app is checking of
the online documentation has been updated and pops up a suggestion to
the user to "Want to update offline documentation", i.e. the online
help
