Mulch-help

1. What is it?

Yet another markup language designed to make it easier to produce HTML. Characteristics:

• produces snippets of HTML rather than a whole page. These can be stitched together by the client program to make a complete page
• basically, a short-hand notation for HTML and CSS class and style specifications
• in the full version, you can drop in any HTML code you like to overcome a Mulch limitation or to enhance it
• applies intelligent defaults to missing or ambiguous mark-up codes. Makes it hard to produce anything other than HTML that validates to 4.01 Strict.
• Mulch is an abbreviation for Mark-Up Language for CSS and HTML

2. Any good?

As with any markup language, personal preferences and the domain you are applying it to make all the difference.

Most of the help and related texts on this site are written in Mulch (the usual sign is the floating table of contents, as per this page).

3. Mulch example

Many Much codes are similar to their HTML equivalents, but you normally do not need a close tag -- many tags close automatically where you'd expect them to

This page so far in Mulch:

 [h1 Mulch-help
 [contents
 [numbering-on

 [h2 What is it?

 [p Yet another markup language designed to make it easier to produce HTML. Characteristics:

 [li produces <strong>snippets </strong>of HTML
  rather than a whole page. These can be stitched together
  by the client program to make a complete page

 [li basically, a short-hand notation for HTML and CSS
  class and style specifications

 [li in the full version, you can drop in <strong>any</strong> HTML
  code you like to overcome a Mulch limitation or
 to enhance it

 [li applies intelligent defaults to missing or
  ambiguous mark-up codes. Makes it hard to produce
 anything other than HTML that validates to 4.01 Strict.

 [li Mulch is an abbreviation for Mark-Up Language for CSS and HTML

 list]

 [h2 Any good?

 [p Most of the help and related texts on this site
  are written in Mulch (the usual sign is
 the floating table of contents, as per this page).

 [h2 Mulch basics

 [p Many Mulch codes are similar
 to their HTML equivalents,
 <strong>but you normally do not need
 a close tag -- many tags close automatically
 where you'd expect them to</strong>

 [p This page so far in Mulch:

 

4. Mulch basics

5. Using Class codes

Mulch uses something similar to a REBOL refinement if you want to specify a class or classes for many tags, eg: ("notice" is a class defined in the Library CSS as is "lsh", "lsdata" and other used throughout this page).

6. Class codes refer-backs

6.1. Relative refer-backs

• You can use class/*-nnn to reuse the class specification for the same tag.
• [p/class/* -- means the same as the previous paragraph
• [p/class/*-1 -- means the same as paragraph before that
• [cell/class/*-1 -- means the same as two cells back.

This notation was used to stripe the Mulch basics table above. The first few lines of it are:

 [cell/class/lsh Code
 [cell/class/lsh use for

 [row
 [cell/class/lskey1 [h1
 [cell/class/lsdata1 A heading 1

 [row
 [cell/class/lskey2 [h2 ... [h6
 [cell/class/lsdata2 Headings 2 through 6

 [row
 [cell/class/*-3 [p
 [cell/class/*-3 Start a paragraph

 [row
 [cell/class/*-3 [contents
 [cell/class/*-3 Insert the table of contents (based in the [h2 ... [h6)

 [row
 [cell/class/*-3 [list
 [cell/class/*-3 Start a list

 

Note that the table above starts with a [cell. Mulch will correctly insert the [table and [row codes that are missing. You only really need those for nested tables.

6.2. Absolute refer-backs

You can use class/nnn to reuse your class specification for the same tag.

• [h2/class/1 -- means the same as the first [h2
• [p/class/4 -- means the same as the 4th paragraph
• [cell/class/9 -- means the same as the 9th cell

This is not as useful a notation as the relative nunmbering, but it does give you a way of writing (say) your first [h2 with a specific class, and then refering to it latter, example:

 [h2/class/warning
 [h2/class/notice
 [h2/class/*-1    -- means class=notice
 [h2/class/1      -- means class=warning
 

7. Style codes

You can do much the same thing with style codes as you can with classes:

 [list/style/list-style-type:lower-alpha;color:red
 [li item 1
 [li item 2
 [li item 3
 list]
 

8. Style code refer-backs

work much the same as class code referbacks:

[h2/style/text-decoration:underline;color:green

[h2/style/* -- means same as above

9. Mixing classes and styles

No problem -- except that a very simple tag is likely to now be somewhat overburdened. Maybe better to rethink it, or declare a new class.

10. Specifying other attributes

Again, like class and style, use a refinement-like specification: this time, /att:

11. Other attributes refer-backs.

Can't do it -- that's not defined

12. Mixing classes, styles and other attributes.

Yes, you can do it, and yes it looks a total mess. Really seriously think about simplifying to a single class. This sort of thing gives mark-up languages a bad name:

13. Use your own CSS styles

The code examples so far have all used CSS classes defined in the REBOL.org CSS styleheet. But suppose you want to define your own styles, or to override system styles?

You do that with the [style and style] codes. Example:

 [style
  h2 {color: blue}
 .mystyle {border-left: thick blue solid}
 style]
 

• You have add a [style ... style] section anywhere in the source, except as part of an [asis ... asis] block
• You can have more than one set of styles. They will be swept up into one <style>...</style> entry
• You styles affect only the page you are adding/updating. They do not affect the look and feel of any other page on the site.

For an example of a personal page with overriding Mulch styles, look at: this page.  It has these styles defined:

 [style
  p {color: blue;}
  h2,h3 {color: green}
  pre {red}
 style]
 

14. Some limitations

14.1. Personal styles

On REBOL.org, these are only honoured on your personal page. You can specify them on other member-contributed documentation (eg script documentation, script discussions); but, currently, they are ignored.

14.2. Double quotes

Much and REBOL squabble over double-quotes. Some times they need to be interpreted by REBOL to make a single unit, like the anchor text in a link:

     [link http://test.com "click here"
 

Should become:

click here  without the quote marks

But, more often you may want to use them in a sentence:

     Press the "Off" button.
 

The trick is to double up the double quotes when you really want to use one: ""like this"".

15. What can't you do

15.1. Disabled features

The REBOL.org version of Mulch disables some features of the full system. That's sadly necessary as it runs in server-mode, and so te ability to read and write files, or to execute arbitrary code has to be curtailed. Just to let you know what you are missing:

• [set-var -- Executes code and sets a variable to a value
• [get-var -- Injects the value of the variable into the expansion
• [include -- Include a whole other file at this point (which may itself include other files, and expand its codes)
• [include-asis -- include a whole other file at this point as an ASIS block -- ie do not expand its codes
• [do -- defines and executes a function. Assumed to return a snippet of Mulch code at the point of execution which is then slipstreamed into the generation.
• Use much in the way of actual HTML. Sadly, letting you specify real tags opens our users to some XSS (cross-system scripting) attacks, if they have Javascript enabled. These HTML codes are the only ones permitted in this version:
  [ <strong> </strong> <u> </u> <br> <br /> ]

15.2. Markup issue

The nature of Mulch codes means they assume a space on each side of items they are marking up. No way to do This with the [span code. The best you could manage is T h i s

Last updated: 30-Jan-2005