REMARK Documentation

Overview

This is a brief overview of what remark is all about. Use the menu above, to go into more details about any one topic.

GUI:

Remark has a simple GUI. Each site in its config files has one row of buttons, each of these button is used to launch a parse of one or more files. button labels are pretty self-explanatory.

A setup with two sites.

Site commands:

• Update Latest: Regenerates just the last edited file of your whole site. To quickly view changes brought to the source file you are working on.
• Update changed: Regenerates and mirrors all the files in the source which are more recent than the destination. Usefull to move over a changed css sheet and images (but will move over the web files too, of course).
• Update all site (forced): Regenerates the whole site. This is often used when updating a site based on changes to the tags themselves.
• Browse: Simply launches the most recent file within the destination... you must cause at least one update for this to be active.

Options:

• Auto Browse: Whenever you update a page or a site, this will automatically call browse on the latest page. Very handy while editing a page.
• verbose: Give a litle bit of feedback while parsing the site's pages.

Remark Engine:

• Remark outputs static html pages out of dynamic source pages.
• Remark mirrors new directories in destination web folder for you, so you don't have to mirror all the layout structure changes to your source.
• Remark, mirrors any other kind of files you specify in the configs. This is usefull to copy over images, css files, etc.
• binary and ascii files are separate mirroring/parsing setups... so that binary files do not get corrupted on mirroring to destination site.

The remark html dialect twist:

Remark has its own dialect, but it is a dialect very near html, which can include html. It is an extension to html. Any html file will go through remark without hickups

If all Goes well and your custom tags are well built, Remark returns w3C 4.0.1 HTML ascii files when its done parsing a file.

The main difference is that custom tags are nested. This means that there are no <tag> </tag> pairs within custom tags. you simply include the hierarchical html inside the first tag's ">" character.

The following in html:
<P><CENTER><B> A centered bold label </B></CENTER></P> 

Can be remarked as:
<P! <CENTER! <B! A centered bold label >>>

why?

• less typing
• easier style changes
• less errors in the long run on large files with many nested html blocks or styles

drawback?

There is one very important thing to know. All < and > characters within the source ascii file must be paired . This means that you cannot use these characters directly within your text, under no circumstance. Always use the explicit &lt; and &gt; character code equivalents... Otherwise remark does not know where the boundaries of tags are and you will get the following message in the REMARK CONSOLE:

BAD HTML TAG NESTING, MISSING "<" character

Custom tags dialecting?

Remark allows each tag to have its own language and interface. In REBOL these are called dialects. This makes them very optimal and flexible. If you think about it, this is very close to the actual design of html, each tag has a set of values you can edit... each having its own interface and supported sub contents.

Within Remark, what actually happens is that each custom tag becomes a snippet of REBOL code, just like it is within REBOL. If you replace the html accolades by square brackets, you can easily see where this is headed ;-).

When sensible and possible, custom tags base their evaluation on order-independent datatypes and block parsing. This makes tag interfaces obvious to any REBOL coder, and in fact, non REBOL coders can easily adapt to this very simple scheme. In any case, the remark rtag api provides easy conversion to REBOL dialect or string data when dealing with the tag contents, so there is no real reason to not use it.

When you are using tags from different authors, overall unity and design can be lessened, but this should not be to an issue if rtag authors follow the above guidelines.

Scalability and flexibility before raw speed:

Now don't be put off, single file parsing is quite fast. And indeed optimisations are possible if you do not use too much dynamic tags for the actual textual content.

Throughout the early stages of design, it was apparent that many of the design goals meant inherent or possible redundant parsing, or multiple levels of tag substitution. This can result in longer parse times if custom tags are used profusely, causing persitent reparsing, especially on large pages. In fact be carefull when creating your own tags... you CAN get infinitly recursing loops, if you return yourself, in the block of code.

Thus I decided to make speed less of a concern overall, in this first draft of the engine. Consequently, many design decisions might not be not completely optimal in regards to how fast they are. Some things might be improved, especially in the raw parsing algorythm, there might be better or smarter loops, but other things like the way tags self-identify, although slower than a simple select block, allow us to more easily create tags which are true self contained dialects.

Note that the later releases of REBOL have a virtual machine implementation, this might be used in a later version in an attempt to VASTLY improve performance

last updated: 16-Feb-2006/14:55:46-5:00