HTMS - HyperText Markup Shorthand

Purpose

A Tcl module for HTML + CSS markup shorthand.

The htms module converts a script written in HTMS into HTML.

HTMS reduces the effort needed to create HTML. The number of
keystrokes needed for HTMS markup is typically from one tenth to
one half that needed for the equivalent HTML markup.

Shorthand

Basically the shorthand forms are Tcl commands. Each shorthand
form is an HTML element name that may be followed by a dot and
any number of dot-separated HTML attributes or CSS properties.
Because this is Tcl, the command has to be a single "word", and
the usual Tcl quoting and escape mechanisms apply. The command's
arguments are made the content of the corresponding HTML element.

Next steps:

• read the examples to learn the shorthand notation
• read the glossary to learn our terminology
• read on to learn about included-, excluded-, and
  deferred-features.

Features included

This module is probably near its Pareto optimality and already
includes the most useful and appreciated features.

• Shorthand for elements. Normal, void and user-defined
  elements are supported.
• Shorthand for entities. Symbol, decimal, hexadecimal
  and user-defined entities are supported.
• Futureproofing. To avoid breaking when HTML changes,
  this module knows very little HTML beyond its syntax.
  What can break:
  • an HTML normal element gets a Tcl command name
    If this happens, you will have to add a dot to the end
    of the element name. Currently (HTML5) this only
    happens with the source element, but as good luck
    would have it, source is a void element that requires
    attributes to be meaningful—so it will always have
    a dot or can be omitted altogether.
  • an HTML void element gets a Tcl command name
    If this happens, you will have to add a slash to the
    element name. In HTML5 this does not happen.
  • an HTML void element is added If this happens,
    submit a change request, or add it yourself to
    void_elements—see below.
• Open for low-level extension. Behavior will reflect
  changes to these internal variables:
  • cite_elements is a list of HTML elements that take a
    cite attribute (blockquote, del, ins, q). It is used to turn
    [q#I#url hello, world] into
     <q id='I' cite='url'>hello, world</q>
  • edict is a dictionary that maps a partial superset of
    HTML entity names to text. It is used to turn
    [&-nbhy] into &#x2011;
    Note: the leading hyphen in -nbhy shows that
    the entity is not standard, and likely never will be.
  • href_elements is a list of HTML elements that take an
    href attribute (a, area, base, link). It is used to turn
    [a#me#url link] into
     <a id='me' href='url'>link</a>
  • src_elements is a list of HTML elements that take a
    src attribute (img, script, source, ...). It is used to turn
    [img#myself#url] into
    <img id='myself' src='url'/>
  • void_elements is a list of HTML void elements
    (br, img, ...).
    It is used to turn [br] into <br/>
• Open for high-level extension. On encountering an
  unknown element, HTMS will look for a mapping from the
  lowercase version of the name to a proc in:
  • user_elements is a map of lowercase element names
    to proc names. The names should not be syntactically
    valid HTML (or XHTML) element names, nor should
    they be likely Tcl command names.
• Do-it-yourself (DIY) heavy-duty futureproofing.
  Steps an author can take to be even more futureproof:
  • put a dot after normal element names, e.g.,
    [h1. Main Title] — not [h1 Main Title]
  • put a slash after void-element names, e.g.,
    [br/] — not [br]
  • use a special character in DIY entity names
    to avoid the HTML namespace ("special" meaning
    non-colon, non-alphanumeric), e.g.:
  • superscripts, à la TeX, with ^
    like x[&^n] for xⁿ
  • subscripts, à la TeX, with _
    like y[&_n] for yₙ
  • and all the rest with -
    like b[&-nbhy]n[&-nbhy]b for b-n-b
• Do-it-yourself XHTML notation. Since HTMS already
  always quotes attribute values, and because it accepts
  attribute names containing colons, there are only a few
  conditions you will have to monitor.
  • void- and empty- elements must be distinguished.
    Although HTML will tolerate empty elements for
    void elements, XHTML will not.
  • empty attributes are invalid in XHTML.
    foo.bar= yields <foo bar='bar'>
    foo.bar="" yields <foo bar=''>
    foo.bar yields <foo bar>

Features excluded

In striving to "do one thing and do it well", some functions
have been rejected.

• HTML validation. No attempt is made to guarantee that
  a document created from a shorthand description is valid.
  Arguably, validation is incompatible with futureproofing.
  • No validation of element hierarchy / nesting.
  • No validation of element names.
  • Attribute names with colons.
• XHTML validation. HTML and XHTML are syntactically
  incompatible. It is however possible to write shorthand
  that produces valid XHTML.

Features deferred

Through indecisiveness, resouce limitation, or laziness, not
all features considered have been implemented or rejected.

• Support for Scalable Vector Graphics.

Repository content

This repository is limited to the htms package/module. HTMS is
used in the Siemens Presentation Markup Compiler.

Toplevel directories

• cmd  command-line commands, some of which we write
• doc  documentation we write
• lib  library of code we depend on
• pub  publications we release
• ref  reference material, documentation others wrote
• src  code that we write
• tst  tcltest support

Unversioned directories

• skip reserved for unversioned artefacts
• temp reserved for unversioned temporaries

Environment

• Bash Basis/Bias. Project development, test, and analysis
  is done in a Unix-like environment—Git was installed
  in a Windows work setting, and now real work is done in
  GitBash shells.
• .bashrc provided to set path variables, etc.
  • .bash_aliases provided for convenience
  • this glob matches reserved file names: .bash*
• Emacs Friendly. You can use Emacs—you don't have to.
  • these globs match reserved file names:
    .emacs.* TAGS* .#* #*#

Licenses

This is an open source software project. Contributers agree to
the Developer Certificate of Origin, but commits are not signed.
As per the REUSE Specification, the licenses are in the
LICENSES directory.

Rationale for release as open source

Beyond the generic, altruistic, and progressive arguments
for Open Source Software, there are a number of reasons to
expect specific benefits beyond goodwill by releasing this
code. Direct and indirect benefits will accrue from users
in the Tcl community, at external suppliers and non-wholly
owned subsidiaries. Feedback and contributions provided by
downstream users will further ripen and improve this code.
If the resonance this code experienced at EuroTcl 2019 is
any indication, there is reason to believe the payoffs will
be greater than expected.

Furthermore, there is little reason to expect detrimental
after-effects from a release.