Documentation
title: Table of Contents 
alias: TOC
  - [Welcome to the Help System]
  - [What's New]
  - [Short Formatting Reference]
  - Formatting
    - [Basic Formatting]
    - [Aliases]
    - [Lists]
    - [Substitutions]
    - [Images]
    - [Code Blocks]
    - [Indentation]
  - [Creating the TOC]
  - [Key Bindings]
  - [To Do]
  - [Index]
  - [Search]

-------
title: Welcome to the Help System
alias: overview
alias: home
icon: acthelp16

This is a new simple hypertext help system.
 
It's based on ''A Little Hypertext System'' so it includes:
  * Hyperlinks to other help pages
  * Simple searching ability
  * History
  * Simple wiki formatting
 
This new version also includes (see [What's New])
  * [Table of Contents]
  * Hypertext [aliases]
  * [Multi-level Lists]
  11. numeric lists
  ** bullet lists
  -- dash list
  * '''Bold text''' in wiki snytax and **bold text** in Markdown
  * ''Italic text'' in wiki syntax and *italic text* in Markdown
  * `code font` using tickmarks
  * variable and command substitutions 
  * support for images
  * support for home, index and browser buttons 
  * browser like key bindings
  * refresh help to update display
  * show toolbar and help outline widgets only if neccessary
  
You are using hyperhelp package version [[package present dgw::hyperhelp]]. 

If you see an error in the  package  version statement in the line before, you should  activate  the option
*-commandsubst* by running for instance a standalone hyperhelp script as

    tclsh hyperhelp.tcl filename --commandsubst
    

    
 
[hyperhelp.png]

-----
title: What's New
Here are some features of this help system not found in the previous version:
    * Table of Content
    * Bullets
    * Multiple levels of indentation
      -- like this
      -- ''and this''
      --- '''and even this'''
    * Aliases
    -- So this link [Welcome to the Help System]
    -- is the same as this link [Overview]
    * Substitutions
    -- variable substitution - you use Tcl/Tk $::tcl_patchLevel 
    -- command substitutions - you have package ttk/tile [[package provide tile]]
    * support for images 
    * support for toolbar buttons index, home, backward, forward, next, previous
    * key bindings to browser, 'n', 'p', 'space' etc.
    * refresh help to update display
    * indentation with markup
    * single page mode without toolbar and toc tree widget
    * more markdown like markup
-----
## <a name="shortref">Short Formatting Reference</a>

### Markdown Markup like sytnax

In this  example,  leading  and  trailing  spaces  are shown  with with dots:

---

'''headers'''
   ...-----
   ...## Page Title
   
   ...----- 
   ... ## <a name="alias">Page Title</a>
   
   ... ### Internal Header

The last lines produces:

### Internal Header

---

**Emphasis**

   ... *italic*

*italic* 

   ... **bold**

**bold** 

    ... normal code and `code in typewriter`

normal code and `code in typewriter`

Mix: **bold** combined with *italic* and `code samples` in one line

---

**Lists**

Nested lists are not possbile in basic Markdown compatible syntax.

Unordered lists:

  * item 1
  * item 2
  * item 3
  * item 4

Ordered lists:
  
  1. item 1
  2. item 2
  3. item 3

---

**Blockquotes**

Simple blockquoting can be done using the > sign

   ... > This text will be a blockquote

produces:

> This text will be a blockquote

Also lists can be indented:

   ... > * item 1
   ...    * item 2
   ...    * item 3

> * item 1
  * item 2
  * item 3
  
---

**Codeblock**

Are done by indeting text with three spaces:

    ... this will be code 
    ... this is another code line
    
produces:

    this will be code 
    this is another code line

---

**Images**

    !\[ \]\(hyperhelp.png\)  
    
produces:

![](hyperhelp.png)

Alternatively   you  can  (Markdown   incompatible)   even easier  just  write  the
filename with the png extension in rectangular brace onlys.


**Links**

   ...[Overview](#anchor)(#anchor)
   
produces: [Overview](#anchor)

The text in the rectangular braces must be a valid page title or alias.
Alternatively  you can as well use the easier,  Markdown  incompatible  syntax
writing the link in rectangular braces.

   ...[Overview]
   
produces as well: [Overview]

---

Horizontal  rules can be inserted by starting a line with exactly three  hyphens, such
as here:

   ... --- 

Produces a horizontal line:

---

Back to the top [shortref]

-----
title: Basic Formatting
alias: Formatting

The formatting code for the help pages follows much like the
tcler's wiki.

'''Links, lists, bold, italics, unformatted''' are
all done the same way. Inline code is shown using  tickmarks  like here `set x
4`.

   | You can also have block paragraphs by prefixing the first line 
with a " | ". It will wrap the text and indent all the lines. Only
one level of indentation can be requested.

Horizontal lines can be create with three or four minus signs or underlines as
the only characters on a line.

So --- at the beginning of a line produces:

---

An ___ at the beginning of a line produces the same:

___

Please note that 5 or more hyphens are used to separate pages.
 
[Aliases] and [multi-level lists] are only slightly more complicated.
 
-----
title: Aliases
alias: alias

''Aliases'' allow the same page to be referenced by different names.
So this link [Welcome to the Help System]
is the same as this link  [Overview].  The ''Home'' or ''home''  alias will be
sign the home page  which can be reached by  pressing  the home  button in the
toolbar.  If there is no such  alias  automatically  the  first  page  will be
called.


------
title: Substitutions

''Substitutions''  are done using the ''subst''  command. For security reasons
some commands are not evaluated like 
''file'',''open'',''socket'',''send'',''exec''.  
'''Anyway  you should  only use help files written by yourself or which you really trust.'''

Text with dollar signs is replaced with the appropiate variable: like here:
    \$::tcl_patchLevel == $::tcl_patchLevel
    
Text within doubled rectangular brace pairs is replaced with the output of the 
command like here:
    \[\[package present TclOO\]\] == [[package present TclOO]]
    
Please note, that since version there is a option for command substitutions for
the hyperhelp  widget which is set for security  reasons per default to false.
To enable this you should set this option to true for documentation  files you
trust.

If you see an error in the  package  version statement, you should  activate  
the option *-commandsubst* by running for instance a standalone hyperhelp 
script as

    tclsh hyperhelp.tcl filename --commandsubst

The  statement  must be  complete  within one line, so it is not  possible  to
create  long code  fragments.  It should be just used to  display  informative
details such as the  current Tcl/Tk or package version.
Missing variables as well as wrong command names are handled as well.
Here an example for a missing package:

[[package present dummy]]

And here an example for a non-existing variable:

$::tcl_dummyVar
    
They are simply not replaced.

------
title: Multi-level Lists
alias: lists
   1. numbered list
   1. numbered list
   11. numbered list
   11. numbered list
   1. numbered list
   1. numbered list
 
   * bullet list
   ** nested bullet list
   ** nested bullet list
   * bullet list
 
    - dash lists
    -- nested dashed list
    -- nested dashed list
    - dash lists
 
-----
title: Creating the TOC

The '''Table of Content''' is a just a help page with the
name (or [alias]) '''TOC''' which gets displayed in a
tile treeview widget. You can also view the [TOC] as a
normal help page.
 
Each line of the TOC help page that begins with a dash becomes
a node in the treeview. The level of indentation dictates the
tree structure.

------
title: Key Bindings

The  hyperhelp  window  provides  some  standard  key bindings to navigate the
content:

  * space, next: scroll down
  * backspace, prior: scroll up
  * Ctrl-k, Ctrl-j: scroll in half page steps up and down
  * Ctrl-space, Ctrl-b: scroll down or up
  * Ctrl-h, Alt-Left, b: browse back history if possible
  * Ctrl-l, Alt-Right: browse forward in history if possible
  * n, p: browse forward or backward in page order
  * Control-Plus, Control-Minus change font sizes 

------
title: Images

Images can be embedded as links using rectangular braces like:

   \[hyperhelp.png\]

will be rendered as ...

[hyperhelp.png]

Missing images will be replaced with a placeholder:

[missing.png]

  
------
title: Code Blocks

Code  blocks can be  created  by  indenting  text with 3 spaces,  such as the
following:

   set x 5
   puts \$x
------
title: Indentation

Here are some test indentations: 

___

Using "...| text" sytnax (... are here for whitespace)

   ... | test indent
   ... | test indent 2

produces:
   
   | test indent
   | test indent 2

___ 

Using "> * text" syntax where subsequent lines are just ".. * text"

   ... > * indented one with `code text`
   ...    * indented two with **bold text**
   ...    * indented three with *italic text*
   ... Should be not indented anymore ...

produces:

> * indented one with `code text`
  * indented two with **bold text**
  * indented three with *italic text*

Should be not indented anymore ...

Using  "> * text"  syntax  where  subsequent  lines  are  just ".. * text",
replace dots with whitespaces.

   >.* indented one with `code text`
   ..* indented two with **bold text**
   ..* indented three with *italic text*
   .
   Should be not indented anymore ...

Back to standard list?
  
Standard list:
  * item 1
  * item 2
  * item 3

___

> Here some indented text ...
which wraps over two lines ... but is displayed on one line ...

    > Here some indented text ...
    which wraps over two lines ... but is displayed on one line ...
  
Finally a longer lipsum fragment which is indented ...

> *Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
incididunt  ut labore et dolore  magna  aliqua. Ut enim ad minim  veniam, quis
nostrud  exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
Duis aute irure dolor in  reprehenderit  in voluptate velit esse cillum dolore
eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt
in culpa qui officia deserunt mollit anim id est laborum.*

------
title: To Do 
icon: idea
  1 Visual clues in TOC about what is a link (don't know treeview well enough  to do this) (Done, blue color)
  1 Mouse buttons 4 & 5 do history back and forward like Firefox and IE (not necessary)
  1 Image support--not hard, I just haven't needed it (done)
  1 msgcat support
  1 read  help  data  from  separate  file  (done)
  1 keyboard navigation like surf and Prior, Next, Space, BackSpace (done)
  1 fix history for duplicates (done)
  1 buttons at the top, navigation bar instead of internal text (done)
  1 change default font 
  1 wrap into snit widgets (done)