diff --git a/shtmlview/shtmlview.html b/shtmlview/shtmlview.html index 7cd373b..9cc3481 100644 --- a/shtmlview/shtmlview.html +++ b/shtmlview/shtmlview.html @@ -1,552 +1,3637 @@ +# -*- mode: tcl ; fill-column: 80 -*- +#* shtmlview HTML-Viewer +#* Cleaned up version of Robert Heller's HTMLHelp tool +#* Detlef Groth's one just can load and display htmlpages +#* ToDo: +#* - remove BWidget: break LabelEntry into entry and label ok +#* - remove snit widget LabelEntry ok +#* - demo with sample.html with tables, images +#* - docutils help page take this as sample2 +#* - toplevel title ony if widget is 'almost' toplevel ok +#* - check back/forward against same entries ok? +#* - capitalize private functions +#* - method dosearch {string {direction forward}} +#* - option browsecmd -> to be executed each time a webpage is browsed +#* - method url -> to get the url +#* - delegate method and options to text +#* - balloon for buttons +#* ------------------------------------------------------------------ +#* Based on HTMLHelp.tcl - HTML Help +#* Created by Robert Heller on Sat Jun 6 10:00:03 2009 +#* ------------------------------------------------------------------ +#* Modification History: Revision 1.1 2002/07/28 14:03:50 heller +#* Add it copyright notice headers +#* Modification History: 2018-10-10 shtmlview 1.0 started, based on HtmlHelp 1.0 of Robert Heller +#* - removing toc part +#* - removing toplevel approach of bwidgets +#* - renamed the namespace to shtmlview::shtmlview +#* - adding more bindings to increase/decrease the font size +#* - adding simple browse function +#* - fixing a parsing bug in html code by adding code of Kevin Walzer's module tkwebview +#* - importing tile scrollbar if available +#* - 2018-10-20 removed bwidget dependency +#* - tablesupport option +#* - 2022-03-XX bugfixes for anchor links and copy operation, support for Markdown files and inline base encoded images +#* ------------------------------------------------------------------ +#* Contents: +#* +#* Simple HTML display library by Stephen Uhler (stephen.uhler@sun.com) +#* Copyright (c) 1995 by Sun Microsystems +#* Version 0.3 Fri Sep 1 10:47:17 PDT 1995 +#* +#* Modified to support some 8.0 and 8.1 font conventions by Clif Flynt (clif@cflynt.com) +#* Modifications copyright (c) 1998 by Flynt Consulting Services, Version 0.3.1 Jan 10, 1999 +#* Modifications copyright (c) 1999 by Flynt Consulting Services, Added table support (another new idea). 7/31/99 +#* Version 0.3.2 July, 31, 1999 Modifications copyright (c) 1999 by Flynt Consulting Services, +#* Modified table support - support for lists in tables +#* beginning of support for nested tables. +#* fixed italics +#* Version 0.3.3 Sep, 29, 1999 +#* +#* Modifications copyright (c) 2000 by Flynt Consulting Services, +#* Modified table support - improved support for nested tables. +#* Changed default font to helvetica +#* Version 0.3.4 April 27, 2000 +#* +#* Modifications copyright (c) 2009 by Robert Heller D/B/A Deepwoods Software +#* Embeded into a Snit Widget Adapter object, using a BWidget Dialog widget, and +#* other 'scenery' to create a full featured help dialog object. +#* Added in *limited* CSS support (sufficient to handle tex4ht's output). +#* +#* Released as part of the Model Railroad System Version 2.1.21 Sept 1, 2009 +#* +#* Version 0.9.0 Oktober 19, 2018 +#* Modifications copyright (c) by Dr. Detlef Groth, Germany - -shtmlview - Basic HTML and Markdown viewer widget - - - - - -
-

shtmlview(n) 1.1.0 shtmlview "Basic HTML and Markdown viewer widget"

-

Name

-

shtmlview - Extended Tcl/Tk text widget with basic support for rendering of HTML and Markdown

-
-

Table Of Contents

- -
-

Synopsis

- -
-

Description

-

The shtmlview::shtmlview package provides a pure Tcl/Tk -widget of the same name to render and display basic HTML and Markdown -files and string.

-

