Tinderbox User-to-User Forum (for formal tech support please email: info@eastgate.com)
Tinderbox Users >> Exporting from Tinderbox >> Exporting literal code samples in HTML?

Message started by l.m.orchard on Nov 12th, 2007, 7:36pm

Title: Exporting literal code samples in HTML?
Post by l.m.orchard on Nov 12th, 2007, 7:36pm

I'm trying to export some blocks of HTML as escaped HTML - eg. samples of code.  Consider this as the text of the note:

   <h3 class="entry-title">

The first thing I tried was to set the attributes HTMLMarkupText=false and HTMLQuoteHTML=true - and then used this as a template:


This didn't work, as the resulting output had all my exported example HTML in raw form.  Then, I tried this template:


However, this didn't work as expected because the exported example HTML was then *double* encoded with like so:

   &amp;lt;h3 class=&amp;quot;entry-title&amp;quot;&amp;gt;

What I'm really after is the following:

   &lt;h3 class="entry-title"&gt;

I've also tried setting HTMLQuoteHTML=false on the note, with the same results.  Am I missing a trick here?

Title: Re: Exporting literal code samples in HTML?
Post by Mark Anderson on Nov 13th, 2007, 4:30am

This is problematic as you need to be able to indicate when TB should/shouldn't escape otherwise similar types of mark-up.  I've written a TBX that you can download from here;"Code_Markup_for_HTML.twiz" is a Tinderbox wizard that will install a TBX plus associated HTML templates.

As the TBX shows, TB - as at v4.0.2 - can't easily do what you want.  The suggest work-around is the rather ugly kludge of putting the code samples in notes of their own and using includes.  That latter solves the exported end but wrecks the usability of the source TBX.

Before reading the following I recommend to look at the above TBX as it explains the status quo.

My suggestion is for a ^format(data,tag [,class, id])^ export tag.  Although 'tag' would normally be <pre> or <span> more advanced HTML-ers might be able to make more inventive use (clearly they're responsible for look the resulting mark-up). The specified mark-up tag would then enclose the TBX source data enclosed by the ^format()^ mark-up. Line breaks in the source data would be maintained in the output HTML stream but on-screen rendering would be controlled by the tag applied and/or the CSS attributes. The 'class' tag would allow TB to apply a named class attribute to the enclosing tag, same for 'id'. Thus:

<note name="Plenary" x="0" y="2"/>
<note name="Track 1" x="4" y="2"/>
, span, codesample, sample1 )^

... this gives HTML output of ...

<span class="codesample" id="sample1">
<note name="Plenary" x="0" y="2"/>
<note name="Track 1" x="4" y="2"/>

Note the output HTML source maintains the line breaks in the XML source data. By default a <span> tag wouldn't honour that line break on screen but the CSS styling of either the optional class or id could do so - or you could just use a <pre> tag instead of <span>.

I propose that line breaks inside ^format()^ before and after the data (see above examples) are ignored, this allows the inline export TB mark-up to not intrude visually on the note's source data. similarly the spanning HTML that is created should be placed on separate lines to the data to aid legibility of the source output. Use of the 'class' and 'id' arguments is optional but if using id without class, the empty argument should be included:
^format(<note name="Plenary" x="0" y="2"/>,pre,,ex4)^
It may be that as TB v4+ moves to using expressly quoted string literals that tag/class/id should be in double quotes:
^format(<note name="Plenary" x="0" y="2"/>,"pre","","ex4")^


What do others think?

Title: Re: Exporting literal code samples in HTML?
Post by Mark Anderson on Dec 4th, 2007, 4:32am

User Dave G has added the following in an email:

I wanted to comment on this thread about HTML. Please feel free to post on
the board for me. ;-)

Anyway re this thread about quoting literal html. I have a suggestion.

Why not honour the <code> tag?

It is similar to <pre> but it has semantic meaning... This is code not just formatting.

If the TB note formatter knows HTML code is expected inside this tag it can handle it differently. I.e. Code the < and > as entities but not interpret the code itself. And the <code> tags disappear (like <pre> would).

This way also has the advantage that code segments can be mixed with plain text.

This method would need some work inside TB but I think provides a way to get easy/simple code display and do something sensible by default on export to HTML, and also keep the parsing and handing of note content well-defined.

It's interesting and opens a concept of treating code sections like TB Bold/Italic markup, i.e. as something we code define at export (or use the TB defaults). Thus we might have another entry in HTML View Style tab to control how <code> sections are marked up.

I still prefer the option of using an export code flag to handle this and then mark up code in TB source as suits reading in TB as it's very possible to want <code> style mark-up to be block (i.e. hard break after element) in some use and inline in others.  A code sample would likely be block whereas reference to a code method or function would be inline.

What do others think, or are there so few of use who want to format code samples?. But 'code' needn't mean computer code, it might be some special sort of reference in the corpus of your research/project - just something that needs consistently different mark-up from the main body copy when exported to HTML/XMl/etc.

Title: Re: Exporting literal code samples in HTML?
Post by DaveG on Dec 4th, 2007, 10:33am


Mark - thanks for doing my post AND sorting out my password issue  :)

I like solutions that work at the text level because for me it makes writing easier and gives more freedom to write fewer notes if preferred.
Using attributes or export codes at whole note level seem less useful to me.
Perhaps I am forgetting export codes can now be embedded in notes?

Of course there would be room to have options controlling what TB did with HTML inside a <code> tag pair.

Issues of display are certainly to worry about but I feel can be dealt with simply and economically in CSS after export and by using id= or class= on the code tag. (or selectors like <p> <code> or just <code>)


http://www.tabatabai.ch/  done just with CSS & Tinderbox  :o In Feb 2003. Honest.

Tinderbox User-to-User Forum (for formal tech support please email: info@eastgate.com) » Powered by YaBB 2.2.1!
YaBB © 2000-2008. All Rights Reserved.