tcl-quill 0.3.0: Quill Project Automation System for Tcl/Tk

macroset_html(n): HTML Tag Macro Set -- macro(n)

SYNOPSIS
DESCRIPTION
MACROS
Basic HTML Tags
Definition List Macros
Topic List Macros
Annotated Listings and Examples
Miscellaneous Convenience Macros
AUTHOR
SEE ALSO

SYNOPSIS

package require quill 0.3.0
macro macroset ::quill::macroset_html
<li>...</li>
<ol>...</ol>
<p>...</p>
<ul>...</ul>
<b>...</b> or <b text...>
<code>...</code> or <code text...>
<em>...</em> or <em text...>
<i>...</i> or <i text...>
<pre>...</pre> or <pre text...>
<strong>...</strong> or <strong text...>
<tt>...</tt> or <tt text...>
<deflist args...>...</deflist args...>
<def text>
<topiclist>...</topiclist>
<topic topic>...</topic>
<box>...</box>
<example>...</example>
<listing>...</listing>
<mark symbol>
<bigmark symbol>
<hrule>
<lb>
<link url ?text?>
<rb>

DESCRIPTION

The ::quill::macroset_html macro set defines a collection of macros corresponding to basic HTML tags, for use in document formats that mimic HTML. It can be registered with an instance of macro(n) using the macroset command.

MACROS

::quill::macroset_html defines the following macros:

Basic HTML Tags

<li>...</li>
<ol>...</ol>
<p>...</p>
<ul>...</ul>
These macros map directly to their HTML namesakes.

<b>...</b> or <b text...>
<code>...</code> or <code text...>
<em>...</em> or <em text...>
<i>...</i> or <i text...>
<pre>...</pre> or <pre text...>
<strong>...</strong> or <strong text...>
<tt>...</tt> or <tt text...>
These style tags have two forms, an HTML-like form and a convenience form. For example,

<i this is italics>
is identical to

<i>this is italics</i>
Note that when convenience form is used, the text... may not contain nested macros. For example, the following will not yield bold italic text:

<b "<i this is not bold italics>">

Definition List Macros

Definition lists are the primary means of documenting a list of items. The items to be defined are displayed in boldface, and the definitions or descriptions of the items appear below them, indented. Definition lists are useful when the terms to be defined are wide.

The following macros are used to define definition lists.

<deflist args...>...</deflist args...>
These tags contain a definition list. The args are ignored. By convention, each <deflist> tag includes arguments which indicate the kind of thing being listed; the </deflist> tag echoes them. This avoids confusion when definition lists are nested. For example,

This application has the following features:<p>

<deflist features>
...
</deflist features>

Items are defined within a definition list using <def>.

<def text>
Begins the documentation of an item in a definition list. The text may contain macros for expansion.

The following features are of interest:<p>

<deflist features>
...
<def {My <i first> Feature.}>
...
<def {My <i second> Feature.}>
</deflist features>

This yields output like this:

My first Feature.
All about my first feature.

My second Feature.
All about my second feature.

Topic List Macros

