CML Reference Guide

Chapter 3:  What's in a CML page?


Each CML page (or file) describes a page that will appear on the user's Web browser.  (In some cases it just produces an HTTP "Location" directive which points in turn to another CML or HTML file.)  CML can be thought of as a superset of HTML.  More precisely, HTML is embedded in CML scripts; swebs does not actually understand or parse the HTML codes.  A CML page contain five kinds of text:

  1. Comments.  In the Unix tradition, all lines beginning with "#" are comments and are ignored.  Entirely blank lines are also ignored.

  2. HTML code.  All lines beginning with a double quote (") are parsed for CML functions and macros, but are otherwise passed on to the browser unchanged.  (The quote is removed.)  There may be leading blanks before the quote; they are ignored.

  3. CML functions.  Strings of the form $xyz(), $xyz(value), or $(value) are parsed by swebs, and replaced by the appropriate Caucus values.

  4. CML macros.  Strings of the form %abc(args) are macro invocations, and are expanded by swebs.  See CML macro definitions and expansions for more information.

  5. CML directives.  Directives are like C program code: they describe actions to be taken.  Directives start with one of the keywords "if", "elif", "else", "for", "count", "while", "set", "include", "return", "quit", "break", or "end".

A single logical line in a CML file may be broken across several physical lines; a "\" as the last character means "continued on next (physical) line".  Most of the time this is not needed, since HTML mostly ignores line boundaries.  However, the "\" is useful for assembling long lines that will appear inside HTML <PRE> code, or to improve readability of the CML code.

Here's a sample CML page, typical of a page a Web Caucus user would see early on:

#---CENTER.CML.   "Caucus Center" Page.
#   Overview of (and initial entry to) conferences.

if $empty ($(href))
   include $cml_dir()/startup.i center.cml

set nch $unique()
set nxt $page_save (1 center.cml \
              $arg(2)+$arg(3)+$arg(4)+$arg(5)+$arg(6)+$arg(7)+$arg(8) \
              # $(center_name) )
set last_conf x

#---HTML declaration, header, and BODY tag.
"Content-type: text/html

"<BODY $(body_bg) >

#---Caucus header.
include $(dir)/header.i

#---Tell the user what this page is about.
"<TD><FONT SIZE=+1><B>Caucus Center</B></FONT></TD>
"<TD ALIGN=right>
   include $(dir)/youare.i

"From here, you may go to specific conferences, or 
"<A HREF="$(href)/allconfs.cml?$(nch)+$(nxt)+x+x+x+x+x+x">
"see a list of <B>all</B> conferences</A> on this host.

#---Prepare to actually put up various kinds of links to the
#   conferences.  Create some variables with lists of 
#   conference names.  Apply $cl_list() to the entire list
#   of conferences.
#     L_CONFS are the "popular" conferences.
#     M_CONFS are from the user's personal conference list
set l_confs $file($(inc)/l_confs.i)
set m_confs $user_var($userid() my_confs)
set ignore  $cl_list ( $(l_confs) $(m_confs) )

#---The various ways of getting to the conferences all appear
#   as numbered entries, within one large table.
#   To avoid unpleasant spacing, and because the "JOIN" choice requires
#   being in a <FORM>, the entire table must be inside a <FORM>.
"<FORM METHOD=POST ACTION="$(href)/centerf.cml?$(nch)+$(nxt)" NAME="joiner">


#---Personal conference list access:
set way_in 1
include $(dir)/cen_pers.i $(way_in)

#---"Popular" conference access:
if $sizeof ($(l_confs))
   include $(dir)/cen_pop.i way_in

#---Type a conference name directly:
set way_in $plus ($(way_in) 1)
include $(dir)/cen_type.i $(way_in)

#---See a list of all conferences:
#set way_in $plus ($(way_in) 1)
#include $(dir)/cen_all.i $(way_in)


include $(dir)/cen_adv.i