(Dr.R.K.) Web Paging - HTML macros

Go to Bottom Previous Next Go up one level To frames R.K.'s Home Page Keyword Index Site Map Help Linux
This page describes some of the m4 macros used for authoring the web pages in this site. The ones listed here are those that will be of most use in the ``content'' section of the web page, not the macros needed to work the underlying magic. The full macro implementation can be found in htm4 and associated files located at the root of this website. 
M4 macros      _TT            _H1            _H1_           _LI            _MARK          
images         _BOLD          _H2            _H2_           _OL            _PAGE          
symbols        _IT            _H3            _H3_           _UL            _URL           
slide howto    _UNDER         _H4            _H4_           _DIR           _IMAG          
               _CENTER        _H5            _H5_           _MENU          _ANONFTP       
               _SUB           _H6            _H6_                          _CGIBIN        
_EM            _SUP                                         _DL                           
_STRONG        _STRIKE        _HR            _BR            _DT            _MK            
_CODE          _BLINK         _P             _NOBR          _DD            _PG            
_SAMP          _BIG           _DIV           _WBR                          _GO            
_KBD           _SMALL                                                                     
_VAR                                                        _AMPER                        
_DFN           _BFS           _TABLE                        _NBSP          _QUOTE         
_CITE          _FS            _CAPTION                      _AMP           _COMMENT       
_PRE           _FC            _TR                           _LT            _C             
_ADDRESS       _FE            _TH                           _GT                           
_BLOCKQUOTE                   _TD                                                         
                                                                                          
                                                                                          
START_HTML     _OPT           _UP            _JS                                          
_LINK                         _ROOT                                                       
_REVISION                     _PIX                                                        
_RCSID         _SLIDE         _SYMB                                                       
_KEYWORD       _SPAGE         _UN_NL                                                      
END_HTML       _PRESENTATION