Some history: The widget is based on the htmllib library -developed in the 90ties by Stephen Uhler and Clif Flynt. -In 2009 Robert Heller wrapped this library into the excellent -mega-widget framework snit. -The resulting widget was however tied directly into a help system. -The author of this document first just isolated the display part and -then added some functions such as changing font size and a few buttons -in the toolbar. Then a rudimentary display of data tables was -added. Even later support for inline images and extended keybindings -and Markdown support was added.

-

The widget is not a web browser. It only supports relative -links in the local filesystem. It does not support style -sheets. It does not support http(s) links nor images. -It is thought of as a last fallback to use in cases where no other -possibilities exists to display HTML or Markdown markup from a Tk -application.

-

Use cases are as a help viewer and wherever the developer has control -about the used html tags.

-

Comments and feedbacks are welcome.

-

The shtmlview::shtmlview widget overloads the text widget and -provides new commands and options. -These are explained in the sections WIDGET COMMANDS and -WIDGET OPTIONS.

-

Note that the file "shtmlview.tcl" is not only a package but also -a standalone application for the direct viewing of Markdown and HTML -files. -Invoke it as

-
 tclsh shtmlview.tcl filename.html 
-

in a terminal.

-

The API described in this document is not the whole API offered by the snit -object ::shtmlview::shtmlview. -Instead, it is the subset of that API that is expected not to change in future -versions.

-
-

COMMANDS

-
-
::shtmlview::converter extension description cmdprefix
-

Registers a conversion command prefix (cmdprefix) for files -having the extension. -The description is a short summary of the kind of files expected -to have that extension.

-

The result of the command is the empty string.

-

Whenever an shtmlview widget encounters a file with the specified -extension it will invoke the registered command prefix with one -argument, the path to the file to convert. The result of the -invokation is expected to be the HTML to render and display.

-

See section EXTENSIONS for an example.

-
::shtmlview::shtmlview pathName ?options?
-

Creates and configures the shtmlview widget pathName.

-

The result of the command is the pathName.

-

An error is thrown if a widget for pathName already exists.

-

An error is also thrown if the parent for pathName does not exist.

-

The recognized options are explained in section WIDGET OPTIONS.

-

The methods of the new widget are explained in section WIDGET COMMANDS.

-
-
-

WIDGET OPTIONS

-

Use method helptext to configure the internal text widget.

-
-
-browsecmd cmd
-

Each time a HTML or Markdown page is rendered the specified cmd -command is invoked. The actual URL is appended as first argument to -the command.

-
-closebutton boolean
-

If true (default) a close button is shown in the toolbar. -This is useful if the widget is the sole child of a toplevel widget.

-
-historycombo boolean
-

If true, and the tile package is available, then a -ttk::combobox to show page history is added to the toolbar. -Defaults to false. -Can be only set at widget creation.

-
-home string
-

Sets the homepage filename of the widget. -If not set, the first page browsed to will be automatically set as the -home page.

-
-tablesupport boolean
-

If true (default) some table support is provided. -This will have some undesired results if table tags are misused as -markup tool. -Simple html tables with th and td tags should however -display well if no internal markup inside of those tags is used.

-
-toolbar boolean
-

If true (default) a toolbar will be displayed at the top. -The toolbar will provide standard buttons for the methods back, -forward and home, as well as search facilities. -Defaults to true.

-
-
-

WIDGET COMMANDS

-

Each shtmlview widget created with the above command supports the following -commands and options:

-
-
pathName back
-

Displays the previous HTML and Markdown page in the browsing history -if any.

-
pathName browse filename ?args?
-

Displays the HTML or Markdown text contained in the named file. -Any additional arguments, while also file names, are just added to the -history stack. -They can be walked to using the history keys, f and b.

-
pathName dosearch string direction
-

Search for and highlight the given string starting from the current -index in the specified direction. The direction has to be either -forward (default) or backwards.

-
pathName edittext cmd ?options?
-

This command exposes the internal text editor widget for -configuration. See the following example:

-
-    ::shtmlview::shtmlview .help
-    .help browse index.md
-    .help editView
-    .help edittext configure -background salmon
-
-
-
pathName editView
-

This command switches the widget from viewing to editing. In this -mode the user is able to edit and change the currently loaded file. -To switch to a non-editable source display instead see -sourceView below.

-
-    ::shtmlview::shtmlview .help
-    .help browse index.md
-    .help editView
-
-
-
pathName forward
-

Displays the next HTML or Markdown page in the browsing history if -any.

-
pathName getFiles
-

