<NB>
</NB>
If you know Markdown, HML is like that on steroids—vastly more capable and, unlike Markdown, easily customizable.
HML converts simple marked-up input into complex HTML output that:
HML excels at displaying code. It properly formats example code in the text and makes it easy to write about the code, even when you actively change that code. HML can pull listings from outside the document, assign line numbers, and reference declarations, etc., symbolically—just as with section numbers. When the code changes, line-number references (in both listing and body text) re-point automatically to the new location. When you change code, the document changes dynamically to reflect the new version. You can modify existing code, add new listings, move listings around, and all references in the document automatically adjust. All references to particular listings, tables, sections, and line numbers in a listing, are hyperlinks: click on a reference to navigate to the referenced item.
HML is well tested, and has evolved through heavy use by its original author, Allen Holub, who wrote all of Holub on Patterns and Taming Java Threads using HML, as well as dozens of online-magazine articles for venues like DDJ. This document is written in HML, which is actually something of a worst case. The HML processor is written in Java, so it's fully portable across all platforms.
HML outputs a single .html file, with no external dependencies, so you can save it locally,
e-mail it, or view it offline.
Part I: Core Features
1. HML vs. HTML
HML documents require no HTML. Nonetheless, HML and HTML coexist nicely in the same document, and documents of any complexity typically use a little of both. HML enhances, not replaces, HTML.
Similarly, HML provides all the CSS styling a nice-looking document needs. However, it's easy to add custom CSS and change the built-in CSS—for all HML documents, or for a single document.
The only issue with HML in the cloud is pulling in listings, because the cloud version has no direct access to your local hard drive. The solution is to use Dropbox. The Section 24.2 explains how to do that.
Dropbox creates a folder on the local hard drive (called Dropbox). Dropbox instantly, copies any file you put in that folder or its subfolders to a private cloud-based mirror of the local Dropbox folder. HML in the cloud can pull files from the cloud-based Dropbox mirror instead of the local hard disk.
Macs come with Java as part of the OSX install. This version works just fine, but you can download a newer version from Oracle. (See here, and here for directions).
Finally, download the HML processor from
https://raw.github.com/aholub/hml/master/Hml/hml.jar
The download is a standalone (.jar) file you can put anywhere.
There's no need to unpack or otherwise “install” it.
Similarly, the HML processor doesn't use any magic folders (e.g. "~/Library"
on the mac) or the Windows registry. To remove it from your disk, just
delete hml.jar.
3.1. Running the HML processor locally
To execute the HML processor, you actually execute java and tell java to run the processor, all from a Mac terminal window or a Windows console window.
> java -jar /my/path/to/hml.jar myInputFile.hml > myOutputFile.html
You can also redirect input into the processor, which is occasionally handy if you're running HML as part of a processing chain:
> myCustomProcessor myInput | java -jar /my/path/to/hml.jar > myOutputFile.html
The HML processor breaks the source document into three types of input and handles each differently:
`like this`
)
like this