Topic lists are the secondary means of documenting a list of items. The topics to be defined and their descriptions are displayed in parallel columns, with the topics in boldface. Topic lists are useful when the topic text is narrow (as when <bigmark>'s are used as topics), and when documenting record structures.

The following macros are used to define topic lists.

<topiclist>...</topiclist>
Contains a topic list. Items are defined within a topic list using <topic>...</topic>.

<topic topic>...</topic>
Specifies a complete topic entry in a <topiclist>. The topic is used on the left, and the text between the start and end tags appears on the right. The topic may contain macros to be expanded.

For example, here's a topic list with text topics:

<topiclist>
<topic "Topic&nbsp;1:">
...Text elaborating on the topic...
</topic>

<topic "Topic&nbsp;2:">
...Text elaborating on the topic...
</topic>
</topiclist>
Note the use of non-breaking spaces to present word-wrapping. The output looks like this:

Topic 1: Lorem ipsum dolor sit amet, consectetur adipiscing elit. Quisque consectetur sollicitudin dolor, et blandit nisl iaculis quis. Donec eu urna nec augue vulputate tempor ut eu diam. Proin quam sapien, vehicula id pellentesque sed, iaculis vitae nunc. Aliquam venenatis suscipit sapien id faucibus.
Topic 2: Lorem ipsum dolor sit amet, consectetur adipiscing elit. Quisque consectetur sollicitudin dolor, et blandit nisl iaculis quis. Donec eu urna nec augue vulputate tempor ut eu diam. Proin quam sapien, vehicula id pellentesque sed, iaculis vitae nunc. Aliquam venenatis suscipit sapien id faucibus.

And here's a topic list using <bigmark>'s, presumably annotating a <listing>:

<topiclist>
<topic "<bigmark A>">
...Text annotating mark A...
</topic>

<topic "<bigmark B>">
...Text annotating mark B...
</topic>
</topiclist>

A
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Quisque consectetur sollicitudin dolor, et blandit nisl iaculis quis. Donec eu urna nec augue vulputate tempor ut eu diam. Proin quam sapien, vehicula id pellentesque sed, iaculis vitae nunc. Aliquam venenatis suscipit sapien id faucibus.
B
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Quisque consectetur sollicitudin dolor, et blandit nisl iaculis quis. Donec eu urna nec augue vulputate tempor ut eu diam. Proin quam sapien, vehicula id pellentesque sed, iaculis vitae nunc. Aliquam venenatis suscipit sapien id faucibus.

The topic list macros make use of the following CSS classes:

It is up to the client to define appropriate CSS settings; these make reasonable defaults:

/* Topic List Styles */
tr.topicrow  { vertical-align: baseline; }
td.topicname { font-weight:    bold;     }

Annotated Listings and Examples

The following macros create annotated examples and source code listings.

An example is a set of preformatted text, contained within <example> and </example> macros, to be displayed in a box with a distinctive background.

A source code listing is similar in appearance to an example, but adds line numbers on the left margin. It is contained within <listing> and </listing> macros.

Authors can add annotation marks to either kind of listing using <mark>. The annotations are typically documented by following the listing by a <topiclist> with matching <bigmark>'s as the topic names.

<box>...</box>
Wraps arbitrary text in a box with a light-blue background. This man page uses these macros for the output examples.

<example>...</example>
Put preformatted text data between the tags. It will displayed in a box with a distinctive background. Insert <mark> annotation markers as desired to denote points of interest.

<listing>...</listing>
Put preformatted source code (or other text data) between the tags. It will displayed as an example, but with line numbers. Insert <mark> annotation markers as desired to denote points of interest.

<mark symbol>
Adds an annotation mark to a listing (or anywhere, really). An annotation mark displays the symbol (usually a capital letter) in white text on a rounded black rectangle. The mark is small enough note to increase the line height.

<bigmark symbol>
Adds a big annotation mark. <bigmark>'s look just like normal <mark>'s, but are somewhat bigger. They are primarily useful as <topic>'s in a <topiclist>.

For example, a listing with marks is entered like this:

<listing>
proc ::quill::ladd {listvar args} { <mark A>
    upvar 1 $listvar theList <mark B>

    foreach value $args {
        if {$value ni $theList} {
            lappend theList $value <mark C>
        }
    }

    return $theList
}
</listing>

And displays like this:

0001 proc ::quill::ladd {listvar args} { 
A
0002 upvar 1 $listvar theList
B
0003 0004 foreach value $args { 0005 if {$value ni $theList} { 0006 lappend theList $value
C
0007 } 0008 } 0009 0010 return $theList 0011 }

These macros depend on the following CSS classes:

div.box Defines the border and background for <box>.
pre.example Defines the border and background for <example>.
pre.listing Defines the border and background for <listing>.
pre.linenum Defines the background for line numbers in a <listing>.
div.mark Defines the appearance of a <mark>.
div.bigmark Defines the appearance of a <bigmark>.

It is up to the client to define reasonable CSS settings; these are reasonable defaults:

div.box {
    border: 1px solid blue;
    background-color: #DEF4FA;
    padding: 2px;
}

pre.example {
    border: 1px solid blue;
    background-color: #FAF5D2;
    padding: 2px;
}

pre.listing {
    border: 1px solid blue;
    background-color: #FAF5D2;
    padding: 2px;
}

span.linenum {
    background-color: #DEDC87;
}

div.mark {
    font-family: Verdana;
    font-size: 75%;
    border: 1px solid black;
    background-color: black;
    color: white;
    border-radius: 10px;
    padding-left: 2px;
    padding-right: 2px;
    display: inline;
}

div.bigmark {
    font-family: Verdana;
    font-size: 100%;
    border: 1px solid black;
    background-color: black;
    color: white;
    border-radius: 10px;
    padding-left: 2px;
    padding-right: 2px;
    display: inline;
}

Miscellaneous Convenience Macros

<hrule>
Adds a horizontal rule across the width of the document.

<lb>
Returns the left macro expansion bracket, "<".

<link url ?text?>
Returns a link to the given url. If text is given, it is used as the link text; otherwise, the url is displayed.

<rb>
Returns the right macro expansion bracket, ">".

AUTHOR

Will Duquette

SEE ALSO

macro(n).
Generated from macroset_html.manpage on Sat Nov 08 09:38:04 PST 2014