This command returns a list of all visited files. -Duplicates and anchor links are removed from the raw data.

-
pathName getHistory
-

This command returns a list of the current history of visited files -and anchors.

-
pathName getEditWidget
-

This commands returns the internal pathname of the text editor widget -used for editing the current document. -This enables the developer to directly access it, if required or desired. -This is dangerous. -See also edittext, above.

-
pathName getTextWidget
-

This commands returns the internal pathname of the internal viewer -text widget. -This enables the developer to directly access it, if required or -desired. -This is dangerous. -See also helptext, below.

-
pathName helptext cmd ?options?
-

This command exposes the internal viewer text widget for -configuration. See the following example:

-
-    ::shtmlview::shtmlview .help
-    .help browse index.html
-    .help helptext configure -background yellow
-
-
-
pathName home
-

Displays either the page set by option -home, or the first -page browse was called for.

-
pathName open
-

Uses a standard file open dialog to select a document in any of the -supported formats for display, and then renders that file, if any.

-
pathName reload
-

Reloads and redisplays the currently shown page.

-
pathName render text ?ext?
-

Renders the given text in the viewer. -If an extension ext is specified the string is assumed to be in -the associated format, and the associated converter is used. -Otherwise the string is considered to be either HTML or Markdown. To -be treated as HTML the text has to start with a recognized HTML -tag. In any other case it is considered to be Markdown.

-
pathName sourceView
-

This command switches the widget from viewing the current document -itself to viewing the source of that document. To switch to a editable -source display see editView above.

-
-    ::shtmlview::shtmlview .help
-    .help browse index.md
-    .help sourceView
-
-
-
pathName url
-

Returns the currently shown URL.

-
-
-

BINDINGS FOR THE WIDGET

-

The following keys are bound to the widget for navigation and other -actions:

-
-
<cursor>
-

Standard cursor movement in the view

-
b
-

Back - display previous page in history

-
f
-

Forward - display next page in history

-
p
-

Previous - Move cursor to previous search match

-
n
-

Next - Move cursor to next search match

-
q
-

Remove current page from history. Implies f.

-
r
-

Start search backward

-
s
-

Start search forward

-
Ctrl-E
-

Toggle edit mode

-
Ctrl-s
-

In edit mode, save page

-
Ctrl-r
-

Reload current page

-
Ctrl-u
-

Toggle source vs rendered views

-
Return
-

Follow link under cursor

-
TAB
-

Move cursor to next link on current page

-
-
-

EXAMPLE

