dgw::hyperhelp


Name

dgw::hyperhelp - hypertext help system

Description

DDG 2020-02-01: dgw::hyperhelp is a help system using a Wiki/Markdown like Markup language, based on A Hypertext Help System which was cleaned up, extended and documented - HTML - manual links see below. Here an example help page for explaining the hyperhelp markup https://chiselapp.com/user/dgroth/repository/tclcode/doc/tip/dgw/hyperhelp-docu.txt - so all documentation is in a single text file using a well known Markup language. There is as well the possibility to reate help files which are as well valid Markdown documents. Here an example for this approach: https://chiselapp.com/user/dgroth/repository/tclcode/doc/tip/dgw/hyperhelp-markdown-sample.md - here in raw text: https://chiselapp.com/user/dgroth/repository/tclcode/artifact?name=596773b6b985ca11&txt=1 The help browser system displays a nice table of contents table in a ttk::treeview widget, offers index, search facilities and sophisticated keyboard navigation.

Links

Example

The package is both a standalone application to directly view help files, as well loadable within an existing application.

package require dgw::hyperhelp
set helpfile [file join [file dirname [info script]] hyperhelp-docu.txt]
set hhelp [dgw::hyperhelp .help -helpfile $helpfile -commandsubst true]
pack $hhelp -side top -fill both -expand true
$hhelp help overview

The Tcl file can be as well executed as standalone application using the following command line:

tclsh hyperhelp.tclhelpfile ?--commandsubst?

Give the flag --commandsubst if you wan't command substitutions within the helpfile. Please not that file, exec, send and socket are not evaluated at all for security reasons even if you supply the --commandsubst flag.

Image

Below is an image of the running application.

dgw::hyperhelp-image


Jeff Smith 2020-02-05 : Below is an online demo using CloudTk. This demo runs HyperHelp in an Alpine Linux Docker container. It is a 28.7MB image which is made up of Alpine Linux + tclkit + dgw-hyperhelp.kit + libx11 + libxft + fontconfig + ttf-linux-libertine. It is run under a user account in the container. The container is restrictive with permissions for "Other" removed for "execute" and "read" for certain directories. Also the Alpine Linux container is using a strange font so the demo looks a bit funky! (I will work on changing the font in the container.)

Jeff Smith 2020-02-14 : Font issue fixed in Alpine Linux Docker container.


See also

Discussion

Please discuss here ...

Jeff Smith 2020-02-05 : I had to add hyperhelp.png from this wiki to the dgw directory for the demo to run.

DDG 2020-02-05: Thanks for mentioning the image error. I uploaded the image as well to the fossil repository, further I catch now against errors for missing images, with a helpful message within the document, also command substitution errors are better catched. Really nice the CloudTk example. Even the key based navigation using the 'n', 'p' and 'space' works :)

DDG 2020-02-07: I updated to version 0.7 which solved problems with single page help files. Further now the Treeview widget is hidden if there is no "Table of Contents" page, and the toolbar is automatically hidden if there is only one page. Last but not least a subset of Markdown is usable, so you can create valid Markdown files which are at the same time valid help files. See https://chiselapp.com/user/dgroth/repository/tclcode/doc/tip/dgw/hyperhelp-markdown-sample.md for an example help page. Here the raw text source: - here in raw text: https://chiselapp.com/user/dgroth/repository/tclcode/artifact?name=596773b6b985ca11&txt=1

Jeff Smith 2020-02-11 : In the Key Bindings Ctrl-k and Ctrl-j produce an error on version 0.7. Try it in the demo above.

DDG 2020-02-17: Thanks for reporting this. I fixed the two keys and uploaded a new version to the fossil repo. I further disabled command substitution on default just for security reasons. You can still enable them both on app and on library level using: tclsh hyperhelp.tcl helpfile --commandsubst on the terminal for instance if you run it as application. Please note, that still file, exec, socket and send will be not evaluated even if you supply --commandsubst.

Jeff Smith 2020-02-19 : Updated HyperHelp CloudTk demo to version 0.8.

Jeff Smith 2020-02-19 : Entering text in the Search field on the top menu bar produces a search results page with another Search field and button on this page. If you press the Search button on the search results page it produces an error on version 0.8.

DDG 2020-02-19 : Indeed. I never used this internal search entry, only the search entry on top, the internal is from the original implementation. I fixed this internal now, but made it now hidden if the toolbar on top is enabled, it does not make sense to have two search entries. Also the focus sticks within the search entry, simplifying now the search. Switched version to 0.8.1, only 19 bugs to fix until version 1.0 ;) And thanks, for taking care of the hyperhelp widget :) My goal was just to make one of the gems of this wiki more usable and available to a broader range of people.

Jeff Smith 2020-02-20 : Updated HyperHelp CloudTk demo to version 0.8.1. (Good luck getting to version 1.0)