Normally, Tinderbox lets you embed html in your notes, and exports that embedded HTML without change.
Spans of $Text using the note's 'Code' font (as in $CodeFont) are now exported with <code> tags. The markup applied is determined by $HTMLCodeStart and $HTMLCodeEnd. The Style tab of the Export Inspector lets you edit these.
Inline code examples
Sometimes, though, you want to show an example of your HTML (or some other programming language) on a web page. That means you want the HTML tags to appear as you see them in Tinderbox, i.e. you see the character sequence "<b>", not the effect of bolding some text.
Originally, setting $HTMLQuoteHTML to false let you export HTML examples in an entire note. But, sometimes, you want the example to be handled differently than the rest of the note so $HTMLQuoteHTML is deprecated in favour of the following usages:
- Tinderbox respects the tags <code> and </code> when they appear within notes. HTML between these tags is always encoded during export so it appears as you see it, instead of being passed unchanged to the browser with the exception that within <code> sections, the opening angle brackets of all tags must be encoded (see section below) in the source text.
- Tinderbox also respects the tags <pre> and </pre> when they appear within notes. Inside these tags, Tinderbox adds no paragraph formatting and leaves whitespace unchanged; since the intent of the <pre> tag is to allow manual line breaks, adding paragraph markup in this context defeats its purpose. Generally, text inside <pre> is also further enclosed in <code> tags. The <pre> controlling the line breaks and layout, the <code> the use of a monospace font.
- If combining use of <code> and <pre>, the <pre> tags should go outside the <code> tags, enclosing them. Either way, enclosed code needs all opening angle brackets encoded (see below).
Setting $HTMLQuoteHTML to true will override this feature, so do not mix the two!
Opening angle brackets of tags with in <code> and/or <pre> sections
Although a single left angle bracket < can be typed literally in text, e.g. used as a less than sign, in all other cases it must be entered into the $Text as an encoded entity '<'. So, a < followed immediately by anything other than a space or number character must be entered as '<' or it may be exported incorrectly. For this reason, nearly all of the many < in the source $Text of this article required the character to be HTML-encoded in the $Text so as to render correctly in the exported text.
Therefore, '<' encoding of a tag opening must be used even inside sections of text enclosed by <code> and/or <pre> tags. Why should this matter inside code samples? Consider these two examples where the sample includes HTML styling tags <b> and </b>:
-
This is some text.→ here the < of the bold tags were not encoded and bolding is applied -
This is <b>some</b> text.→ here the < of the bold tags were encoded as '<' and so the code is seen as intended
Using the newer $Text 'Code' font option does not remove the need to check < characters inside the code-styled text.
This requirement to encode < characters opening tags holds not just for HTML code samples but any code where < and > are use to indicate inline tags, eg., XML, OPML, etc.
Code samples and paragraph spacing
Note that if you use <code> for a single line sample, you will not emit a wrapping <p> tag as Tinderbox does not emit an 'auto-paragraph' if:
- The line beings with a < character
- The line beings with a < character preceded by whitespace (space, tab, etc.)
So, if you want such a single line code example emitted as a separate paragraph, place an option+space at the end of the line after the </code> tag. Tinderbox will detect this and add the <p> tags Also, if such a line also starts with a tab it will use your TBX's defined indented-paragraph styling.
Whole note code samples
Alternatively, you may have a note consisting entirely of code (HTML, XML, etc.) that needs to be exported verbatim, e.g. as is a boilerplate include to a larger exported page. In this case the best approach is to turn off $HTMLMarkupText (i.e. set to false). This should ensure the pages characters are exported untouched. However, characters outside the low ASCII set, such as a • may get transposed to a Unicode-style HTML entity.