-
-    package require shtmlview::shtmlview
-    proc browsed {url} {
-        puts "You browsed $url"
-    }
-    ::shtmlview::shtmlview .help -toolbar true -browsecmd browsed
-    .help browse index.html
-    pack .help -fill both -expand true -side left
+#* Original license terms:
+#*
+#* Sun Microsystems, Inc.  The following terms apply to all files
+#* a ssociated with the software unless explicitly disclaimed in individual
+#* files.
+#*
+#* The authors hereby grant permission to use, copy, modify, distribute,
+#* and license this software and its documentation for any purpose, provided
+#* that existing copyright notices are retained in all copies and that this
+#* notice is included verbatim in any distributions. No written agreement,
+#* license, or royalty fee is required for any of the authorized uses.
+#* Modifications to this software may be copyrighted by their authors
+#* and need not follow the licensing terms described here, provided that
+#* the new terms are clearly indicated on the first page of each file where
+#* they apply.
+#*
+#* IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY PARTY
+#* FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
+#* ARISING OUT OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY
+#* DERIVATIVES THEREOF, EVEN IF THE AUTHORS HAVE BEEN ADVISED OF THE
+#* POSSIBILITY OF SUCH DAMAGE.
+#*
+#* THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES,
+#* INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY,
+#* FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT.  THIS SOFTWARE
+#* IS PROVIDED ON AN "AS IS" BASIS, AND THE AUTHORS AND DISTRIBUTORS HAVE
+#* NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR
+#* MODIFICATIONS.
+#*
+#* RESTRICTED RIGHTS: Use, duplication or disclosure by the government
+#* is subject to the restrictions as set forth in subparagraph (c) (1) (ii)
+#* of the Rights in Technical Data and Computer Software Clause as DFARS
+#* 252.227-7013 and FAR 52.227-19.
+
+
+if {[info exists argv0] && [lindex $argv 0] eq [info script]} {
+    lappend auto_path [file join [file dirname [info script]] .. libs]
+}
+
+package require Tcl 8.5
+package require Tk
+package require snit
+
+package provide shtmlview::shtmlview 1.1.0
+
+# Optional packages supporting various features (jpeg images, tile/themes)
+# Markdown support - See bottom
+catch { package require img::jpeg }
+catch { package require tile      }
+
+if {[info command luniq] eq ""} {
+    proc luniq list {
+        set res {}
+        foreach i $list {
+            if {[lsearch $res $i]<0} {lappend res $i}
+        }
+        set res
+    }
+}
+
+namespace eval ::shtmlview {}
+
+## Customizable download procedure.
+# The "progress" argument is the name of the function that is called to show download progress, see http package.
+proc ::shtmlview::download {url {progress ""}} {
+    return [::meshparts::DownloadFile $url $progress]
+}
+## Initialization procedure needed to handle https URLs
+proc ::shtmlview::tlsinit {args} {
+  package require http
+  package require twapi
+  package require autoproxy
+
+  catch {::http::unregister https}
+
+  # Use twapi (CA file is not needed)
+  set code [catch {set tlssocket [http::register https 443 twapi::tls_socket]} err]
+  if {$code} {
+    set tlssocket ""
+  }
+}
+# API: Register a format converter
+proc ::shtmlview::converter {extension description command} {
+    variable filetypes
+    variable converter
+
+    lappend filetypes [list $description $extension]
+    set converter($extension) $command
+    return
+}
+
+# Internal: Check presence of a converter for the extension
+proc ::shtmlview::HasConverter {ext} {
+    variable converter
+    return [info exists converter($ext)]
+}
+
+# Internal: Invoke converter for file
+proc ::shtmlview::Convert {url {clean true}} {
+    variable converter
+    set ext [string tolower [file extension [TrimAnchor $url]]]
+
+    if {![info exists converter($ext)]} {
+    return -code error "Unable to convert $ext"
+    }
+
+    set cmd $converter($ext)
+    lappend cmd $url
+
+    set html [uplevel #0 $cmd]
+
+    if {$clean} {
+    set html [shtmlview::cleanHTML $html]
+    }
+
+    return $html
+}
+
+# Internal: Sensibly name a common internal operation.
+proc ::shtmlview::TrimAnchor {url} {
+    return [regsub "#.*" $url {}]
+}
+
+proc ::shtmlview::md2html {url} {
+    if {[info commands ::Markdown::convert] eq ""} {
+        catch { package require Markdown }
+        if {[info commands ::Markdown::convert] eq ""} {
+            error "package Markdown can't be loaded!"
+        }
+    }
+    if [catch {open $url r} infh] {
+        error "Cannot open $url: $infh"
+    } else {
+        set md ""
+        while {[gets $infh line] >= 0} {
+            set line [regsub {!\[\]\((.+?)\)} $line "!\[ \](\\1)"]
+            append md "$line\n"
+        }
+        close $infh
+    }
+    return [Markdown::convert $md]
+}
+
+namespace eval ::shtmlview {
+    variable filetypes [list]
+    # Robert Heller: It uses code originally written by Stephen Uhler and
+    # modified by Clif Flynt (htmllib 0.3 through 0.3.4). I have modified it
+    # further and embedded into a snit widget adapter object to create a full
+    # featured help dialog object.  I also added limited support for cascading
+    # style sheets.
+    #
+    # @author Stephen Uhler \,
+    #     Clif Flynt \,
+    #        Robert Heller \,
+    #        and Detlef Groth \.
+    #
+    catch {
+        bind all  \
+              {event generate [focus -displayof %W]  -delta  120}
+
+        bind all  \
+              {event generate [focus -displayof %W]  -delta -120}
+        bind HelpText  {
+            %W yview scroll [expr {- (%D)}] units
+        }
+    }
+    bind HelpText <1> {
+        tk::TextButton1 %W %x %y
+        %W tag remove sel 0.0 end
+    }
+    bind HelpText  {
+        set tk::Priv(x) %x
+        set tk::Priv(y) %y
+        tk::TextSelectTo %W %x %y
+    }
+    bind HelpText  {
+        set tk::Priv(selectMode) word
+        tk::TextSelectTo %W %x %y
+        catch {%W mark set insert sel.first}
+    }
+    bind HelpText  {
+        set tk::Priv(selectMode) line
+        tk::TextSelectTo %W %x %y
+        catch {%W mark set insert sel.first}
+    }
+    bind HelpText  {
+        tk::TextResetAnchor %W @%x,%y
+        set tk::Priv(selectMode) char
+        tk::TextSelectTo %W %x %y
+    }
+    bind HelpText   {
+        set tk::Priv(selectMode) word
+        tk::TextSelectTo %W %x %y
+    }
+    bind HelpText   {
+        set tk::Priv(selectMode) line
+        tk::TextSelectTo %W %x %y
+    }
+    bind HelpText  {
+        set tk::Priv(x) %x
+        set tk::Priv(y) %y
+        tk::TextAutoScan %W
+    }
+    bind HelpText  {
+        tk::CancelRepeat
+    }
+    bind HelpText  {
+        tk::CancelRepeat
+    }
+    bind HelpText  {
+        %W mark set insert @%x,%y
+    }
+    bind HelpText  {
+        tk::TextSetCursor %W insert-1c
+    }
+    bind HelpText  {
+        tk::TextSetCursor %W insert+1c
+    }
+    bind HelpText  {
+        tk::TextSetCursor %W [tk::TextUpDownLine %W -1]
+    }
+    bind HelpText  {
+        tk::TextSetCursor %W [tk::TextUpDownLine %W 1]
+    }
+    bind HelpText  {
+        tk::TextKeySelect %W [%W index {insert - 1c}]
+    }
+    bind HelpText  {
+        tk::TextKeySelect %W [%W index {insert + 1c}]
+    }
+    bind HelpText  {
+        tk::TextKeySelect %W [tk::TextUpDownLine %W -1]
+    }
+    bind HelpText  {
+        tk::TextKeySelect %W [tk::TextUpDownLine %W 1]
+    }
+    bind HelpText  {
+        tk::TextSetCursor %W [tk::TextPrevPos %W insert tcl_startOfPreviousWord]
+    }
+    bind HelpText  {
+        tk::TextSetCursor %W [tk::TextNextWord %W insert]
+    }
+    bind HelpText  {
+        tk::TextSetCursor %W [tk::TextPrevPara %W insert]
+    }
+    bind HelpText  {
+        tk::TextSetCursor %W [tk::TextNextPara %W insert]
+    }
+    bind HelpText  {
+        tk::TextKeySelect %W [tk::TextPrevPos %W insert tcl_startOfPreviousWord]
+    }
+    bind HelpText  {
+        tk::TextKeySelect %W [tk::TextNextWord %W insert]
+    }
+    bind HelpText  {
+        tk::TextKeySelect %W [tk::TextPrevPara %W insert]
+    }
+    bind HelpText  {
+        tk::TextKeySelect %W [tk::TextNextPara %W insert]
+    }
+    bind HelpText  {
+        tk::TextSetCursor %W [tk::TextScrollPages %W -1]
+    }
+    bind HelpText  {
+        tk::TextSetCursor %W [tk::TextScrollPages %W +1]
+    }
+    bind HelpText  {
+        tk::TextKeySelect %W [tk::TextScrollPages %W -1]
+    }
+    bind HelpText  {
+        tk::TextSetCursor %W [tk::TextScrollPages %W 1]
+    }
+    bind HelpText  {
+        tk::TextKeySelect %W [tk::TextScrollPages %W 1]
+    }
+    bind HelpText  {
+        %W xview scroll -1 page
+    }
+    bind HelpText  {
+        %W xview scroll 1 page
+    }
+
+    bind HelpText  {
+        tk::TextSetCursor %W {insert linestart}
+    }
+    bind HelpText  {
+        tk::TextKeySelect %W {insert linestart}
+    }
+    bind HelpText  {
+        tk::TextSetCursor %W {insert lineend}
+    }
+    bind HelpText  {
+        tk::TextKeySelect %W {insert lineend}
+    }
+    bind HelpText  {
+        tk::TextSetCursor %W 1.0
+    }
+    bind HelpText  {
+        tk::TextKeySelect %W 1.0
+    }
+    bind HelpText  {
+        tk::TextSetCursor %W {end - 1 char}
+    }
+    bind HelpText  {
+        tk::TextKeySelect %W {end - 1 char}
+    }
+    bind HelpText  {
+        %W mark set anchor insert
+    }
+    bind HelpText