Web design course tutorial 4 : a simple introduction to m4
§ 4.1 Introduction to m4
Recall from Section § 1.1 the following diagram showing how
Emacs, Web pages, Ripway and Web browsers relate to one another.
The m4 language adds an additional layer of complexity to this
diagram:
The file extension name .hts was invented by me and stands for
H.T.M.L. m4 Source File. Despite adding one
additional layer of complexity to the Web design process, the m4
language is a useful tool to eliminate most of the tiresome repetitive work that is needed to build a complex Website. In the tutorials
that follow this one, you will learn how to use m4 cleverly to
achieve this goal. The m4 language is more widely applicable to
Websites then P.H.P., since m4 only requires a normal H.T.M.L. Web
server. If P.H.P. is supported by your Web host, then you probably
should use it as it is more powerful than m4, since P.H.P. renders
pages just before they are downloaded, rather than before they are
uploaded, which is the case for m4. The later rendering allows you
to do more things with P.H.P. than m4.
§ 4.2 Introduction to the archive
Here is a diagram showing the contents of the archive tutorial-4.tar.gz:
The above files have the following different purposes:
The files marked PAGE above are Web pages that you can
edit, rename, delete or copy.
The files marked SPECIAL PAGE above should
only be edited when you add, remove or rename pages or when you
edit the preferences for this Website.
The files marked SPECIAL SITE above should only be
edited when the name of your Website is changed or you wish to add
or remove a Website to the src folder.
The files marked READ ONLY above should only be edited
by advanced users. Novice users should not need to edit or even
look at these files.
As mentioned above, files ending with the .hts extension
are used to build H.T.M.L. files.
Files ending with the .m4 extension are m4 source files that
are used by the H.T.S. files.
Files ending with the .mk extension are files that
are used by the Makefiles.
§ 4.3 How to build the Website
§ 4.3.1 Step 1. Extracting the tarball
Question 4.1: Unzip the archive
file tutorial-4.tar.gz
using Winzip or the tar command for the purposes of completing
this tutorial.
§ 4.3.2 Step 2. Executing make m4 copy
Question 4.2: In Emacs, execute make m4 copy by pressing
Shift-F9 while you are in the folder tutorial-4/src or
tutorial-4/src/site. Executing make m4 copy is identical
to running make twice, firstly with make m4 and secondly with
make copy. The make m4 command runs the m4 preprocessor
on all of the *.hts source files in the folder src to
generate *.html files in the folder output. The command
make copy copies all of the images from the folder src to
the folder output.
Question 4.3: Look at the folder tutorial-4/output/site to see
that the Website has been built. There are two ways to do this.
The first way is using Emacs' dired mode (reached by pressing
Ctrl-f and selecting the folder you wish to look at and the
second way is to use Windows Explorer.
§ 4.3.3 Step 3. Opening a Web page in a Web browser
Question 4.4: In a Web browser open the file
tutorial-4/output/site/index.html and browse the site. If
you want to see what m4 has done to your hts source files, click
on View Source (Internet Explorer) or View Page Source (Mozilla Firefox) menu button, while looking at these pages. You will
see that m4 has added a lot of code for the navigation buttons at
the top and bottom of every page in the Website. The m4 language
has done this with a minimum of complexity in your .hts source
files.
§ 4.3.4 Step 4. Cleverness at navigating H.T.S. and H.T.M.L. files
Due to some cleverness invented by myself it is possible to easily
navigate between H.T.S. m4 source files and their resulting H.T.M.L. files
and the Web browser. The key F10 goes from H.T.S. files to H.T.M.L.
files and from there to showing the file in a Web browser. Conversely
the keys Ctrl-F10, Alt-F10 and Shift-F10 go in the
opposite direction from H.T.M.L. files to H.T.S. files. The following
diagram should explain how this works:
Question 4.5: Open the file tutorial-4/src/site/index.hts in
Emacs and locate the corresponding H.T.M.L. file by pressing F10.
Then go back to the H.T.S. file by pressing one of the following key
sequences: Ctrl-F10, Alt-F10 or Shift-F10.
§ 4.3.5 Step 5. Two safety systems for H.T.M.L. generated files
By default H.T.M.L. generated files from m4 H.T.S. source files are opened
in Emacs in read-only mode. This safety check is intended to
prevent accidental editing of H.T.M.L. generated files, as this is
usually a mistake. It is a mistake because any changes you make to
an H.T.M.L. generated file will be overwritten the next time you invoke
the command make m4. If you really want to edit such files,
simply press F7 and the file will become writable.
Another way that Emacs helps prevent you from editing H.T.M.L. generated
files is that the mode-line at the bottom of Emacs's screen appears
in the cyan colour for H.T.M.L.
generated files and in a different colour for other files.
§ 4.4 Other Makefile targets
§ 4.4.1 Executing make clean
This command deletes every file in the current output folder.
Question 4.6: Try executing make clean and then look at the
folder tutorial-4/output/site using Ctrl-f to see that it
is empty. Then rebuild the Website using make m4 copy and
look at the same folder to see that the Website has come back.
§ 4.4.2 Executing make tar
This command builds a time-stamped backup of the src folder
in the folder tutorial-4.
Question 4.7: Try executing make tar and then examine the
tar file src-YYYYMMDD-HHMMSS.tar.gz by pressing enter
on the file in Emacs dired or by clicking on the
archive in Windows.
§ 4.5 Editing pages
Question 4.8: Try making some simple customisations to the H.T.M.L. code
of the following files: cv.hts, index.hts,
photos.hts and stuff.hts. When you have made some
changes, save them and open them in a Web browser to verify that
your changes are correct.
§ 4.6 Simple customisations
The following questions in this section will guide you through the
process of customising the look of your Website. All of the
customisation code is located in the file
tutorial-4/src/site/index.m4.
Question 4.9: The symbol m4_menu_current_col defines the colour of
navigation button that represents the current page. Change it now and see what happens when you
execute make m4 and then load your Website into a Web browser.
Question 4.10: The symbols: m4_button_col_fglo,
m4_button_col_fghi, m4_button_col_bglo and m4_button_col_bghi
are used to define the colours of the navigation buttons that are
not the current page. Here is a task for you to do: invert
the colours so that background colours are black and the
foreground colours are not black. Change it now and see what happens when you
execute make m4 and then load your Website into a Web browser.
Question 4.11: The symbols: m4_bgcolor, m4_textcolor, m4_linkcolor and
m4_vlinkcolor define that values of the attributes to the <body>
tag. Specifically they define the screen colours of each H.T.M.L. Web
page. The first two define, respectively, the background and
foreground colours of the Web page. The second two define,
respectively, the colours of unfollowed links and followed links.
Change it now and see what happens when you
execute make m4 and then load your Website into a Web browser.
Question 4.12: The symbol m4_menu_face defines the font of
the navigation buttons. Change it now and see what happens when you
execute make m4 and then load your Website into a Web browser.
Question 4.13: The symbol m4_logo defines what appears in the logo
section above the navigation buttons. Feel free to attach an
<img> tag to this section. Change it now and see what happens when you
execute make m4 and then load your Website into a Web browser.
Question 4.14: The symbol m4_table_bgcolor defines the background
colour of the navigation menus at the top of the page. Change it now and see what happens when you
execute make m4 and then load your Website into a Web browser
Question 4.15: The symbols m4_table_bgcolor_light and
m4_table_bgcolor_dark define the colours surrounding the navigation
table. These symbols are only used my Microsoft Internet Explorer.
Mozilla calculates these values from the symbol m4_table_bgcolor.
Change it now and see what happens when you
execute make m4 and then load your Website into a Web browser.
Question 4.16: The symbol m4_copyright is used to set the copyright message at
the bottom of each page of your Website. Change it now and see what happens when you
execute make m4 and then load your Website into a Web browser.
§ 4.7 Customising pages
Question 4.17:
Rename some of the pages to pages that are appropriate for your needs.
For every page you rename, create or delete, you will need to adjust
the file index.m4. For every page that is not index.hts you
will need to add the following lines to the top of the file to
generate the <title> information and the navigation buttons at the
top of your page:
m4_include(m4_home/../readonly.m4)
m4_define([m4_title],Page Title Goes Here)
m4_begin_html
In the above code, note that .. refers to the parent folder of
m4_home. If you wish to suppress the generation of the page title
at the top of the page (like with index.hts), you will need to
undefine m4_show_title before calling m4_begin_html like so:
m4_undefine([m4_show_title])
You must also add the following lines to the bottom of the file, to
generate the navigation buttons and last modified time at the bottom
of your Web pages:
m4_end_html
If your Website has more than 4-6 pages, you will need to use the
newline function so that your menus are broken from one long
horizontal strip to multiple rows. Ask Davin for how to do this.
Question 4.18: Delete the page cv.hts. Remember to delete the
corresponding navigation button from index.m4.
Question 4.19: Add a new page greatest-artists.hts containing
a list of your favourite artists. Remember to add a navigation
button for this file to index.m4
§ 4.8 Customising content
Question 4.20: Once you have worked out how to customise pages, it
should be relatively easy to customise the content of those pages.
Any images that you add should be put in the source folder
tutorial-4/src/site/, which will be automatically copied to the
destination folder tutorial-4/output/site when you execute
make copy.
§ 4.9 Problematic characters for m4
If you need to have an open bracket ( without a matching closing
bracket ) then this will cause problems for m4's parsing
algorithm. In such cases you should use the H.T.M.L. special tags:
( for (
) for )
You might find the following macro definitions useful:
m4_define([BRA],()
m4_define([KET],))
where BRA stands for Bracket and KET stands for
Bracket.
Question 4.21: Using the BRA and KET macros, write some m4 code
to generate the following text:
( ( ( hello ) )
Question 4.22: † Tricky Write some m4 code to generate the
following text:
(((hello))
Note that you cannot use the BRA and KET macros for this
questions as there are no spaces between the symbols.
The square bracket characters in my version of m4 have special
meaning, you will find out more about this in the next tutorial.
For the meantime you should use the following H.T.M.L. special tags:
[ for [
] for ]
It is left as an exercise for the reader to define some sensible
macro abbreviations for these characters.
Question 4.23: † Tricky Write some m4 code to generate the following text:
[[[hello]]
The comma character is also problematic when used inside one or more
macro calls, because the comma character is used by m4 to separate
arguments. It seems natural to use the following macro definition:
m4_define([COMMA],,)
to define COMMA to be the H.T.M.L. Ascii code of the comma
character. But when you try and use it like so: "TomCOMMA Dick
and Harry" m4 fails to expand the COMMA macro because it
is joined to the word "Tom". Adding a space before the call to
the COMMA macro works well, but it causes m4 to insert a
space before the comma like so "Tom , Dick and Harry", which
looks ugly. Therefore the following macro definition is more
sensible:
m4_define([COMMA],$*,)
so that "COMMA(Tom) Dick and Harry" expands to the correct
result: "Tom, Dick and Harry". See Question 5.1 for
more information.
