6.8 Branch Sites

6.8.1 A Minimal Example

Directory examples-1.5/branch-site/ contains the following files:

File index.html:

<a href="main/toc.html">Main Version</a>
<a href="accessible/toc.html">Accessible Version</a>

File Makefile.cm:

*branch*main/*accessible/
cows-option:--define accessible
end-branch

File main/toc.cws:

<cows>

ifdef (accessible) {
  // A simple layout for visually impaired users
  // relying on speech synthesys
  print ("<p> Accessible version ...");
} else {
  // A more complex layout
  print ("<table> <tr> <td> Standard version ...");
}

</cows>

There are some interesting things to notice:

• index.html refers to file accessible/toc.html but there isn't a accessible/toc.cws source (nor even an accessible/ directory);

• source file main/toc.cws behaves differently according to variable accessible in such a way that you can create the different versions of this page with the following commands:

  cows main/toc.cws main/toc.html
  cows --define accessible main/toc.cws accessible/toc.html
  

In general, whenever two (or more) portions of your site share the same sources, place these common sources in a subdirectory (in this example: main/). Now, you need to tell Cows-mkgen that another directory (in this example: accessible/) must be created from the same sources with different command-line options. That's where Makefile.cm comes in help. It's very short - only three lines - but that's all Cows-mkgen need to know. A brief explanation follows:

Now, let's run Cows-mkgen and look at the generated makefile:

# Generated automatically from Makefile.cm by cows-mkgen 1.5
# Copyright (C) 2002, 2003, 2004, 2005 Andrea Sozzi
# This makefile is free software; you have unlimited
# permission to copy and/or distribute it, with or without
# modifications, as long as this notice is preserved.

# This makefile is distributed in the hope that it will be
# useful, but WITHOUT ANY WARRANTY, to the extent permitted
# by law; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.


prefix = ./

__cows_OPTS =
main_OPTS =
accessible_OPTS = --parents  --define accessible


TARGETS = $(prefix)main/toc.html\
$(prefix)accessible/toc.html\

all: $(TARGETS)

$(prefix)main/toc.html:   main/toc.cws
      cows $(__cows_OPTS) $(main_OPTS) main/toc.cws $(prefix)main/toc.html

$(prefix)accessible/toc.html:     main/toc.cws
      cows $(__cows_OPTS) $(accessible_OPTS) main/toc.cws $(prefix)accessible/toc.html


clean:
      rm -f $(TARGETS)

dist-noupdate:
      cd ../ && \
      tar chozf branch-site/branch-site.tar.gz \
      -X branch-site/Makefile.sources branch-site && \
      cd branch-site

dist: all dist-noupdate

sitedist: dist-noupdate



.PHONY: all clean dist dist-noupdate sitedist

As you can see, this makefile suits our needs since it generates both files main/toc.html and accessible/toc.html from the same source main/toc.cws. It also add -parents option when creating files within branch since we can't assume target directory (accessible/) exists (main/ must exist since that's where sources cames from).

Now, run make:

$ make
cows   ./main/toc.cws ./main/toc.html
cows  --parents --define accessible="" ./main/toc.cws ./accessible/toc.html

Everything seem to be right; let's look at the pages created by Cows.

File main/toc.html:

<table> <tr> <td> Standard version ...

File accessible/toc.html:

<p> Accessible version ...

6.8.2 Complete Syntax for Options Files

Follows a sample Makefile.cm; description is given in form of comments (lines beginning with #).

# --------------------------------------------------------------------
# First, options for Cows-mkgen;
# --------------------------------------------------------------------
# Some examples:
# brief:           corresponds to invoking cows-mkgen --brief
# prefix:foo/      corresponds to invoking cows-mkgen --prefix=foo/
# cows-option:-r   corresponds to invoking cows-mkgen --cows-option=-r
#
# Notice that options passed to Cows within this section will be used
# both in main/ site and in branch sites (if any)
# ---------------------------------------------------------------------

brief:
prefix:foo/
target-extension:htm
cows-option:--define common_var_1=V1
cows-option:--define common_var_2=V2
cows-option:--define common_var_2=V3

# --------------------------------------------------------------------
# Main site
# --------------------------------------------------------------------
# Sometimes, when using `branch sites', you want some options to be
# used ONLY within main site.
# This section begins with `*main' and ends with `end-main'
# --------------------------------------------------------------------

*main
cows-option:--define only_within_main
end-main

# --------------------------------------------------------------------
# Branch site: you need one of these sections for each branch
# --------------------------------------------------------------------
# Here, you place options needed for creating the branch
# This section begins with `*branch*<SOURCE-DIR>*<OUTPUT-DIR>' and
# ends with `end-branch'
# --------------------------------------------------------------------

*branch*main/*accessible/
cows-option:--define accessible_1
cows-option:--define accessible_2
end-branch

*branch*main/*another_version/
cows-option:--define another_version
end-branch