On Sun, Sep 23, 2018 at 5:18 AM Oliver Rettig <[email protected]> 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 <[email protected]> > > > Sent: Saturday, September 22, 2018 5:22 PM > > > To: [email protected] > > > 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 -- http://timboudreau.com
