hyperhelp-package

Name
Description
Links
Main Features
Example
Image
See also
Discussion

Name

hyperhelp::hyperhelp - hypertext help system

Description

DDG: hyperhelp::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://github.com/mittelmarkhyperhelp/blob/master/hyperhelp/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 create help files which are as well valid Markdown documents. Here an example for this approach: https://github.com/mittelmark/hyperhelp/blob/master/hyperhelp/hyperhelp-markdown-sample.md . The help browser system displays a nice table of contents table in a ttk::treeview widget, offers index, search facilities and sophisticated keyboard navigation. A port to the R tcltk library is as well available if requested. Since version 0.9.0 in its own package (hyperhelp). Before it was part of the dgw-package. Since version 1.0.0 as well images can be embedded within the document as base64 encodes.

Main Features

all in one file documentation for several help pages (TOC, images, text)
single Tcl file
Tcl package to be embedded in your Tk application
Tcl standalone application to browse help files

Example

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

package require hyperhelp
set helpfile [file join [file dirname [info script]] hyperhelp-docu.txt]
set hhelp [hyperhelp::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.tcl helpfile ?--commandsubst?

Give the flag --commandsubst if you want 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 2023-09-24 : Below is an online demo using CloudTk. This demo runs HyperHelp in an Alpine Linux Docker container. It is a 27.7MB image which is made up of Alpine Linux + tclkit + hyperhelp-package-1.0.0.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.

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)

DDG 2021-10-25: Fixing an issue on windows, because of missing send command. Test as well, with R and its tcltk library. Works!!

DDG 2023-08-27: Making a separate small package at https://github.com/mittelmark/hyperhelp

DDG 2023-09-23: Released version 1.0.0 which allows embedding of images and icons as base64 codes and which supports as well TODO lists

Jeff Smith 2023-09-24 : Updated HyperHelp CloudTk demo to version 1.0.0. Also fixed typo in "hyperhelp-docu.txt" from "package present dgw::hyperhelp" to "package present hyperhelp".

DDG 2023-09-24: Thanks for updating. I fix this on my repo. As I can see the Unicode symbols do not work on the server. May be better I change the TODO icons from Unicode symbols to images ...

DDG 2023-09:30: Version 1.0.1 adds support for tclmain by creating a hyperhelp::main procedure, no additional functionality.

Category Package

Category Widget

Category Snit Widgets