<listing>
HML recognizes three styles of comments.
{
[

which displays as my web site. The URL comes first, followed by the link's visible text. If you don't specify visible text, HML displays the URL.[http://www.holub.com my web site]
| Input | Displays as | Comment |
|---|---|---|
{link http://www.holub.com} {link www.holub.com} [www.holub.com] [http://www.holub.com] <http://www.holub.com> {link www.holub.com } [www.holub.com ] |
http://www.holub.com www.holub.com www.holub.com http://www.holub.com www.holub.com some text other text | A hyperlink. If you don't specify visible text, the processor uses the URL.
In the multiple-argument form, the text to the right of the href is the visible text of the link.
An http:// http://
The
A |
{anchor foo} | Creates an "empty" (invisible) anchor that indicates a target for a link. The example at left evaluates to  [#foo] [#foo visible text] # [#foo go to foo] |
{i text}
_text_
Note that the HML processor treats backquote-delimited code snippets
(Section 9)
differently than
the other emphasis mechanisms.
Unlike {c xxx}
&
<
>
&
<
>
"
'
{c xxx}
{c xxx}
<nobr>
</nobr>
You can put a literal back-tick in code by "escaping" it with a backslash:
\`not code\`
prints as `not code`.
Put a backtick in a code block by escaping it the same way.
HML has no backquote equivalents to {cb x}
{ci x}
{b `code`}
code
| Input | Displays as | Comment |
|---|---|---|
{b bold} *text* | bold text | Asterisks indicate boldface text
(e.g.,*this is boldface* {b this is boldface} xxx{b bold}xxx
Text in the * form of the macro must be entirely on one line.
The brace version can span several lines.
A |
{i italic} _text_ | italic text |
Same rules as *bold* \_ _ |
{bi bold italic } | bold italic | |
{u underline text} | underline text | |
{s strikeout text} | strikeout text | Uses styles, not  tag. |
{x style text} | (depends on the style) | Puts the text into a  span.style |
{c code & text} | code & text
| Just wraps the contents in a  |
{ci italic code} | italic code | |
{cb bold code} | bold code |
The brace forms in Table 8.2 do not nest---{i {b text}}
_*bold italic*_ *_bold italic_* _italic *bold* more italic_ *bold _italic_ more bold* {b bold _italic_} {i italic *bold*}
bold italic
bold italic
italic bold more italic
bold italic more bold
bold italic
italic bold
`code`
)
A code snippet is a bit of in-line code that appears in the middle of your text like this
`if(a<b)`
if(a<b)
The HML processor puts the entire snippet on a single line (by replacing space characters with
<nobr>...</nobr>
All punctuation in the code snippet (everthing except an alphanumeric character space or tab) is mapped to an HTML entity. For example:
| input | maps to |
< | < |
> | > |
& | & |
{ | { |
| etc. |
This is a much more severe mapping than you'll find in Markdown, which maps only <, >, ', ", and &. The more comprehensive mapping is necessary because HML's powerful macro feature can use pretty much any character as a macro key (the text that's replaced by the macro processor). Code snippets are processed before macros are expanded, so this mapping-all-punctuation-to-entities rule effectively prevents macros from being expanded in code snippets. You'll find that all the predefined macros include some sort of punctuation in their key. Follow the same convention if you define your own macros.
All tab characters in code snippets are expanded as four-space tabs, but the processor treats the opening backquote as the first character on the virtual "line". This behavior is relevant only if you're using code snippets to put leading whitespace on a line, and might use both tabs and spaces at the start of the line. For example:
<block> ` <- line starts with tab` ` <- line starts with three (!) spaces, but lines up with the tabbed line, above.` </block>
<- line starts with tab
<- line starts with three (!) spaces, but lines up with the tabbed line, above.
,
The easiest way to put a short full-line code sample in your text is to prefix the code lines with a comma. For example:
is treated identically to, someCode();
, someMoreCode().
and displays as

someCode();
someMoreCode();

someCode(); someMoreCode();

displays as, <-- 1 tab
, <-- 2 tabs
, <-- 3 tabs
<-- 1 tab <-- 2 tabs <-- 3 tabs
displays like this:

Some text

code();

Some textThe
code();
code()
It displays as

Some text
, code();
More text

Some textwithout the extra space to the left ofMore text.
code();
code()
HML provides more sophisticated in code-handling mechanisms (see Section 23).
In fact, the easy-code-block mechanism we just looked at is just an alias for the more elaborate

11. Headings (MediaWiki-Style)
The easiest ways to put headings into your document is to use equal signs:
| = text | maps to | <h0> </h0> | Works just like an HTML
 |
| =/ text | maps to |

 | Headings at this level and all inner levels have section numbers
added automatically (see Section 20)).
Headings in the current document were created using
=/ |
| == text | maps to |

 | (==/ works too, but / is unnecessary). |
| === text | maps to |

 | (===/ works too, but / is unnecessary). |
| ==== text | maps to |

 | (====/ works too, but / is unnecessary). |
| ===== text | maps to |

 | (=====/ works too, but / is unnecessary). |
| ====== text | maps to |

 | (======/ works too, but / is unnecessary). |
The default (no slash) makes HTML-style titles, exactly like MediaWiki.
The slash form enables section numbering—for not only that level, but also for all nested levels. All the outermost headings in the current document were specified with the slash form. The HML processor automatically assigns the numbers.
HML handles heading numbering and renumbering.
If you change the heading structure—add or remove one, for example,
or move the section—the {section mwheadings}
{section mwheadings}
You can use a slash for inner heading levels (e.g.,==/ title
Close the heading if you like
(e.g.,== heading ==
== My heading == label
=/ Headings (MediaWiki-Style) == mwheadings
mwheadings
{section mwheadings}
{section-number
}
{section-number mwheadings}
[#mwheadings MediaWiki-style headings section].
in the MediaWiki-style headings section.The leading
#
As was the case with the "easy" code blocks, the heading mechanism discussed in the current section is
a simplification of a more-elaborate system (described in Section 20) that handles the majority of
situations.
In fact, the heading mechanism described in the current section is implemented by a set of pre-defined macros
(see Section 19.2) that map to their more complicated variants.
12.
Works like <block>...</block>

All attributes in a <block>
class=
style=

class=
Block elements do not nest, so don't be tempted to do the following—it just won't work.
<block>
//...
← Error! Nesting not permitted. <block>
//...
</block>
</block>
Use HTML

13. Lists
You may use standard

Text above bullets * first item * second item * third item is three lines long Text below bullets Text above numbers 0. first 0. second line 0. third Text below numbers Text above numbers # first # second line # third Text below numbers
Text above bulletsText below bullets
- first item
- second item
- third item is three lines long
Text above numbers
Text below numbers
- first
- second line
- third
Text above numbers
Text below numbers
- first
- second line
- third
An asterisk introduces an item in a bullet list.
The asterisk must be the first character on the line (no space or tab characters to the left).
Within a list, indented lines are effectively merged with the previous line.
That is, any indented lines that follow one that starts with a *
#
A blank line terminates the whole list, so blank lines can't separate list items. However, HML removes comment lines entirely before it processes lists, so you can visually separate list items like this:
* first // * second // * third
9. first 1. second line 7. third
; term 1 : definition of term 1. ; term 2 : definition of term 2, and more. : another definition of term 2.

# numbered-list element
#* bullet list in numbered list

<listing>
,
ends up displaying like this:# item 1

some code.

# item 2
some code.

<block>
# item 1
<block>
`some code.`
</block>
# item 2
which displays like this:
some code.
|
\|
|
[
(] ... [
|] ... [
)]
Create a simple table like this:
| A | B | C
|- 3
| first | second | third
| doo | wha | ditty
| hickory
| dickory
| dock
and more dock.
Which displays as follows
| A | B | C |
| first | second | third |
| doo | wha | ditty |
| hickory | dickory | dock and more dock. |
A '
HML replaces a row that starts with |-
N
with a horizontal line.
The number (3 in the earlier example)
is the width of the line in columns, and it's required.
Terminate the table with a blank line.
This mechanism is really for columnar data, but you can style the underlying table using CSS. A minor issue with the earlier examples might come into play if you do restyle, however. If the table cells have borders, you should put a terminating
| a | b | c | | A | | C | | x | y | |
The earlier examples left out that rightmost |
15. End notes (
<note>
<endnotes>
HML supports linked end notes. The note is typically moved to the end of the document, and a reference is placed at the end of the sentence.1 The note at the end of the previous sentence was generated by the following markup:
…notes.By default, the note pops up in a small box when the cursor hovers over the reference, but you can change that behavior if you like (Section 28.4). The numbers are generated automatically, and increment with each use.2 The<note>Here's the note.</note>
<note>
some text. <note> The note goes here. </note>
You'll note (so to speak) that the note reference is a link to the actual end note, which is at the end of the document. You can't click on it because the popup obscures it, but if you remove the popup, clicking on the note mark gets you to the note. Once you get there, clicking on the reference next to the actual note gets you back to your original location. The note mark is underlined to highlight the fact that it's a link, but that underline doesn't appear in the printed version of the document.
The only restriction with the note text is that it can't contain a code block. That is, you can't say:
<note>
 someCode();
 </note>
<note> , someCode(); </note>
<note> <block> `someCode()` </block> </note>
…want to.HML macros can be used for callouts, as I've done here with<note mark="[dagger]">This is a note with a non-numeric callout.</note>
[dagger]
<note mark="\*">
You can restart the numbering to an arbitrary number by using a mark=
<note...>
…at 10:Thereafter, numbering continues from whatever number you assign manually, so the next note is 11. If you need to reference a note in more than one place, you can use… <note
mark="10">This is note number 10.</note>
to give the note a label, and then link to the note text using one of:… <note label="myLabel"
>
For example, the full annotation for note 10, above, was actually:{note myLabel}
{note-number myLabel}
and<note
label="note10"
mark="10">
displays as{note note10}
{note-number note10}
Note 10
10
One final minor, but useful feature. The prefix="
"
suffix="
"
suffix=", "
Surround the note with brackets[13]
with <note prefix="\[" suffix="\]">
If you want to use brackets throughout the document, the easiest solution is to create a macro (see Section 22):
<macro> '<n>'<note prefix="\\[" suffix="\\]">' '</n>'</note>' </macro> text<n>The reference to this note has brackets.</n>
text[14]Use double backslashes in the macro definition to get the macro to expand to a single backslash.
<endnotes>
<endnotes> = Notes = notes </endnotes>
The contents of the <endnotes>
= Notes
=
Any and all HML markup can be used within the <endnotes>
<endnotes> --- </endnotes>
<toc>Table of Contents</toc>
<toc>
<toc>
</toc>
<toc>Contents</toc>
toc="no"

<h
toc="false">
=Title=
<h
>
You can, however, remove entire contents levels (e.g.,all sections at level 3 or higher) from
the table by modifying the CSS styling used in the table.
The details are discussed in Section 28.3.
17. Creating an index (
Use the {index
}
<index>
<index-entry>
{index
}
{index index creation
As was the case with end notes, you need to add an element at the place where you want the index to appear in your document:
The HML processor uses the element contents as the title. for example, The index at the end of this document was created using:Title <index>
</index>
<index> = Index = index </index>
Because of the way that most browsers scroll, it's best to put the
{index x}
You can specify a subtopic with a comma in the macro, for example, the current paragraph was put into the index using
{index index, subtopic}
Here's an easy-to-find example (The ZZ topic sorts to the very end of the Index). The current paragraph is prefixed with
{index ZZ} {index ZZ, subtopic} {index ZZ} {index ZZs, plural version}
ZZ 1, subtopic, 3(The three items to the right of the ZZ are hyperlinks to the current paragraph.)
The {index topic, optional-subtopic}
<index-entry topic="theTopic">optional-subtopic</index-entry>
Finally, remember that implicit paragraphs implied by a blank line are inserted only if the first character following the blank line alphanumeric. Consequently
...end of previous paragraph. {index myTopoc} A new paragraph.
{
...end of previous paragraph. A {index myTopoc} new paragraph.
...end of previous paragraph.
 {index myTopoc} A new paragraph.
Export the index to an external file by specifying a dest=
<index dest="/path/to/output/file.html">Optional Title</index>
The generated file holds HTML markup that exactly mirrors the HTML that's output to the main body of the document (see Section 28.5). You'll have to do a little postprocessing to build an aggregate external index for a multi-part document. In particular, the location anchors are all relative URL's, so you'll need to add a file indicator to their left.
<include>
<import>
Both include
import
< include href="http://www.holub.com/sources/someFile.java"> | |
< include src="/Users/allen/projects/sources/someFile.java"> | (or file=" " |
< import href="http://www.holub.com/sources/someFile.java"> | |
< import src="~/projects/sources/someFile.java"> | (or file=" " |
< import src="../sibling/someFile.java"> | (or file=" " |
Include code. Import everything else.
The href=
src=
file=
href="file://..."
~
~
The contents of imported files are just inserted into your document verbatim. That is, the <import>
<import>
<macro>

Included files are treated as listings, and unlike imported files, which are imported verbatim, listings are heavily processed. The listings at the end of this document were imported with
<include src="~/config/hml.head" title=""> <include src="~/config/hml.tail" title=""> <include src="~/config/hml.macros" title="">
If you supply a listing title (even an empty one, as I've done here), you can reference the listing symbolically.
Given the earlier <include src="~/config/hml.macros" title="">
{listing hml.macros} | displays as Listing 3 |
{listing-number hml.macros} | displays as 3 |
If you leave out the title=
<include>
Finally, you may tag lines in the listing. (Tagging is actually a complicated subject, and is discussed further in Section 23.5.)
Mark a line in a listing by putting {=
}
<listing>
public void f()
// {= f-def}
{
}
</listing>
displays as
and elsewhere in your document, you can reference the line with any of the following: {line f-def} | displays as | line 1 |
{# f-def} | displays as | 1 |
[#f-def the `f()` declaration] | displays as | the f() |
The <include>
<include>
19. Macro substitution
Macros are input that's replaced by something else (the replacement process
is called a "macro expansion").
The HML processor applies macros to the text portion of your document—they're never expanded inside any sort of code block
(inside a <listing>

19.1. Macro types
Two sorts of macros are supported:
The HML processor reads the macro definitions for the pre-defined macros from a configuration file (hml.macros, Listing 3) when the program starts up. The default version of this file is packed inside the hml.jar file that holds the program, but you can provide your own version. The process is discussed in Appendix A. Your version preempts the default one.
<
macro>
<import>
<h
>
=
==
Though it's tempting to look at the code-snippet mechanism (`code
`) as a macro,
it's not—it's an integral part of the processor. Consequently,
you can't redefine ` as if it introduced a macro.
HML processes code snippets before macros, so you can't use a macro in a code snippet,
and macros can't expand to code snippets.
19.2. Predefined macros expanded in normal text
Table 20.1 lists the predefined macros that aren't otherwise described in this manual.
The actual macro definitions are in Listing 3, and
Section 22.2 talks about how to interpret that file.
These macros are not expanded in code.
They effect only the text part of your document.
| Input | Displays as | Comment | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
\{ \} \[ \] \\ \* \^ \_ \ ` |
{ } [ ] \ * ^ _ ` | Many
macros depend on one or more of these special characters. "Escape" the special character with a backslash to prevent
a it from being handled specially. For example,
{i text} \{i text} | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
--- | | Lines containing nothing but a sequence of one or more dashes
are replaced by a horizontal rule (
 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
→[!] | →← | Zero-width space. Expanded after all other special
characters are processed. Handy for doing things like preventing
other macros from expanding. For example {[!]link x} {link x} | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
→[##] | → ← | Replaced by two more non-breaking spaces than the number of hash marks.
You may specify at most eight hash marks.
The current example is four spaces wide.
(The two extras make the width in the input the same as the width in the output, which
is convenient if you're trying to get text to line up in neat columns.)
[] ‘ ‘ ),
though that approach always uses space characters in the code, not the
document, font.
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
& | & | Expands to & & { | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
<< | « | Open guillemet. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
>> | » | Close guillemet. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
< | < | Expands to <
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
> | > | Expands to > | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
word---word | word—word | An em-dash. The --- | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
[---] | — | An em-dash in other contexts. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
0123--0123 | 0123–0123 | An en-dash. The -- | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
[--] | – | An en-dash in other contexts. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
... | … | An …
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
[tm] | ™ | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
(c) (C) | © © | If you really need to display a (c), use a zero-width space: ([!]c) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
(r) (R) | ® ® | If you really need to display a (r), use a zero-width space: ([!]r) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
+- +/- -+ | ± ± ± | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
[*] | × | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
[/] | ÷ | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
[+] | + | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
[-] | − | A minus sign, as compared to a dash (-). | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
[!=] != | ≠ ≠ | The brackets are optional. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
<= | ≤ | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
>= | ≥ | | | 1/4 ¼ | {index | 1/4 1[!]/4 | 1/2 ½ | Only when no spaces surround the /. If spaces are present, you'll get 1/2 | | 3/4 ¾ | Only when no spaces surround the /. If spaces are present, you'll get 3/4 | | ^1 ¹ | Evaluates to the | ¹ | ^2 ² | Evaluates to the | ² | ^3 ³ | Evaluates to the | ³ | ^o ° | Lower-case o. Evaluates to a | ° | X^super Xsuper | Superscript a single "word" (all alphanumeric characters that immediately follow the underscore).
A non-space character must both precede and follow the ^.
The | ^1 ^2 ^3 ^o | X_ _sub Xsub | Subscript a single "word." Note that you need two underscores.
| | X{^ many words} Xmany words | Use this form to superscript multiple words or strings that contain non-alphanumeric characters.
| | X{_ many words} Xmany words | Use this form to subscript multiple words or strings
that contain non-alphanumeric characters. There's only one underscore in this form.
| | <- ← | | | -> → | | | [SS] § | | | [dagger] † | | | [Dagger] ‡ | | | [Delta] Δ | | | [a``] à | Two ` characters in sequence are required. | | [a'] á | {link )
| | [a^] â | | | [e``] è | Two ` characters in sequence are required. | | [e'] é | | | [e^] ê | | | [i``] ì | Two ` characters in sequence are required. | | [i'] í | | | [i^] î | | | [o``] ò | Two ` characters in sequence are required. | | [o'] ó | | | [o^] ô | | | [u``] ù | Two ` characters in sequence are required. | | [u'] ú | | | [u^] û | | | [A``] À | Two ` characters in sequence are required. | | [A'] Á | | | [A^] Â | | | [E``] È | Two ` characters in sequence are required. | | [E'] É | | | [E^] Ê | | | [I``] Ì | Two ` characters in sequence are required. | | [I'] Í | | | [I^] Î | | | [O``] Ò | Two ` characters in sequence are required. | | [O'] Ó | | | [O^] Ô | | | [U``] Ù | Two ` characters in sequence are required. | | [U'] Ú | | | [U^] Û | | | ``
‘
| (Two left-quote characters in the input.) A left single quote.
|
An empty code snippet is treated as a left single quote.
If you really want two left-single-quote
characters next to each other, use HTML entities ( | ' '
’
| (Two right-quote characters in the input.) A right single quote, not an apostrophe ('). They're different in some fonts.
| | ` ` }`
“
| (Three left-quote characters in the input.) A left double quote, not a quotation mark ("). They're different in some fonts. Note that you need three of them in the input.
| | '''
”
| (Three right-quote characters in the input.) A right double quote, not a quotation mark ("). They're different in some fonts. Note that you need three of them in the input.
| | [timestamp] Thu Jan 23 11:02:31 PST 2014 | Current date and time in standard form. | | [month] 1 | Current Month. January = 1. | | [day] 23 | Current day of the month. | | [year] 2014 | Current Year. | | [hr] 11 | Current hour (24-hour time). | | [min] 2 | Current minute | | [sec] 31 | Current second | | [Month] January | Current month in English | | [Day] Thursday | Current day of the week in English | | {amazon 159059388X Holub on Patterns} Holub on Patterns
| Link to Amazon for book with indicated ISBN and title. By default,
if whoever clicks on the link actually buys the book, a percentage of the sale price
goes towards maintaining HML. You can, of course, change the macro to remove the
vendor ID (or reference your own vendor ID), either by modifying hml.macros
or by defining a user macro that overrides the default.
| | <box> Boxed Paragraph </box> | Boxed paragraph
Expands to |
...

|
 [( style="color:red;"] A [|] C [|] E [| style="background-color:yellow"] G [)] [(] B [|] D [|] F [|] [)] [(] [|] [|] [|] [)]

|
The columnar-output mechanism (Section 14) is easy to use, but not particularly flexible.
These macros are more annoying to type, but are more flexible.
The macros inserts |

Unlike the standard table mechanism, these macros don't care about
indenting, and they let you style individual cells. Text following
the '(' in
Theses macros don't work well with the built-in columnar-data mechanism.
Don't use something like |
There are two main categories of macros:
those that use braces (e.g.,{i
}
[http://www.holub.com]
In general, you can't nest macros that contain braces, but you can use any of the other macros in a brace-delimited macro without difficulty..
Brace and non-brace forms work well, however: {i r[e']sum[e']}
Part II: Advanced Features
20. Headings (HTML-style)
The =
<h
>
== MediaWiki-style headings == mwheadings

 Headings (MediaWiki-Style)

label=
HML modifies the behavior of the standard elements <h
>
=
<h
>
Note that HML recognizes only lower-case
versions of the <h
>

Looking at HML-specific behavior, the input:

H1-Title
 // or: =/ H1-Title <- Slash required for numbering
H2-Title
 // or: == H2-Title
H3-Title
 // or: === H2-Title
H4-Title
 // or: ==== H2-Title
You can change the leftmost number in the section number with the10. H1-Title
10.1. H2-Title
10.1.1. H3-Title
<IP_ADDRESS>. H4-Title
chapter="text"
attribute. If you leave it out, the chapter
number defaults to 1 for the first

In fact, any time you specify a number in a chapter=
chapter=

Appendix
 // can't do a chapter= with = form, must use <hN>

H2-Title

H3-Title

H4-Title

Another Appendix

H2-Title

A. Appendix
A.1. H2-Title
A.1.1. H3-Title
A.1.1.1. H4-Title
B. Another Appendix
B.1. H2-Title
You can actually use any arbitrary text in the chapter=
If you don't want HML to add section numbers, use <h0>

<h0>

<h0>H0-Title</h0> // or: = H0-Title = <- No slash for no numbering
H2-Title
 // or: == H2-Title ==
H3-Title
 // or: === H3-Title ===
H4-Title
 // or: ==== H4-Title ====
H0-Title
H2-Title
H3-Title
H4-Title
Setting the chapter=

H0-Title

H2-Title

H3-Title

H0-Title
H2-Title
H3-Title
The =heading=
<h0>
=/heading=

Finally, note that if you use an <h0>
<h0>

H1-title

Second H1-title
 <h0>H0-title</h0>
Third H1-title

Fouth H1-title

1. H1-title
2. Second H1-title
H0-title
1. Third H1-title
2. Fouth H1-title
You can use a chapter=
<h0>
21. Title elements:
<listing-title>

HML also supports automatic numbering of Listings, Tables, Figures, and
easy references to both these and <h
>
In fact, you've already seen this feature in action with Table 20.1. The following element preceded that table definition:

HML Macros

Table 2.1. HML Macros
{index {figure ...}
{table ...}
{listing ...}
{figure-number ...}
{table-number ...}
{listing-number ...}
label="macroTable"

<
xxx
-title>
| This input: | displays as: |
{table macroTable} | Table 20.1 |
{table macroTable visible text} | visible text |
{table-number macroTable} | 20.1 |
[#macroTable arbitrary text] | arbitrary text |
The word macroTable, in these examples,
is the label specified in the original

arbitrary text
#
There are identical mechanisms for Listings and Figures. Here's the complete set:

The Title
 | {figure abc} | {figure-number abc} | {figure abc visible text} |

The Title
 | {table abc} | {table-number abc} | {table abc visible text} |
<listing-title label="abc">The Title</listing-title> | {listing abc} | {listing-number abc} | {listing abc visible text} |
Section reference work much like figure, table, and listing references. Assign a label with
orN <h
N label="myLabel"> Title </h
>
== Title == myLabel
=/ Section references = sectionRef
{section sectionRef} | evaluates to | Section 21.1 |
{section-number sectionRef} | evaluates to | 21.1 |
[#sectionRef arbitrary text] | evaluates to | arbitrary text |
If you don't
like the visible text associated with
{section ...}
{figure ...}
{table ...}
{listing ...}
{note ...}
=/ Roll-your-own Links = rollYourOwn

Roll-your-own Links

[#rollYourOwn the current section]
Note that the link has to start with a hash mark, since it refers to a section within the current file. This is an HTML requirement.
Internal links (introduced with a #) don't
put a target="_blank"
#
The [
]
the current section.
<
macro>...<
/macro>
Use a <macro>
For example, this block:
defines a macro and then expands that macro. (The macro replaces every instance of the phrase "my web site" with a hyperlink to my web site). The previous example displays as:<macro>
|my web site|my web site|
</macro>
On my web site.
On my web site.
The HML processor reads all <
macro>
"
"
"abc"
"
"
{
i }
<
macro>
|"""([A-Za-z]+)"""|{
i $1}|
<
/macro>
Macros are expanded before most other tags are processed,
so you can redefine any of the predefined macros, or even
tags like <listing>
= text =

 text

...

The one exception to this rule are <
import>
<
include>
<
macro>
<
import>
Macros are processed in definition order,
and are processed only once, from the top to the bottom of the document.
Consequently, it can be risky for a user macro to expand to another user macro,
because it's sometimes difficult to know which of the two will
be processed first. Circular or recursive definitions won't work either.
22.1. Macro categories
In general, macros expand only in the text portion of your document;
they aren't expanded in <listing>

code:

<macro> code:'(?<=\b)(\ abstract|assert|boolean|break|byte|case|catch|char|class|const \ |continue|default|do|double|else|enum|extends \ |final|finally|float|for|goto|if|implements|import|instanceof \ |int|interface|long|native|new|package|private|protected \ |public|return|short|static|strictfp|super|switch|synchronized \ |this|throw|throws|transient|try|void|volatile|while|true|false|null)(?=\b) \ '$1' <macro>

<listing>
The backslash at the end of the line is a line-continuation indicator that tells the code that's loading the macro to concatenate the following line with the current line. This way you can put very-long macro definitions on multiple lines. The backslash and all surround white space (including space at the beginning of the next line) is ignored. This mechanism is supported only in macro definitions.
snippet: | macros that are active only in code snippets |
ref: | macros that are active only an a reference-expansion pass that occurs very late in processing. |
At present, you can define snippet:
ref:
Default-macros (in hml.macros, Listing 3) and user-defined macros are both created using the same syntax. The syntax is more complicated than the previous section would lead you to believe, but as long as you're doing something simple, you can ignore the complexity. The one thing you can't ignore is that there are a few special characters that have to be treated specially. Every macro definition takes the form:
'text-to-replace'replacement-text'optional-flags
The first character on the line is a delimiter that separates the three pieces of the definition, and can be any character of your choosing (except a space or tab). You can restate the above example as:
/text-to-replace/replacement-text/optional-flags
Just pick a character that's not otherwise used in the definition.
Here's a macro that replaces the text ytr
Yours truly
/ytr/Your's truly/
Here's another example that uses the
<NB>Note to the editor goes here</NB>
Here's the input that implements that mechanism:
   <macro> '<NB>'
' '</NB>'
' </macro>
| Character | Do the following to take away special meaning |
. | \. |
+ | \+ |
* | \* |
? | \? |
^ | \& |
$ | \$ |
| | \| |
{ | \{ |
} | \} |
[ | \[ |
] | \] |
( | \( |
) | \) |
\ | \\
|
and the following characters have special meaning in the replacement-text section:
| Character | Do the following to take away special meaning |
& | \& |
$ | \$ |
% | \% |
Either avoid these characters altogether or used the escaped (backslash-prefixed) forms unless you really know what you're doing. The text-to-replace is actually something called a regular expression. (See Section 22.2.1.) The HML processor ignores:
#
##
As mentioned earlier, the text-to-replace part of the macro definition is actually something called a regular expression. In fact, the characters with special meaning mentioned in the previous section all have meaning in a regular expression. To display a special character as itself, precede them it with a backslash ('\') to suppress its special meaning. A full discussion of regular expressions is beyond the scope of this document*, Here's the gist:
Think of a regular expression as a sequence of characters. For example, the regular expression abc matches the sequence a, followed by b, followed by c.
A .
c.t
cat
cut
c
t
A *
<.*>
<>

<abc>
Note that the *
*
*.txt
.txt
.
*
*.txt
*.txt
.*\.txt
txt
In addition to *
+
?
.*\.txt
.txt
.+\.txt
The default behavior of .*
<.*>
<abc> <def> <ghi>

.
<
>
i
Since the dot often matches too many characters, you can use
brackets to indicate a limited set of characters that can be matched.
For example, [abc]
a
b
c
ca[rt]
cat
car
[a-z]
[0-9]
[a-zA-Z]
The *
+
?
[A-Z]+\.TXT
+
[A-Z]
The replacement text in the second part of the macro definition uses special characters as well,
For example, an &
The macro expands to the HML markup for a link (|Allen Holub|[http:/
/www.holub.com &]
[url visible-text]
&
Allen Holub
Use parentheses to group input sequences. For example:
(abc)+
abcYou can also reference a particular group in the replacement text by using a
abcabc
abcabcabc
…
$
$1
/==>(.*)<==/$1/
.*
$1
==>
<==
==>BIG<==
`<span style="font-size:14pt;">BIG</span>`
'([0-9]+)==>(.*)<=='$2'
([0-9]+)
$1
(.*)
$2
36==>Really big<==
$1
36
$2
Really Big
Really Big
There a few more loose ends. You can use a vertical bar (|
(dog|cat)
^
$
^cat
cat
dog$
dog
^cow$
cow
^
$
MULTILINE
<macro> '^foo'Foo`MULTILINE </macro>
foo
Foo
MULTILINE
^
That's all I'll be saying about regular expressions, but this discussion barely touches the surface.
You should really read up on the subject if you want to do anything more complicated than what I've just described.
See the notes for suggestions. HML uses
Java-style regular expressions, and there's
additional information about HML-specific processing in a comment at the top of the
default hml.macros file (Listing 3).
23. Advanced code handling:
`code`
, <listing>

As mentioned earlier, code is handled differently from the everything else in your document. None of the standard HML mechanisms described elsewhere in this document apply to code blocks. Standard macros don't expand in code blocks, for example. In fact, you can use code snippets and blocks to document both HML and HTML.
For the most part, code appears exactly the same in the output as it looks in the input.
23.1. Explicit code blocks (
<listing>

{index <listing>

<listing>

<listing>

<listing>

As is the case with other HTML pseudo elements, any attributes that you specify in the tag that aren't meaningful to the tag itself are passed through to the underlying HTML, and your own styles preempt the default styles. For example, you could style your code and add an id with:
<listing class="myClass" id="myID">
<listing>

& < > !<...>! !{...}! //!
The following substitutions are made everywhere in
The
The sequence
This comment style forms a "bang comment."
The mechanism is handy for doing things like highlighting a block of several lines of code.
The three-character sequence
If there's nothing but white space to the left of the bang comment,
then the newline at the end of the comment line is removed as well.
In other words, if the bang comment is alone on the line, the HTML in the bang comment is effectively prefixed to the line that follows
the comment line.
This mechanism is different than
Tab character are expanded as 4-space tabs. Tabs are expanded very early in the processing,
so the above substitutions won't effect the tab layout.
Also, the tab-expansion code treats a
A comment introduced with three slashes (
Javadoc comments may not span
The
Defaults:
The
This behavior is necessary because you might want to pull in an untitled listing into your document
using an
When the title is empty (
Examples:
and can be referenced using
The HML processor generates listing line numbers automatically, and you can reference these
line numbers symbolically in your document. That way, the references in the document change
automatically as the code changes. There are two ways to handle symbolic references.
In any code block (but not a code snippet),
you can use
For example, this input
Though it doesn't make sense to use most of the line-number references
to discuss code in a
The following reference syntax is recognized everywhere in the document, even
in code blocks.
For example, this input
displays as
and a reference like
The HML processor recognizes definitions with pattern matching,
not a real parser, so it can be fooled by nonstandard formatting.
The following rules are followed:
The following definitions work fine, however:
You may split a class definition across listings,
but you must put the entire method definition in a single code block.
Inner classes are handled properly, but you must reference them with the full name.
So, here's a complete example that demonstrates all the possibilities.
This input:
displays as
{java, inner-class references}
{symbolic references, to java declarations}
and you can use the following references:
The same rule applies to listings, and
When you use an
The generated
When you supply a label at the
Use the
You can include just the
Finally, any
The listings in Appendix A were all imported into
the document with the following markup. Title and
The HML processor integrates seamlessly with Dropbox.
When the path you specify in a
All this requires a Dropbox account.
Go to the Dropbox web site and click Sign Up.
After the Dropbox sign up procedure, set up Dropbox access in your HML-in-the-cloud account.
HML-in-the-cloud doesn't need your Dropbox password.
Log on to Dropbox and authorize HML-in-the-cloud to access the account. Here's how:
TODO
Here are few of the most obvious differences between HML and MediaWiki/Markdown markup.
The main consideration with all these HML-specific elements is that they "wrap" standard HTML elements in the sense that the HML processor translates the special element into one or more standard HTML elements. A
In general, the HML processor adds a
Your document's
HML solves the problem by moving the contents of all
For example, you could add a title to your document and also
redefine one of the default HML styles by putting the following into your document.
If you specify multiple
All HML-generated HTML elements have a
The easiest way to style a single element is to simply pass a
The
CSS styles that HML uses come from the default header file.
That is, the HML processor inserts two files the output file (Appendix A):
If you want to style listings and included code differently,
The only structural difference is the
The
Notice a few things in the CSS for these divs in Listing 1.
<listing>

//!
code:
# comment
## comment
/* comment */
/* */
// comment
//
f(); //
# comment
## comment
/* comment */
// comment
//
f();
Comments
are styled specially, and empty comments are discarded, with the one exception of an
empty to-end-of-line comment that's alone on the line, which is preserved so that you can do this:
// A comment.
//
// More of the comment.
#
#
/***
*/
/**...*/
Javadoc comments that start with three or more stars are elided, and display exactly as shown at left.
&
&
<
<
>
>
!<...>!
<...>
In a listing or pre block only (not in a ‘…‘ code snippet), !<
>!
<
>
<
>
displays as

foo(); // call foo !!!!NOW!!!!

foo(); // call foo NOW
!∞
∞
In a listing or pre block only (not in a ‘…‘ code snippet),
the leading !
&
displays as

()=>( z+q ) // A !Λ function

()=>( z+q ) // A !Λ function
-----
//!

hello();
//!

-----
-----
#!

print 'hello'
#!

-----
-----
#!
//!
//!

<
>
!<...>!
which displays as
-----
// !!
f();
// !!
-----
-----
//
f();
//
-----
code:
code:
!<...>!
// The comment
/*
* The comment
*/
.hmlComment

28. Styling
class=
hml
class=
style=
hml.head holds all the CSS for the generated document.
This CSS is inserted directly into the output file,
not imported, so that the output file can stand alone.
There are no external dependencies that would make it difficult to view the document offline in your browser.
hml.head (Listing 1) is inserted at the top of the output file, before all the processed input.
hml.tail (Listing 2) is inserted at the bottom of the output file, after all the processed input.
28.1. Styling Code Blocks
<listing>

to
<listing>
public void code(){ }
</listing>
and

1

public void f(){ }

to

public void code(){ }

public void f(){ }

class

hmlPreGroup

hmlListingGroup
<listing>

hmlCodeAnnotations

<listing>

The processor puts line numbers and clutter associated with linking to specific lines into the "annotations" div, rather than mix this material into the code.
This makes it easier to cut and paste listings, and also helps internally with the code-macro processing (since macros don't have to worry
about markup the HML processor adds).

1

2

3

4

5

6

7

class C
{
public void f()
{
hello();
}
}

display: table-cell
28.2. Styling tables
The
| a | b | c | d | | e

 a	 b	 c

 d	 	 e

class="hmlTable"

hmlTable

The HML processor tries to put an
For example, you can add cell borders as follows:

When the rows have different numbers of columns in them, however, this input:
| c1 | | c3 | c1 | c2 |
| c1 | c3 | |
| c1 | c2 |
However, if you have borders, you end up with this (because the third cell on the second row doesn't have an
| c1 | c3 | |
| c1 | c2 |
You can solve the problem in one of two ways. Either put an explicit non-breaking space in the missing cell:
| c1 | | c3 | c1 | c2 | []
or put an explicit column marker at the end of every row:
| c1 | | c3 | | c1 | c2 | |
both of which give you
| c1 | c3 | |
| c1 | c2 |
The table of contents is laid out as follows:

Contents

1. Section One

1.1 Sub-sectionOne

2. Section Two
 ...

hmlTocLev0
hmlTocLev1
hmlTocLev0
<h0>
hmlTocLev1

A

<toc>

A

<toc>Title</toc>
A

<h0>

To eliminate all headings at a particular level from the table of contents, restyle the associated element to not print. For example, remove all heading levels from 4 up with:

toc="no"
= heading = myLabel

heading

If you don't specify a label, then the processor supplies one: ...
where N is an arbitrary number. This number changes if you add sections, etc., so it's not a good idea to actually use it for anything. It will appear in the browser's title bar when you use the table-of-contents link to get to a section of your document, however, so if you don't want anybody to see these machine-generated anchors, provide explicit labels in your heading tags.N  ...
The current document uses both <h0>

<h0>
<h0>
hmlTocLevel0
<h0 class="part"> Part I: Core Features</h0>
This input
Text<note>The note.</note> <endNotes> Title </endNotes>
Text1
 Title

1

The note.

hmlNoteBody
The popup behavior of the note is implemented with a bit of JavaScript (Listing 1, line 238).
To eliminate the popup behavior for all your documents (whereupon the note reference is a hyperlink to the note text),
just remove the
The

Optional title specified in
element.

topic

1,
2
…

…

hmlIndex
hmlTopics
hmlTopic
The processor makes several passes through the input—each pass works on the output of the previous pass. The logical ordering of the passes is:
<include>
<import>
<listing>

<include>
HML is best written in a programmer's editor like vim, which can handle straight-ASCII text without adding idiosyncratic modifications. If you use vim, you can keep a browser window open next to the vim editor window. On each save of the source file, vim can run the HML processor automatically, a simple browser refresh after writing immediately shows the new version. To make vim do that, add the following line to your .vimrc file:
autocmd BufWritePost *.hml silent! !/Users/allen/bin/hml <afile>
!silent
!silent
echo "Found errors" | espeak
C:\Windows>start C:\Windows\Media\tada.wav
mplay32 /play /close c:\windows\media\chimes.wav
# !/bin/bash # # Run hml from file-system binaries. If the file name ends in .html, # the otuput filename is the input name with a .html INSTEAD OF a # .hml extension. If the file name ends in anything else, the output file # has a .html added. This script has sounds an audible message where # there are errors, necessary because VIM calls the script whenever you # write a .hml file, and VIM doesn't show you any error messages, when # errors occur. # # This version runs HML directly from the file system. java -cp ~/projects/src/Hml/bin:/Users/allen/projects/src/util/bin:$CLASSPATH com.holub.hml.Hml $1 > ${1%.hml}.html # This version runs the HML processor from the distribution jar. modify the line to # reflect the path to your copy of the .jar file. # # java -jar ~/bin/hml.jar $1 > ${1%.hml}.html if [ $? -ne 0 ]; then say -v Agnes "There were errors" fi
The HML processor uses log4j to print debugging diagnostics. If you don't know what that means, don't worry, because diagnostic printing is turned off by default.
If you do use log4j, and your local default configuration file enables logging at the DEBUG level or lower, diagnostic messages appear every time the HML processor runs. To turn off those messages, put a
log4j.logger.com.holub=fatal
<logger name="com.holub"> <level value="fatal"> </logger>
For example, the following command processes chapter 1 (ch1.hml)
and sends the output to ch1.html
ch2.html
> java -jar hml.jar --out ch1.html ch1.hml --out ch2.html ch2.hml
The processor can handle forward references within a file. You can symbolically reference a listing pulled into the document later on in the same input file, for example. You can't reference a listing in an input file that hasn't yet been processed, however.
All output from processing files listed to the left of the first --out
directive goes to standard output.
Appendix A. Configuration
The distribution file—hml.jar includes a default set of configuration files (hml.head, hml.tail, hml.macros). The HML processor uses these versions by default.
The HML output file contains the contents of hml.head, followed by the processed input file, followed by the contents of hml.tail.
Default definitions for all HML's CSS styles are in hml.head,
along with the DOCTYPE

The various hml macros are defined in hml.macros.
You may provide custom versions of these files if you like. The best way to do that is use the default files as a template. Get the default versions by copying hml.jar to hml.zip and unpacking the hml.zip with an archive utility. On Mac or Windows, just double click a .zip file to open it. The root directory of the unpacked archive contains the configuration files.
The HML processor looks for customized configuration files before it loads the defaults in the jar file, so you don't need to replace the default versions in the .jar file. Just provide the custom versions somewhere in the file system.
The easiest way to specify an arbitrary location for a customized
configuration files is on the java command line with a -D
java "-DCONFIG=/path/to/my/config/folder" -jar hml.jar myInputFile > myOutputFile
If you don't use the -D
Changing the way comments are processed
At present, you cannot modify the automatic-tagging feature to work with a language other than Java. (That's definitely on the to-do list.)
However, you can change the way that comments work if your language
doesn't use a /*...*/
//
#
#
#
Here's how to change the comment convention to use a --
//
#
(*...*)
/*...*/
<
HMLconfig>
bangComment
<
HMLconfig>
<import...>
The element should look like this:
The<
HMLconfig>
bangComment=--!
<
/HMLconfig>
--!
(?: ... )
The next step is to modify the comment-related code macros. The defaults are defined as follows in Listing 3 (line 409 and following):
code: '/\*\s*?\*/''MULTILINE code: '^([ \t]*[^ \t/].*?)[ \t]*(?://|(?<!&)#+)[ \t]*$'$1'MULTILINE code: '/\*.*?\*/'$0'DOTALL|MULTILINE code: '(?://|(?<!&)#+[- \n=]).*'$0'MULTILINE
/*...*/
//
//
// ...some text // // some more text...
is transformed tof(); //
f();
The second group of macros wrap the comments in
which is a non-capturing group that matches either a(?:/
/|(?<!&)#)
//
#
&
--
/\*
\(\*
<macro>
Include this<macro>
code: '\(\*\\s*\*\)''DOTALL|MULTILINE
code: '^([ \t]*[^ \t/].*?)[ \t]*--[ \t]*$'$1'MULTILINE
code: '\(\*.*?\*\)'$0'DOTALL|MULTILINE
code: '--.*'$0
</macro>
<macro>
<
HMLconfig>
<import>
hml.macros
The following listings are the default configurations at the time of this writing. These are all in the top-level folder of the hml.jar file. (Again, copy hml.jar to hml.zip and unzip it to examine the actual files.)
<!DOCTYPE html>

# DON'T MODIFY THIS FILE UNLESS YOU KNOW WHAT YOU'RE DOING! # # In particular, you need to know regular expressions thoroughly. I # recommend reading Jeffrey Friedl's book "Mastering Regular Expressions:" # # http://www.amazon.com/gp/product/0596528124/ref=as_li_ss_tl?ie=UTF8&camp=1789&creative=390957&creativeASIN=0596528124&linkCode=as2&tag=alleiholuasso # # The regular expressions in this file follow the Java conventions (which are very similar to the Perl # conventions) described here: # # http://docs.oracle.com/javase/6/docs/api/java/util/regex/Pattern.html # # Regular expressions are notoriously difficult to both program and debug. I recommend running a full test # after every change, no matter how small. All the macros in this file are tested at the Java level # by the MacroTest jUnit test. ****** IF YOU CHANGE A MACRO IN THIS FILE, CHANGE THE JUNIT TEST TOO! ***** # Running the documentation file (hmldoc.hml) is also not a bad boundary-layer # test, since it uses every feature of the system. # # Blank lines, and all lines that start with a # are ignored, as is all text that follows a # # None of the macros in this file are applied to code: they have no effect within # a
...
, <listing>...</listing>, or `code` block. # # Macros are expanded in the order they appear, which is sometimes important. # For example, the character-escape macros (\\, \{, etc.) are defined very # early so that they'll be applied before any of the macros that might # use those characters. # # If you introduce a new macro, make sure that it doesn't conflict with an existing one. # None of the macros in this file are ambiguous. That is, a given input string will not # be recognized by more than one of the macros defined here. # # Macros definitions take the form: # # /regex/replacement/flags # # The first character is used as the delimiter, but you can't use a space or tab as a delimiter. # The flags are standard java Pattern-class flags, and you can OR them together (e.g. MULTILINE|DOTALL). # Note that you must specify MULTILINE for ^ and $ to work and DOTALL # if you want a . to match newlines. # # The following escape sequences are recognized in replacement-text strings: \t \b \n \r \f # All other characters are treated literally (so you don't have to use \\ to get a backslash # into a replacement string, and you don't have to escape quote marks). # # The following nonstandard variables can also be used in your replacement text: # # %(timestamp) Full timestamp for "now" # %(month) Month (1-12) # %(day) Day of the month # %(month) Month in English # %(day) day of the week in English # %(year) year (e.g. 2013) # %(hr) hour of the day (0--23) # %(min) minute of the hour (0-60) # %(sec) second of the minute (0-60) # # Use \% to put any of the above into your replacement text as literals. #---------------------------------------------------------------------- # The following prefixes can introduce macros (eg: code: /regex/repl/flags) # # text: Macro is expanded in text blocks only. # code: Macro is expanded in code blocks only. # ref: (not implemented, yet) Macro is expanded in a reference-expansion pass that occurs towards the end of # processing only (after all listings are processed). Macro is expanded in # both text and code! #---------------------------------------------------------------------- # Handle escaped characters. With the exception of backquote and open brace, # all of these are restored to their original form by the post-macro processing # `\\\\`\\` `\\\|`\|` `\\\[`\[` `\\\]`\]` `\\\{`\{` `\\\}`\}` `\\\*`\*` `\\\^`\^` `\\\_`\_` |\\`|\`| `&(?!\#?[a-zA-Z0-9]+;)|&$`&`MULTILINE # Comments. Note that the HML ... is handled by Hml.expand() # so it can span a
...
 or <listing>...</listing> element. Macros are handled # in a normal Pass, though there scope is limited to a single TEXT block. # A C-style end-of-line comment. First handle all real comments, but # don't touch \//. Then replaces the \// with a //. `(^\s*(?<![\\:])//.*\n)|(\s*(?<![\\:])//[^\n]*)``MULTILINE|DOTALL `\\//`//` # An HML comment. replaced with ellipsis `\[\*.*?\*\]`...`DOTALL `\[\]` ` `\[#\]` ` `\[#\#\]` ` `\[#\#\#\]` ` `\[#\#\#\#\]` ` `\[#\#\#\#\#\]` ` `\[#\#\#\#\#\#\]` ` `\[#\#\#\#\#\#\#\]` ` `\[#\#\#\#\#\#\#\#\]` ` `^-+$`<hr class="hmlRule">`MULTILINE` `<<`\«` `>>`\»` # Angle brackets. Don't map < or > in HTML/XML elements. # This expression is a kluge, but using negative look-behind to protect the trailing > # fails. That is, the following expression fails at the final {0,16}: # `(?<<[a-zA-Z]\w{1,32}(\s{1,32}\w{1,32}=".{0,128}"){0,16})>`\<`MULTILINE|DOTALL) # This appears to be a bug in Java, not in the expression, but who knows? This stuff is complicated! # Instead of look-behind, protect the angle brackets in an HTML element by mapping them to # entities, process any brackets that don't form elements, then put back the ones we protected. # # Note that the last two macros (which put things back) don't display properly in HTML. Here's # a version with an extra space after the ampersand that's not in the real definition. # '& #60;'<' # '& #62;'>' # '& #38;'\&' # `(?<!\\)<(https?://.*?(?<!\\))>`<$1>`MULTILINE|DOTALL `(?<!\\)<(/?[\p{Alnum}_-]+(\s+\w+=".*?")*)\s*(?<!\\)>`<$1>`MULTILINE|DOTALL `<=`\≤` `>=`\≥` `<-`←` `->`→` `\\?<`\<` `\\?>`\>` `<`<` `>`>` `(?<=[a-zA-Z])---(?=[a-zA-Z])`\—` `(?<=[0-9])--(?=[0-9])`\–` `\[---\]`\—` `\[--\]`\–` `\.\.\.`\…` `\([rR]\)`\®` `\([cC]\)`\©` `\[(tm|TM)\]`\™` `(\+-)|(\+/-)|(-\+)`\±` `\[\*\]`\×` `\[/\]`\÷` `\[\+\]`\+` `\[-\]`\−` `\[!=\]`\≠` `!=`\≠` `1/4`\¼` `1/2`\½` `3/4`\¾` `\^1`\¹` `\^2`\²` `\^3`\³` `\^o`\°` `\[SS\]`\§` `\[dagger\]`\†` `\[Dagger\]`\‡` `\[Delta\]`\Δ` # Accented vowels /\[a``\]/à/ /\[a'\]/á/ /\[a\^\]/â/ /\[e``\]/è/ /\[e'\]/é/ /\[e\^\]/ê/ /\[i``\]/ì/ /\[i'\]/í/ /\[i\^\]/î/ /\[o``\]/ò/ /\[o'\]/ó/ /\[o\^\]/ô/ /\[u``\]/ù/ /\[u'\]/ú/ /\[u\^\]/û/ /\[A``\]/À/ /\[A'\]/Á/ /\[A\^\]/Â/ /\[E``\]/È/ /\[E'\]/É/ /\[E\^\]/Ê/ /\[I``\]/Ì/ /\[I'\]/Í/ /\[I\^\]/Î/ /\[O``\]/Ò/ /\[O'\]/Ó/ /\[O\^\]/Ô/ /\[U``\]/Ù/ /\[U'\]/Ú/ /\[U\^\]/Û/ `\[timestamp\]`%(timestamp)` `\[Month\]`%(Month)` `\[Day\]`%(Day)` `\[month\]`%(month)` `\[day\]`%(day)` `\[year\]`%(year)` `\[hr\]`%(hr)` `\[min\]`%(min)` `\[sec\]`%(sec)` # boxes `<box>`<div class="hmlBox">` `</box>`
` # ordering matters here. Do the three-quote versions first. /```/\“/ /'''/\”/ /``(?!`)/\‘/ /''(?!')/\’/ # The _ is the _ entity. It's turned back into an _ by the restoration macros at the end # of the current file. `\{amazon\s+(\S+)\s+([^}]*)\}`<a href="http://www.amazon.com/exec/obidos/ASIN/$1/alleiholuasso" target="_blank"><em>$2</em></a>` # _italic_ *bold* `^\*(\S.+?)\*$`$1`MULTILINE|DOTALL `^\*(\S.+?)\*(?=[\s\p{Punct}])`<strong>$1</strong>`MULTILINE|DOTALL `(?<=[\s\p{Punct}])\*(\S.+?)\*(?=[\s\p{Punct}])`$1`MULTILINE|DOTALL `^_(.+?)_$`<em>$1</em>`MULTILINE `^_(.+?)_(?=[\s"'!,\.:;\?>\]}\)])`$1`MULTILINE `(?<=[<>\[{\(\s])_(.+?)_(?=[\s"'!,\.:;\?<>\]}\)])`<em>$1</em>` # subscript/superscript. Must follow circumflex accents to avoid # ambiguity. Do multi-word forms first to avoid ambiguity. # Must also follow _italic_ macro. `(?<![\s\\])\^(\p{Alnum}+)`$1` `\{\^\s*(.*?)\}`<sup style="hmlSuperscript">$1</sup>`DOTALL `(?<=[\p{Alnum}\.;"'>\)}\]])__(\S+)`$1` `\{_\s*(.*?)\}`<sub style="hmlSubscript">$1</sub>`DOTALL # other font-related macros `\{b\s+(.*?)\}`$1`DOTALL|MULTILINE `\{i\s+(.*?)\}`<em>$1</em>`DOTALL|MULTILINE `\{bi\s+(.*?)\}`$1`DOTALL|MULTILINE `\{ci\s+(.*?)\}`<code><em>$1</em></code>`DOTALL|MULTILINE `\{cb\s+(.*?)\}`$1`DOTALL|MULTILINE `\{u\s+(.*?)\}`<u>$1</u>`DOTALL|MULTILINE `\{x\s+([a-zA-Z0-0\-]+)\s+(.*?)\}`$2`DOTALL|MULTILINE `\{s\s+(.*?)\}`<span style="text-decoration:line-through;">$1</span>`DOTALL|MULTILINE `\{c\s+(.*?)\}`$1`DOTALL|MULTILINE `\{anchor\s+(.*?)\}`<a name="$1"></a>`DOTALL # Bullet and number lists lists: # Line items in both lists. After this pass, line items are all introduced by (^*
). # `^([#*]|(\d+\.))(.*\n) \ (([ \t\x0B\f]+.*\n)*) \ `$1
$3$4
\n \ `MULTILINE # # Now, wrap the whole list in the appropriate element. # `^(\*<.*?\n)\n`<ul>\n$1</ul>\n`MULTILINE|DOTALL `^((#|\d+\.)<.*?\n)\n`
\n$1
\n`MULTILINE|DOTALL # # Finally, get rid of the original list-item markers # `^(\*<)`<`MULTILINE `^((#|\d+\.)<)`<`MULTILINE # definition lists work pretty much like bullet lists, except ; introduces # the dt and : the dd. `^(:)(.*\n) \ (([ \t\x0B\f]+.*\n)*) \ `$1<dd>$2$3</dd>\n \ `MULTILINE `^(;)(.*\n) \ (([ \t\x0B\f]+.*\n)*) \ `$1
$2$3
\n \ `MULTILINE `^([;:]<.*?\n)\n`<dl>\n$1</dl>\n`MULTILINE|DOTALL `^([:;]<)`<`MULTILINE # Alternative table macros: [(] [|] [)], etc. Do these before Columnar-output # macros (which interpret the | in [|] specially `(?<=\[[\|\(]\])(\s*)(?=\[[\|\)]\])` \ ` ## Replace empty table cells with `\[\(([^\]]*)\]`
` ## [(] `\[\|([^\]]*)\]`</td><td valign="top"$1>` ## [|] `\[\)\]`
` ## [)] # Columnar output/simple tables # # Get rid of the optional trailing bars (at the end of a row): all bars # that are followed by a blank line, or are not followed by an indented continuation line `\|([ \t\f\x0B]*\n\n)`$1`MULTILINE `\|([ \t\f\x0B]*\n\S)`$1`MULTILINE # Add   into empty table cells `\|([ \t\f\x0B]*(\n[ \t\f\x0B]*)?)\|`| $1|`MULTILINE # horizontal separators `^\s*\|-\s*(\d*).*`<tr><td class=\"hmlTableLine\" colspan="$1"> </td></tr>`MULTILINE # Rows `^(\|)(.*\n) \ (([ \t\x0B\f]+.*\n)*) \ `|
$2$3
\n \ `MULTILINE # the entire table `^(\|<.*?\n)\n`<table class="hmlTable">\n$1</table>\n\n`MULTILINE|DOTALL `^\|<tr>`
`MULTILINE # column separators `\s*\|`</td><td valign="top">` # {link...}-shorthand macros ({link} itself is handled in the code) # Do this late in the file so that other macros that use square brackets. # are expanded first. `\[(?!!)(\S+?)((\s[^\]]+)*?)\]`{link $1 $2}`MULTILINE|DOTALL `(?<!\\)<https?://(\S+?)(?<!\\)>$`{link $1}`MULTILINE|DOTALL # Now do the {link itself}, in order: Note that all lower-case strings # are accepted as a protocol. # # {link ./url} // remove ./ # {link ./url text...} // remove ./ # {link #url} # {link #url text...} # {link http://url} # {link http://url text...} # {link url} // add http # {link url text...} // add http `\{link\s*\./(\S*)\s*\}`$1` `\{link\s*\./(\S*)\s*([^\s\}].*?)\}`<a target="_blank" href="$1">$2</a>` `\{link\s*#(\S*)\s*\}`$1` `\{link\s*(#\S*)\s*([^\s\}].*?)\}`<a href="$1">$2</a>` `\{link\s*([a-z]+://\S*)\s*\}`$1` `\{link\s*([a-z]+://\S*)\s*([^\s\}].*?)\}`<a target="_blank" href="$1">$2</a>` `\{link\s*(\S*)\s*\}`$1` `\{link\s*(\S*)\s*([^\s\}].*?)\}`<a target="_blank" href="http://$1">$2</a>` # Index `\{index\s*(.*?)\s*,\s*(.*?)\s*\}`<index-entry topic="$1">$2</index-entry>` `\{index\s*(.*?)\s*\}`<index-entry topic="$1"></index-entry>` # Mediawiki-style heading aliases (with an augmentation for labels) # First set handles the versions with no label (that set has to be done first), # then handle the labeled versions `^[ \t\f\xB0]*======/?([^=]*?)=*[ \t\f\xB0]*?$`
$1
`MULTILINE `^[ \t\f\xB0]*=====/?([^=]*?)=*[ \t\f\xB0]*?$`<h5>$1</h5>`MULTILINE `^[ \t\f\xB0]*====/?([^=]*?)=*[ \t\f\xB0]*?$`
$1
`MULTILINE `^[ \t\f\xB0]*===/?([^=]*?)=*[ \t\f\xB0]*?$`<h3>$1</h3>`MULTILINE `^[ \t\f\xB0]*==/?([^=]*?)=*[ \t\f\xB0]*?$`
$1
`MULTILINE `^[ \t\f\xB0]*=/([^=]*?)=*[ \t\f\xB0]*?$`<h1>$1</h1>`MULTILINE `^[ \t\f\xB0]*=([^=]*?)=*[ \t\f\xB0]*?$`<h0>$1</h0>`MULTILINE `^[ \t\f\xB0]*======/?([^=]+?)(?:=+)[ \t\f\xB0]*(\S+).*?$`<h6 label="$2">$1</h6>`MULTILINE `^[ \t\f\xB0]*=====/?([^=]+?)(?:=+)[ \t\f\xB0]*(\S+).*?$`
$1
`MULTILINE `^[ \t\f\xB0]*====/?([^=]+?)(?:=+)[ \t\f\xB0]*(\S+).*?$`<h4 label="$2">$1</h4>`MULTILINE `^[ \t\f\xB0]*===/?([^=]+?)(?:=+)[ \t\f\xB0]*(\S+).*?$`
$1
`MULTILINE `^[ \t\f\xB0]*==/?([^=]+?)(?:=+)[ \t\f\xB0]*(\S+).*?$`<h2 label="$2">$1</h2>`MULTILINE `^[ \t\f\xB0]*=/([^=]+?)(?:=+)[ \t\f\xB0]*(\S+).*?$`
$1
`MULTILINE `^[ \t\f\xB0]*=([^=]+?)(?:=+)[ \t\f\xB0]*(\S+).*?$`<h0 label="$2">$1</h0>`MULTILINE # implicit paragraphs `\n([ \t\f\x0B]*\n[ \t\f\x0B]*)+(\p{Alnum}|\[|\{|\()`\n
\n$2`MULTILINE # zero-width space /\[!\]// # Code macros are somewhat limited in what they can do, and if a code macro changes the # number of lines in the listing, all of the line numbering and associated HTML links # will be messed up. Don't do that. You can see which of of the HML mappings are done # here. Everything else is done by the HML processor **before** code-macro expansion # occurs. In particular, "bang comments" cannot be handled by macros because they can # change the line numbering. # code: '(?<!!)&(?!#(38|60|62);)'\&' code: '!&(?!#(38|60|62);)`\&` code: '(?<!!)<'\<' code: '>(?!!)'\>' code: '<'<' code: '>'>' # Macros that handle comments. The first two handle empty comments (which can # occur after marks are processed and removed. # Multi-line comments (e.g. /*...*/) # that contain nothing but whitespace are removed entirely. Empty end of line # comments (e.g. //...) are removed if there's something to their left, but # a // that has nothing but white space on both sides of it is not removed. # After the empty comments are removed, other comments are surrounded by # a  that formats them differently from the rest of the code. #start-comment-macros code: '/\*\s*?\*/''MULTILINE code: '^([ \t]*[^ \t/].*?)[ \t]*(?://|(?<!&)#+)[ \t]*$'$1'MULTILINE code: '/\*.*?\*/'$0'DOTALL|MULTILINE code: '(?://|(?<!&)#+[- \n=]).*'$0'MULTILINE #end-comment-macros # These entities are inserted in the Listing process to protect < > and & symbols # that it inserts from macro expansion. Now that we're done with macro expansion, # put them back. # # The following macros WILL NOT DISPLAY properly in the documentation (because # they'll be expanded)! Here are versions with a space added after the & so # that they'll print. That space isn't present in the actual file. # # code: '& #60;'<' # code: '& #62;'>' # code: '& #38;'\&' code: '<'<' code: '>'>' code: '&'\&'
…use.Note that, even though the
<note>
Here's the second note, created using
<block>
…
</block>
</note>
<note>
<note>
The<note mark="10" label="note10">...</note>
mark=
label=
{note note10}
<note suffix=", ">
Pattern
<
HMLconfig>
<import>
<
HMLconfig>
\\
\
`
{#
}
{:
}
{=name}
{amazon...}
{b...}
{bi...}
{c...}
{cb...}
{ci...}
{i...}
{line
}
{link ...}
{s...}
{section ...}
{u...}
{x...}
!=
(c)
(r)
*bold*
+-
,
----
---
--
...
//...
=
[|]
[!]
[##]
[(]
[)]
[*...*]
[*]
[+]
[-]
[...]
[/]
[a']
[hr]
[http://...]
[min]
[sec]
[timestamp]
[tm]
[year]
\{
\}
\*
\[
\]
\^
\_
^
_
_italic_
&
>
<=
<<
<
<
!=...=!
>
<block>
<box>
<endnotes>

<http://...>
<import>
<include>
<index-entry>
<listing-title>
<note>

1/2
3/4
code:
ref:
text:
title=
[*...*]
{=name}


There are 3 bytes of permanent storage in the chip called 'fuse low byte', 'fuse high byte' and 'fuse extended byte'. These bytes are called fuses and can be reprogrammed as many times as you want and determines the behaviour of the chip. To do that, their value is not erased when the chip is powered off or reprogrammed.
Each microchip has its own definition for the values that must have the fuses. In this tutorial, we are going to work with the fuses of the Atmel Attiny44A.
| Name | Description | Default Value | Byte | Bit range | Datasheet page |
|---|---|---|---|---|---|
| CKDIV8 | The prescaler feature can be used to change the power consumption when not high performance is required. This feature can be used with any clock source. The prescaler divides the clock frecuency by a defined factor that can be configured using the CLKPS(3...0) register (Datasheet - Table 6-11), being its default value "0011" (divistion factor of 8). | 0 | LOW | (7) | 30 |
| CKOUT | This fuse allows us to use the chip clock as a clock source to drive other circuits. Once this bit is programmed, the PIN B2 will output the clock. | 1 | LOW | (6) | 30 |
| SUT | This fuses determine the Start-up Times for the external clock selection. This time must be long enough to ensure that the MCU is kept in reset mode while the clock is changing (is not stable). Its default value defines the longest Start-up time. | 10 | LOW | (5,4) | 26 |
| CKSEL | The AMTEL Attiny44A can use several clock sources. By default, the clock used is the internal 8MHz oscillator. The available configurations can be found in the datasheet, in table 6-1. | 0010 | LOW | (3...0) | 25 |
| RSTDISBL | When programmed (0), the PB3, instead of being used as a reset pin, it can be used as an I/O pin. | 1 | HIGH | (7) | 3 |
| DWEN | This fuse allows the activation of the 'debug' mode. Once it is programmed, the RESET port is configured as a bidirectional I/O pin with pull-up enabled. | 1 | HIGH | (6) | 150 |
| SPIEN | Fuse that enables serial program and data downloading. Once unprogrammed this fuse, in order to reset its value, you will need a 12V programmer. | 0 | HIGH | (5) | 159 |
| WDTON | A watchdog timer is a mechanism to prevent closed loops and errors in the microchip. It consists on a decreasing counter. If it reaches 0, it generates a timeout signal that triggers an action to restore the system. To avoid this, the program must restart the timer before it times out. | 1 | HIGH | bit range | 41 |
| EESAVE | If programmed (0) the EEPROM memory will be preserved through chip erase. | 1 | HIGH | (4) | 159 |
| BODLEVEL | This fuse controles the Brown-out detector. A Broun-out detector is a circuit that monitors the supply voltage while operating. It compares the supplied voltage to a fixed one. If the supplied voltage decreases blow a fixed one (VBOT-), the Brown-out reset is enabled until the voltage raises above a VBOT+. Then a timer starts; if it times out, the reset is disabled. By default, the Brown-out detector is disabled. In table 20-6 of the Datasheet all the modes are specified. | 111 | HIGH | (2...0) | 159 & 176 |
| SELDPRGEN | This fuse, if programmed, allows to the device the ability to upload a program to the MCU by itself. | 1 | EXTENDED | (0) | 152 |
As seen, there is just one bit in the Extended byte of the fuses whose value will change the microchip behaviour. The bytes 7...1 should be set with a value of 1.
| High Level configuration | |
|---|---|
| Clock Output Enable [PB2] | |
| Divide clock by 8 | |
| Clock | |
| External Reset disable | |
| DebugWire Enable | |
| Enable Serial Program and Data Downloading | |
| Watchdog Timer always on | |
| EEPROM memory is preserved through the Chip Erase | |
| Brown-out Detector trigger level | |
| Self-Programming Enable |
| Low Level configuration | |||
|---|---|---|---|
| Bit | Low | High | Extended |
| 7 | |||
| 6 | |||
| 5 | |||
| 4 | |||
| 3 | |||
| 2 | |||
| 1 | |||
| 0 |
| Fuse values | |
|---|---|
| Low: | 0x |
| High: | 0x |
| Extended: | 0x |
~$ avrdude -p t44 -P usb -c usbtiny -U lfuse:w:0x:m -U hfuse:w:0x:m -U efuse:w:0x:m


I challenged myself to create a web project everyday for a year.
I created a navbar from scratch using just CSS. I included a background image of Mount Baker that I found on Imgur.
HTMLCSS
I got the idea to create a Mondrain-esque picture from here. I wanted to start off with an easy challenge.
HTMLCSS


dash.games.thumbnail.page_help_link
Give your page a splash of color! When people view your game page, they'll be switched to this theme.


Maria:
You said that you would use this crystal to purge the dark energy from the Execution Grounds? You must hurry and give it to
High Priest Sylvain
. I hope that the purification of that place will soon be achieved.


Customers // {{ policy.holder.username }} Harris
{{ policy.holder.username }} Harris
Owner of an {{ policy.vehicle.vehicleDetails.make.name }} {{policy.vehicle.vehicleDetails.modelType}}
With Prince Insurance since November 2014
Insured on {{ policy.startDate | date:'d MMM y'}}
Lives at:
40 Garick Pass
Newbury
United Kingdom
{{ policy.vehicle.vehicleDetails.make.name }} {{ policy.vehicle.vehicleDetails.modelType }}
New Vehicle
Owned by: {{ policy.holder.username }} Harris
Registered on: {{ policy.startDate | date:'d MMM y'}}
2.5L Engine 240bhp
5 Doors
Colour: {{policy.vehicle.vehicleDetails.colour}}


encoding¶
Tools to work with encoding files, character sets etc.
-
chars2psnames
(char_list)[source]¶ Get a list of PostScript glyph names for a list of unicode characters.
-
crop_glyphset
(font, glyph_names)[source]¶ Reduce the font’s character set, keeping only glyphs with names in the given list.
-
extract_encoding
(ufo_path, enc_path=None)[source]¶ Extract encoding data from an ufo’s glyphOrder attribute.
-
import_encoding
(file_path)[source]¶ Import glyph names from an encoding file.
file_path: The path to the encoding file.
Returns a list of glyph names, or
None
if the file does not exist.
-
import_groups_from_encoding
(enc_path)[source]¶ Import groups and glyph names from a structured encoding file.
Returns an OrderedDict with group names (keys) and glyph names (values).


Bootstrap's grid system uses a series of containers, rows, and columns to layout and align content. It1s built with flexbox and is fully responsive. Below is an example and an in-depth look at how the grid comes together.
Bootstrap's grid system uses a series of containers, rows, and columns to layout and align content. It1s built with flexbox and is fully responsive. Below is an example and an in-depth look at how the grid comes together.
Bootstrap's grid system uses a series of containers, rows, and columns to layout and align content. It1s built with flexbox and is fully responsive. Below is an example and an in-depth look at how the grid comes together.
Lorem magna voluptate commodo elit reprehenderit. Ad sint et occaecat culpa cupidatat pariatur. Culpa aliquip ullamco elit labore incididunt cupidatat consectetur ea nulla quis aute deserunt eiusmod anim.
Lorem magna voluptate commodo elit reprehenderit. Ad sint et occaecat culpa cupidatat pariatur. Culpa aliquip ullamco elit labore incididunt cupidatat consectetur ea nulla quis aute deserunt eiusmod anim.


Repomania
Enter a user to view their repositories
Submit
User Info:
Username:
Full Name:
Followers:
Repositories


Carcassonne
Game: {{ key }} {{ value[0].GameName }} ({{ value[0].GameDate | date:'shortDate' }})
| Player Name | Farms | Towns | Roads | Monasteries | Extra | TotalScore |
|---|---|---|---|---|---|---|
| {{ game.PlayerName }} | {{ game.Farms }} | {{ game.Towns }} | {{ game.Roads }} | {{ game.Monasteries }} | {{ game.Extra }} | {{ game.TotalScore }} |


Change Program
Junior Program
Adult Program
Red
Keelboats Reef
Lagoon Restriction
Two to a jib
Two to a main
Yellow Crew
Red Crew
Yellow
Green Keel
Green Crew
Special
4th of July
Head of The Charles
Weather
Weather Warning
Half River
Wetsuits
Other
Requires dockmaster approval to submit.