Note that to display the m4 macros here in this web page, the macros were ``disabled'' by inserting pairs of quotes (`') in the middle of the macro names, thus making them unrecognizable by the m4 preprocessor.

General macro form

The following macros are useful (and easier) implementations of many of the HTML tags. The general format for a HTML tag is
<TAG> enclosed text </TAG>
where the tag is case insensitive. Suppose the tag is ``TT'' then the enclosed text is displayed with Courier (typewriter) font by the web browser. If for some reason the ending tag is missing (or incorrectly spelled) then all text from that point on will be displayed in Courier font to the end of the web page. Making sure the closing tags are correct and properly placed can be a nuisance. The following macros alleviates this by using the m4 macro definition capabilities to define simple replacements of the form
_TAG(enclosed text)
However, the tag name is quite case sensitive and must be in UPPERCASE. Another advantage of this form is that many text editors (e.g. vi and emacs) have mechanisms for finding the matching parentheses. In vi entering the ``%'' while placed on a parentheses (``('' or ``)'') will move the cursor to the matching one. If one does not exist then the terminal will beep at you. I don't know what the emacs equivalent is since I view emacs as a bloated and crippling heresy.

Another form available for most of the text style tags closely matches the HTML tags format with a starting tag and a closing un-tag.

_TAG enclosed text _UNTAG
These may have an advantage when the enclosed text contains commas (,) which plays general havoc with m4 macros unless they're escaped to some level with quotes (@[]@).

Some tags allow optional arguments to be passed as in the following example:

_TAG(ARG=arguments) some more enclosed text _UNTAG
which results in
<TAG ARG=arguments> some more enclosed text </TAG>

For a small class of tags, another way is available to specify the optional arguments. This is for tags where the usual way is to specify ``_TAG(some enclosed text)'', but due to changes in the HTML standard the tag now allows options, usually for specifying alignment. The new format is to add somewhere within the argument.

_TAG(_OPT(ARG=arguments) some more enclosed text)
or
_TAG(_OPT(ARG=arguments)) some more enclosed text _UNTAG

m4 Built-in Macros

Some of the m4 built-in macros are common words like ``include'', ``define'' and as such may conflict with or confuse the text output. To prevent such occurences, all the m4 built-in macros have been renamed to UPPERCASE with a prepended underscore (_). Hence the two macros listed above become _INCLUDE and _DEFINE respectively.

One macro is treated special and that is the ``sinclude'' macro that performs a safe include. A regular macro _SINCLUDE is defined as well as ``sinclude'', which ``eats' its argument, outputs no text, and does nothing at all. The purpose of this is to allow the macro specification file to be specified on the commandline as well as included from within for the same results. Hence, 

m4 htm4 xxx.htm4 > xxx.html
should produce the same results as 
m4 xxx.htm4 > xxx.html
if xxx.htm4 performs an sinclude(html.lite) as its first line.

Logical styles formatting

_EM text _UNEM or _EM(text)
Emphasis (usually italics)
example text
_STRONG text _UNSTRONG or _STRONG(text)
Stronger emphasis (usually bold)
example text
_CODE text _UNCODE or _CODE(text)
Example of typed code (usually Courier TT font)
example text
_SAMP text _UNSAMP or _SAMP(text)
``sample'' text, a sequence of literal characters
example text
_KBD text _UNKBD or _KBD(text)
Text designated as ``keyboard'' input
example text
_VAR text _UNVAR or _VAR(text)
``variable'' name
example text
_DFN text _UNDFN or _DFN(text)
The defining instance of a term (often rendered in bold or bold italics)
example text
_CITE text _UNCITE or _CITE(text)
A citation (usually in italics)
example text
_PRE text _UNPRE or _PRE(text)
Preformatted text (usually in courier TT font) 
example text
_ADDRESS text _UNADDRESS or _ADDRESS(text)
Address block (usually in italics)
example text
_BLOCKQUOTE text _UNBLOCKQUOTE or _BLOCKQUOTE(text)
Block quote - indents text
example text

styles formatting

Use the Logical styles whenever possible
_TT text _UNTT or _TT(text)
Fixed width typewriter font (usually Courier)
example text
_BOLD text _UNBOLD or _BOLD(text)
Boldface font (or substitute)
example text
_IT text _UNIT or _IT(text)
Italics font
example text
_UNDER text _UNUNDER or _UNDER(text)
Underline (may be slanted instead)
example text
_CENTER text _UNCENTER or _CENTER(text)
Centers the block of text and images
example centered text
_SUB text _UNSUB or _SUB(text)
Puts text in a smaller font and placed below current line
regular textsubscript text
_SUP text _UNSUP or _SUP(text)
Puts text in a smaller font and placed above current line
regular textsuperscript text
_STRIKE text _UNSTRIKE or _STRIKE(text)
Prints text with a strike-through line
example text
_BLINK text _UNBLINK or _BLINK(text)
Prints annoying blinking text
_BLINK(example text)
_BIG text _UNBIG or _BIG(text)
Displays text in BIG font
example BIG text
_SMALL text _UNSMALL or _SMALL(text)
Displays text in small font
example small text
_BFS(size)
Sets the base-font size, if no argument then defaults to SIZE=3
example text made one size bigger and BIGGER
_FS(size) text _FE or _FS(size,text)
Sets the font size
example text made one size bigger and BIGGER
_FC(color) text _FE or _FC(color,text)
Sets the font color
patriotic example text
nested example text
_FE
Terminates _FS or _FC, but may need to be nested, one for each unterminated _FS & _FC

Header types

HTML allows for 6 levels of headings and are specified here with _H1 ... _H6. The headers are not indented, but the following text is. This is implemented via the <BLOCKQUOTE> tag.

The macros with the trailing `_' do not indent the following text.

_H1 text _UNH1 or _H1(text) can include _OPT
Header level 1

example text

follow on text (indented)
_H2 text _UNH2 or _H2(text) can include _OPT
Header level 2

example text

follow on text (indented)
_H3 text _UNH3 or _H3(text) can include _OPT
Header level 3

example text

follow on text (indented)
_H4 text _UNH4 or _H4(text) can include _OPT
Header level 4

example text

follow on text (indented)
_H5 text _UNH5 or _H5(text) can include _OPT
Header level 5
example text
follow on text (indented)
_H6 text _UNH6 or _H6(text) can include _OPT
Header level 6
example text
follow on text (indented)
_H1_ text _UNH1_ or _H1_(text) can include _OPT
Header level 1

example text

follow on text (non-indented)
_H2_ text _UNH2_ or _H2_(text) can include _OPT
Header level 2

example text

follow on text (non-indented)
_H3_ text _UNH3_ or _H3_(text) can include _OPT
Header level 3

example text

follow on text (non-indented)
_H4_ text _UNH4_ or _H4_(text) can include _OPT
Header level 4

example text

follow on text (non-indented)
_H5_ text _UNH5_ or _H5_(text) can include _OPT
Header level 5
example text
follow on text (non-indented)
_H6_ text _UNH6_ or _H6_(text) can include _OPT
Header level 6
example text
follow on text (non-indented)

Special Separators

These tags allow the text to be broken up in special ways.
_HR or _HR(options)
Breaks the text with a horizontal rule
_P or _P(options) (_UNP is optional)
Inserts a paragraph break in the text
_DIV(options) text _UNDIV or _DIV(options,text)
Places ``division'' in the text
_BR or _BR(options)
Breaks the text
_NOBR text _UNNOBR or _NOBR(text)
Prevents breaks in the text
_WBR
Defines a place where a line break can occur.
In a _NOBR section a _BR can be added after a _WBR

Table Tags

HTML has recently added tables as a useful way to organize & display text & data. For each of the tags you can optionally specify alignment, width, color, borders, etc. The closing _UNTAG is optional in most cases.
_TABLE or _TABLE(options) and _UNTABLE
Declares a table section. The _UNTABLE is required to finish the table
_CAPTION or _CAPTION(options) and _UNCAPTION
Specify the table caption
_TR or _TR(options) and optional _UNTR
Starts a table row
_TH or _TH(options) and optional _UNTH
Specify a table header cell
_TD or _TD(options) and optional _UNTD
Specify a table data cell

Various List Specifiers

These various tags allow the formatting of different types of lists. The list is started with a list specifier tag and must close with the matching tag (unless noted otherwise).
_LI or _LI(options) and optional _UNLI
Specifies a list item, the closing _UNLI is unnecessary. This tag is used only with _OL, _UL, _DIR, and _MENU.
_OL or _OL(options) and _UNOL
An ordered list
  1. first
  2. second
  3. third
_UL or _UL(options) and _UNUL
A bullet list
  • first
  • second
  • third
_DIR or _DIR(options) and _UNDIR
A directory list of short items
  • first
  • second
  • third
    • _MENU or _MENU(options) and _UNMENU
    A menu list
  • first
  • second
  • third
    • _DL or _DL(options) and _UNDL
    A Definition list - with a term, and its definition
    This whole page is an example of this
    _DT or _DT(options) and optional _UNDT
    Term being defined. This tag is used only with _DL.
    _DD or _DD(options) and optional _UNDD
    Definition of listed term. This tag is used only with _DL.

    Special Character Macros

    Special HTML characters are specified with ``&xxx;'', were xxx is the ID string for the special character. Only a few are widely used for the website and they are given special macros.
    _AMPER(text)
    ``Amperize'' the text. It performs all three of the ``amperizations'' listed below. (Useful for displaying code.)
    _AMPER(((a << 3) => 8) && (( b >> 1) < 4))
    _AMPER1(text)
    Converts ``&'' to ``&amp;''
    _AMPER2(text)
    Converts ``<'' to ``&lt;''
    _AMPER3(text)
    Converts ``>'' to ``&gt;''
    _NBSP
    Puts in a non-breaking space, this is useful for tables with borders where ordinary empty fields cause the table extend the border over the empty field.
    _AMP
    Puts in an ampersand ( &) in the HTML text.
    _LT
    Puts in an less-than ( <) in the HTML text.
    _GT
    Puts in an greater-than ( >) in the HTML text.

    Special web anchor macros

    The following macros are for ease of establishing URL ``NAME'' anchors or for jumping to other web pages within the scope of this site.

    Named Anchors

    A specific spot in a web page may be marked with the ``NAME'' attribute in an anchor. The typical form is
    <A NAME="anchor_id">some text</A>
    which marks ``some text'' with the name or id of ``anchor_id''. A link can be placed in the same document that references this spot with
    <A HREF="#anchor_id">something that relates to ``some text''</A>
    The text within the anchor will be highlighted in some color (typically blue) and clicking on it will immediately jump the browser to that point. If the reference is on another page, say, ``somepage.html'' then link to that specific point is made with
    <A HREF="somepage.html#anchor_id">something that relates to ``some text''</A>

    Special page marking & jumping macros

    These macros are useful for jumping within this website. The macros are designed such that the HTML file extensions are automatically added for maximum portability. The web page contents should not be tied to any specific file format (e.g. .html, .shtml, .htm, etc.).

    The following macros all have two arguments, the first references an URL, the second is the explanatory text that the URL is anchored to. If the text contains commas (,) or the following brackets (@[ ]@) then enclose the text in brackets @[ ]@, which are the m4 ``quotes'' for this implementation.

    _MARK ( anchor_id , some text )
    Marks ``some text'' with the anchor id ``anchor_id'' on the current page (see the above example)
    _PAGE ( #anchor_id , some text that relates to ``#anchor_id'' )
    Jumps to the ``anchor_id'' in this page
    _PAGE( somepage#anchor_id , something that relates to ``somepage#anchor_id'' )
    Jumps to the ``anchor_id'' in the ``somepage'' web page. Note that only the ``basename'' is given. Do not specify the extension (usually .html). This allows the macro package to automatically assign the correct extension which may differ from machine to machine
    _PAGE( somepage , something that relates to ``somepage'' )
    Jumps to the top of web page ``somepage'', and like above ... do not specify the extension

    Referencing other URLs & non-web pages

    These macros provide a mean to access other URLs, and also special URLs associated with this website.
    _URL ( some_url , something that relates to ``some_url'' [, optional <A> arguments for ``some_url''])
    Jumps to the given URL. If you don't know what these are ... you shouldn't be writing web pages!
    _IMAG ( some_imag [, optional <IMG> arguments for ``some_imag''])
    The purpose of this macro is to display images. The optional argument is usually ALT="xxx" where ``xxx'' is a text description of the image for non-graphical browsers (or people who turn off autoloading of graphics).
    _ANONFTP ( ftp_file , explanatory text related to ``ftp_file'' )
    The web pages are usually kept separate from the anonymous ftp site. This allow the website to specify, in a non-specific way, an associated file. Note that the ``basename'' of the file is given. The extension is specified by the default compression being used. All the anonymous ftp files must be compressed in the same way. If ``ftp_file'' is not specified then it refers to the website's anonymous ftp ``root'' directory.
    Note that many internet service providers are disabling anonymous ftp; however, files can still be transfered by using the http: protocol and directing the user to use the browser ``File / Save As'' menu.
    _CGIBIN ( cgi_bin , explanatory text invoking the ``cgi_bin'' )
    The web pages are usually kept separate from the CGI-BIN executables. This allow the website to specify, in a non-specific way, an associated CGI-BIN script or executable. (not implemented yet.)

    Macro short cuts

    The following macros are short cuts for some of the above macros. They all have a single argument, thus the URL and the ``text'' must refer to the same thing. (This isn't as hard as you think.) The only provision is that these macros must be the ``inner'' most macro else it will have unintentional results (e.g. _H2(_MK(header)) ).
    _MK ( mark )
    Same as _MARK ( mark , mark )
    _PG ( page )
    Same as _PAGE ( page , page )
    _GO ( thispagemark )
    Same as _PAGE ( #thispagemark , thispagemark )

    Commenting capability

    There aren't too many ways to comment your m4 or HTML sources. These few macros are about it.
    _QUOTE and _UNQUOTE
    eliminates and restores the m4 quoting mechanism. This was mostly useful for displaying C-code. However, there may be unforeseen problems if used indiscriminately, particularly if there are any website macro calls contained within, since they rely heavily on this quoting mechanism.

    This feature was more important, when this package was developed on a system with only a single-character quoting mechanism. At that time the quote characters were [ & ], the quote characters now are @[]@, which aren't too likely to be used anywhere except here.

    _COMMENT and _UNCOMMENT
    Causes the m4 text to be diverted to oblivion. This is good for ``commenting out sections of m4 code, which do not appear in the HTML text at all.
    _C text _UNC or _C(text)
    This is an HTML commenting feature. The enclosed does not appear in the displayed text, but is within the HTML sources. This produces source text that looks like this:
    <!-- text -->

    Miscellaneous web page macros

    These are some of the web page macros that don't neatly fall into a specific category. They can be very helpful though.
    _UP ( number_levels )
    Provides a ``short cut'' to refer to upper directory levels. The following _UP(DIR_LEVEL) refers to the root directory for this website. The good reason for using this macro is to shield this web page from future changes to the directory structure.
    _ROOT ( file_path )
    This is the short cut refered to above, but in a more formal way. To refer to the howto/index web page relative the website root: _ROOT(howto/index)
    _PIX ( pix_file )
    This short cut is the same as _ROOT(images/pix_file) and used for ``shared'' images and symbols. This is generally used in _IMAG. However, use the predefined image macros whenever possible.
    _SYMB ( symbol_file [ , optional <IMG> arguments] )
    This short cut gives easy access to the special symbol images in the _ROOT(images/symbols/) directory and is used for displaying ``special'' symbols.
    _UN_NL ( string )
    Converts new-lines to spaces in the given string.
    _JS ( JavaScript text )
    Include JavaScript code.

    HTML page structure macros

    The following macros are essential for this implementation, and as such are automatically included via the template file. If you use the template file just search for the string ``xxx'' and edit appropriately. The following macros are listed in the order they appear in the template file.
    START_HTML ( _SUBTITLE( title ), up_page , this_page , time_stamp )
    This is the very important starting macro that sets up the web page and initializes the page data.
    • title is the title for the current web page. This is title is usually displayed in the X-window frame or in the browser title line. Note that _SUBTITLE is usually defined in the .level file.
    • up_page is the web page that refers to the referencing web page (Note the this web page structure is viewed as a tree structure). Do not specify the web page extension. If there is no up-page (hence this is the root page) put ``NULL'' instead.
    • this_page is the basename for this web page (no file extension). You think that the macro package should be able to determine this, but it's harder than you think ... and you don't want to be changing the web page name on the fly anyways, because it will screw up the other pages that refer to it.
    • time_stamp is the current date & time stamp. Usually this is provided by the revision control system (RCS).
    _LINK ( previous , next )@[]@_DNL
    This is placed immediately before the START_HTML macro and is optional. It provides links to the previous and next logical web page in a series of web pages. If at the beginning or end of a sequence of web pages use ``NULL'' to denote a terminal point.
    _REVISION ( version )
    an internal macro for tracking the page version via RCS. Note that this is inside an HTML comment and does not get viewed
    _RCSID ( id )
    an internal macro for the page id via RCS. Note that this is inside an HTML comment and does not get viewed
    _KEYWORD ( key_words )
    This is one of the most important macros, which gives the informational glue. key_words is a list of keywords delimited by whitespace. They should be simple, concise & descriptive. It's probably a good idea to review the current set of keywords. The _KEYWORD macro must not be embedded within another macro. The _KEYWORD macro may be placed in multiple places within the web page. This is especially useful for longer web pages.
    END_HTML
    This closing macro has no arguments and does the clean-up and output of the web page and auxiliary files.

    Optional Arguments

    As the HTML standard evolves, tags that were once accepted become obsolescent or deprecated. Other tags gain new meaning or added options. The m4 macros can shield users from some of changes by just making changes ``under the hood''. However, they can't predict future capabilities. For this reason the _OPT was developed specifically to easily add optional arguments to the header tags. The HTML form is given above as well as the _OPT form. However, note that the _OPT macro should not be protected by any quoting (@[]@) because it needs to be interpreted before the outer enclosing macro.

    For example:

    _H3(_OPT(ALIGN=center) Centered Title or Section)
    yields:

    Centered Title or Section

    Slide Making Macros

    The concept of slides is to provide a visual aid to help an oral presentation. Generally, each slide briefly lists the main ideas, usually with ``bullets'', and are presented one after another. You may want to skip over or redisplay some slides at times. The downside of slides is that the information content on each slide is limited and scant. Also, a hard-copy version is just a copy of the slides with a lot of wasted space.

    Most people use some high-powered application like FrameMaker or PowerPoint for creating slides. The resulting slides are output to a laser printer for hardcopy or on special transparency material. These transparencies are then placed on an overhead projector.

    A computer with some sort of projection system or LCD panel provides a good alternative. (It also allows you to change things even upto 5 minutes before the presentation.) The web browser provides an ideal medium for displaying slides along with the side-benefit that the information can be posted for all to access. The methods I've seen for transfering slides from one of these applications usually just creates a GIF file or PostScript file of each slide and tacks on some HTML front-end to display each image. The obvious disadvantages are the high network bandwidth required for each image and lack of text searching capabilities.

    This macro package allows for slides to be ``easily'' created and processed. The advantages are:

    View the slide tutorial for an example of slides and a ``howto'', or look at the slide collection.

    _SLIDE
    This is placed immediately before the START_HTML macro to signify that this is a slide web page. (This triggers the macro package to do special things.)
    _SPAGE ( anchor , ``some text'' )
    Jumps to the ``anchor'' in this page, it follows the same syntax as _PAGE but is only for referencing other slide web pages.
    _PRESENTATION
    Placed in the .level file to signal that ``presentation'' quality colors are to be used for the slides.
    Last Modified:
    Go to Top Previous Next Go up one level To frames R.K.'s Home Page Keyword Index Site Map Help Linux
    Brought to you by: R.K. Owen,Ph.D.
    This page is http://owen.sj.ca.us/rkowen/howto/webpaging/macros.html