zlax/ljr
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

init

Browse Source
This commit is contained in:
ivan
2019-02-06 00:49:12 +03:00
commit 8dbb1bb605
4796 changed files with 506072 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
bml/doc/docbook/BUILD.txt Executable file
View File

@@ -0,0 +1,5 @@
To build the BML documentation from these DocBook sources, you'll need
apidoc.pl from wcmtools here, and then run generate.pl.
FIXME: better notes

450
bml/doc/docbook/appx.gfdl.xml Executable file
View File

@@ -0,0 +1,450 @@
<appendix id="appx.gfdl">
<title>GNU Free Documentation License</title>
<!-- - GNU Project - Free Software Foundation (FSF) -->
<!-- LINK REV="made" HREF="mailto:webmasters@gnu.org" -->
<!-- sect1>
<title>GNU Free Documentation License</title -->
<para>Version 1.1, March 2000</para>
<blockquote>
<para>Copyright (C) 2000 Free Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.</para>
</blockquote>
<sect1 id="appx.gfdl-0">
<title>PREAMBLE</title>
<para>The purpose of this License is to make a manual, textbook,
or other written document "free" in the sense of freedom: to
assure everyone the effective freedom to copy and redistribute it,
with or without modifying it, either commercially or
noncommercially. Secondarily, this License preserves for the
author and publisher a way to get credit for their work, while not
being considered responsible for modifications made by
others.</para>
<para>This License is a kind of "copyleft", which means that
derivative works of the document must themselves be free in the
same sense. It complements the GNU General Public License, which
is a copyleft license designed for free software.</para>
<para>We have designed this License in order to use it for manuals
for free software, because free software needs free documentation:
a free program should come with manuals providing the same
freedoms that the software does. But this License is not limited
to software manuals; it can be used for any textual work,
regardless of subject matter or whether it is published as a
printed book. We recommend this License principally for works
whose purpose is instruction or reference.</para>
</sect1>
<sect1 id="appx.gfdl-1">
<title>APPLICABILITY AND DEFINITIONS</title>
<para>This License applies to any manual or other work that
contains a notice placed by the copyright holder saying it can be
distributed under the terms of this License. The "Document",
below, refers to any such manual or work. Any member of the
public is a licensee, and is addressed as "you".</para>
<para>A "Modified Version" of the Document means any work
containing the Document or a portion of it, either copied
verbatim, or with modifications and/or translated into another
language.</para>
<para>A "Secondary Section" is a named appendix or a front-matter
section of the Document that deals exclusively with the
relationship of the publishers or authors of the Document to the
Document's overall subject (or to related matters) and contains
nothing that could fall directly within that overall subject.
(For example, if the Document is in part a textbook of
mathematics, a Secondary Section may not explain any mathematics.)
The relationship could be a matter of historical connection with
the subject or with related matters, or of legal, commercial,
philosophical, ethical or political position regarding
them.</para>
<para>The "Invariant Sections" are certain Secondary Sections
whose titles are designated, as being those of Invariant Sections,
in the notice that says that the Document is released under this
License.</para>
<para>The "Cover Texts" are certain short passages of text that
are listed, as Front-Cover Texts or Back-Cover Texts, in the
notice that says that the Document is released under this
License.</para>
<para>A "Transparent" copy of the Document means a
machine-readable copy, represented in a format whose specification
is available to the general public, whose contents can be viewed
and edited directly and straightforwardly with generic text
editors or (for images composed of pixels) generic paint programs
or (for drawings) some widely available drawing editor, and that
is suitable for input to text formatters or for automatic
translation to a variety of formats suitable for input to text
formatters. A copy made in an otherwise Transparent file format
whose markup has been designed to thwart or discourage subsequent
modification by readers is not Transparent. A copy that is not
"Transparent" is called "Opaque".</para>
<para>Examples of suitable formats for Transparent copies include
plain ASCII without markup, Texinfo input format, LaTeX input
format, SGML or XML using a publicly available DTD, and
standard-conforming simple HTML designed for human modification.
Opaque formats include PostScript, PDF, proprietary formats that
can be read and edited only by proprietary word processors, SGML
or XML for which the DTD and/or processing tools are not generally
available, and the machine-generated HTML produced by some word
processors for output purposes only.</para>
<para>The "Title Page" means, for a printed book, the title page
itself, plus such following pages as are needed to hold, legibly,
the material this License requires to appear in the title page.
For works in formats which do not have any title page as such,
"Title Page" means the text near the most prominent appearance of
the work's title, preceding the beginning of the body of the
text.</para>
</sect1>
<sect1 id="appx.gfdl-2">
<title>VERBATIM COPYING</title>
<para>You may copy and distribute the Document in any medium,
either commercially or noncommercially, provided that this
License, the copyright notices, and the license notice saying this
License applies to the Document are reproduced in all copies, and
that you add no other conditions whatsoever to those of this
License. You may not use technical measures to obstruct or
control the reading or further copying of the copies you make or
distribute. However, you may accept compensation in exchange for
copies. If you distribute a large enough number of copies you
must also follow the conditions in section 3.</para>
<para>You may also lend copies, under the same conditions stated
above, and you may publicly display copies.</para>
</sect1>
<sect1 id="appx.gfdl-3">
<title>COPYING IN QUANTITY</title>
<para>If you publish printed copies of the Document numbering more
than 100, and the Document's license notice requires Cover Texts,
you must enclose the copies in covers that carry, clearly and
legibly, all these Cover Texts: Front-Cover Texts on the front
cover, and Back-Cover Texts on the back cover. Both covers must
also clearly and legibly identify you as the publisher of these
copies. The front cover must present the full title with all
words of the title equally prominent and visible. You may add
other material on the covers in addition. Copying with changes
limited to the covers, as long as they preserve the title of the
Document and satisfy these conditions, can be treated as verbatim
copying in other respects.</para>
<para>If the required texts for either cover are too voluminous to
fit legibly, you should put the first ones listed (as many as fit
reasonably) on the actual cover, and continue the rest onto
adjacent pages.</para>
<para>If you publish or distribute Opaque copies of the Document
numbering more than 100, you must either include a
machine-readable Transparent copy along with each Opaque copy, or
state in or with each Opaque copy a publicly-accessible
computer-network location containing a complete Transparent copy
of the Document, free of added material, which the general
network-using public has access to download anonymously at no
charge using public-standard network protocols. If you use the
latter option, you must take reasonably prudent steps, when you
begin distribution of Opaque copies in quantity, to ensure that
this Transparent copy will remain thus accessible at the stated
location until at least one year after the last time you
distribute an Opaque copy (directly or through your agents or
retailers) of that edition to the public.</para>
<para>It is requested, but not required, that you contact the
authors of the Document well before redistributing any large
number of copies, to give them a chance to provide you with an
updated version of the Document.</para>
</sect1>
<sect1 id="appx.gfdl-4">
<title>MODIFICATIONS</title>
<para>You may copy and distribute a Modified Version of the
Document under the conditions of sections 2 and 3 above, provided
that you release the Modified Version under precisely this
License, with the Modified Version filling the role of the
Document, thus licensing distribution and modification of the
Modified Version to whoever possesses a copy of it. In addition,
you must do these things in the Modified Version:</para>
<orderedlist numeration="upperalpha">
<listitem><para>Use in the Title Page
(and on the covers, if any) a title distinct from that of the
Document, and from those of previous versions (which should, if
there were any, be listed in the History section of the
Document). You may use the same title as a previous version if
the original publisher of that version gives permission.</para>
</listitem>
<listitem><para>List on the Title Page,
as authors, one or more persons or entities responsible for
authorship of the modifications in the Modified Version,
together with at least five of the principal authors of the
Document (all of its principal authors, if it has less than
five).</para>
</listitem>
<listitem><para>State on the Title page
the name of the publisher of the Modified Version, as the
publisher.</para>
</listitem>
<listitem><para>Preserve all the
copyright notices of the Document.</para>
</listitem>
<listitem><para>Add an appropriate
copyright notice for your modifications adjacent to the other
copyright notices.</para>
</listitem>
<listitem><para>Include, immediately
after the copyright notices, a license notice giving the public
permission to use the Modified Version under the terms of this
License, in the form shown in the Addendum below.</para>
</listitem>
<listitem><para>Preserve in that license
notice the full lists of Invariant Sections and required Cover
Texts given in the Document's license notice.</para>
</listitem>
<listitem><para>Include an unaltered
copy of this License.</para>
</listitem>
<listitem><para>Preserve the section
entitled "History", and its title, and add to it an item stating
at least the title, year, new authors, and publisher of the
Modified Version as given on the Title Page. If there is no
section entitled "History" in the Document, create one stating
the title, year, authors, and publisher of the Document as given
on its Title Page, then add an item describing the Modified
Version as stated in the previous sentence.</para>
</listitem>
<listitem><para>Preserve the network
location, if any, given in the Document for public access to a
Transparent copy of the Document, and likewise the network
locations given in the Document for previous versions it was
based on. These may be placed in the "History" section. You
may omit a network location for a work that was published at
least four years before the Document itself, or if the original
publisher of the version it refers to gives permission.</para>
</listitem>
<listitem><para>In any section entitled
"Acknowledgements" or "Dedications", preserve the section's
title, and preserve in the section all the substance and tone of
each of the contributor acknowledgements and/or dedications
given therein.</para>
</listitem>
<listitem><para>Preserve all the
Invariant Sections of the Document, unaltered in their text and
in their titles. Section numbers or the equivalent are not
considered part of the section titles.</para>
</listitem>
<listitem><para>Delete any section
entitled "Endorsements". Such a section may not be included in
the Modified Version.</para>
</listitem>
<listitem><para>Do not retitle any
existing section as "Endorsements" or to conflict in title with
any Invariant Section.</para>
</listitem>
</orderedlist>
<para>If the Modified Version includes new front-matter sections
or appendices that qualify as Secondary Sections and contain no
material copied from the Document, you may at your option
designate some or all of these sections as invariant. To do this,
add their titles to the list of Invariant Sections in the Modified
Version's license notice. These titles must be distinct from any
other section titles.</para>
<para>You may add a section entitled "Endorsements", provided it
contains nothing but endorsements of your Modified Version by
various parties--for example, statements of peer review or that
the text has been approved by an organization as the authoritative
definition of a standard.</para>
<para>You may add a passage of up to five words as a Front-Cover
Text, and a passage of up to 25 words as a Back-Cover Text, to the
end of the list of Cover Texts in the Modified Version. Only one
passage of Front-Cover Text and one of Back-Cover Text may be
added by (or through arrangements made by) any one entity. If the
Document already includes a cover text for the same cover,
previously added by you or by arrangement made by the same entity
you are acting on behalf of, you may not add another; but you may
replace the old one, on explicit permission from the previous
publisher that added the old one.</para>
<para>The author(s) and publisher(s) of the Document do not by
this License give permission to use their names for publicity for
or to assert or imply endorsement of any Modified Version.</para>
</sect1>
<sect1 id="appx.gfdl-5">
<title>COMBINING DOCUMENTS</title>
<para>You may combine the Document with other documents released
under this License, under the terms defined in section 4 above for
modified versions, provided that you include in the combination
all of the Invariant Sections of all of the original documents,
unmodified, and list them all as Invariant Sections of your
combined work in its license notice.</para>
<para>The combined work need only contain one copy of this
License, and multiple identical Invariant Sections may be replaced
with a single copy. If there are multiple Invariant Sections with
the same name but different contents, make the title of each such
section unique by adding at the end of it, in parentheses, the
name of the original author or publisher of that section if known,
or else a unique number. Make the same adjustment to the section
titles in the list of Invariant Sections in the license notice of
the combined work.</para>
<para>In the combination, you must combine any sections entitled
"History" in the various original documents, forming one section
entitled "History"; likewise combine any sections entitled
"Acknowledgements", and any sections entitled "Dedications". You
must delete all sections entitled "Endorsements."</para>
</sect1>
<sect1 id="appx.gfdl-6">
<title>COLLECTIONS OF DOCUMENTS</title>
<para>You may make a collection consisting of the Document and
other documents released under this License, and replace the
individual copies of this License in the various documents with a
single copy that is included in the collection, provided that you
follow the rules of this License for verbatim copying of each of
the documents in all other respects.</para>
<para>You may extract a single document from such a collection,
and distribute it individually under this License, provided you
insert a copy of this License into the extracted document, and
follow this License in all other respects regarding verbatim
copying of that document.</para>
</sect1>
<sect1 id="appx.gfdl-7">
<title>AGGREGATION WITH INDEPENDENT WORKS</title>
<para>A compilation of the Document or its derivatives with other
separate and independent documents or works, in or on a volume of
a storage or distribution medium, does not as a whole count as a
Modified Version of the Document, provided no compilation
copyright is claimed for the compilation. Such a compilation is
called an "aggregate", and this License does not apply to the
other self-contained works thus compiled with the Document, on
account of their being thus compiled, if they are not themselves
derivative works of the Document.</para>
<para>If the Cover Text requirement of section 3 is applicable to
these copies of the Document, then if the Document is less than
one quarter of the entire aggregate, the Document's Cover Texts
may be placed on covers that surround only the Document within the
aggregate. Otherwise they must appear on covers around the whole
aggregate.</para>
</sect1>
<sect1 id="appx.gfdl-8">
<title>TRANSLATION</title>
<para>Translation is considered a kind of modification, so you may
distribute translations of the Document under the terms of section
4. Replacing Invariant Sections with translations requires
special permission from their copyright holders, but you may
include translations of some or all Invariant Sections in addition
to the original versions of these Invariant Sections. You may
include a translation of this License provided that you also
include the original English version of this License. In case of
a disagreement between the translation and the original English
version of this License, the original English version will
prevail.</para>
</sect1>
<sect1 id="appx.gfdl-9">
<title>TERMINATION</title>
<para>You may not copy, modify, sublicense, or distribute the
Document except as expressly provided for under this License. Any
other attempt to copy, modify, sublicense or distribute the
Document is void, and will automatically terminate your rights
under this License. However, parties who have received copies, or
rights, from you under this License will not have their licenses
terminated so long as such parties remain in full
compliance.</para>
</sect1>
<sect1 id="appx.gfdl-10">
<title>FUTURE REVISIONS OF THIS LICENSE</title>
<para>The Free Software Foundation may publish new, revised
versions of the GNU Free Documentation License from time to time.
Such new versions will be similar in spirit to the present
version, but may differ in detail to address new problems or
concerns. See <ulink
url="http://www.gnu.org/copyleft/">http://www.gnu.org/copyleft/</ulink>.</para>
<para>Each version of the License is given a distinguishing
version number. If the Document specifies that a particular
numbered version of this License "or any later version" applies to
it, you have the option of following the terms and conditions
either of that specified version or of any later version that has
been published (not as a draft) by the Free Software Foundation.
If the Document does not specify a version number of this License,
you may choose any version ever published (not as a draft) by the
Free Software Foundation.</para>
</sect1>
<sect1 id="appx.gfdl-11">
<title>How to use this License for your documents</title>
<para>To use this License in a document you have written, include
a copy of the License in the document and put the following
copyright and license notices just after the title page:</para>
<blockquote><para>
Copyright (c) YEAR YOUR NAME.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1
or any later version published by the Free Software Foundation;
with the Invariant Sections being LIST THEIR TITLES, with the
Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
A copy of the license is included in the section entitled "GNU
Free Documentation License".
</para></blockquote>
<para>If you have no Invariant Sections, write "with no Invariant
Sections" instead of saying which ones are invariant. If you have
no Front-Cover Texts, write "no Front-Cover Texts" instead of
"Front-Cover Texts being LIST"; likewise for Back-Cover
Texts.</para>
<para>If your document contains nontrivial examples of program
code, we recommend releasing these examples in parallel under your
choice of free software license, such as the GNU General Public
License, to permit their use in free software.</para>
</sect1>
</appendix>

35
bml/doc/docbook/book.ent Executable file
View File

@@ -0,0 +1,35 @@
<!ENTITY bml.book SYSTEM "book.xml">
<!ENTITY bml.index SYSTEM "index.xml">
<!ENTITY bml.bookinfo SYSTEM "bookinfo.xml">
<!ENTITY bml.preface SYSTEM "preface.xml">
<!ENTITY bml.api.ref SYSTEM "api.gen.xml">
<!ENTITY bml.flags SYSTEM "flags.xml">
<!ENTITY bml.core SYSTEM "core.xml">
<!ENTITY bml.tutorial SYSTEM "tutorial.xml">
<!ENTITY appx.gfdl SYSTEM "appx.gfdl.xml">
<!ENTITY bml.legalnotice "
<legalnotice>
<para>
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version
1.1 or any later version published by the Free Software
Foundation; with no invariant sections, nor Front-Cover/Back-Cover
Texts.
A copy of the license is included in <xref linkend='appx.gfdl'/>
</para>
</legalnotice>
">
<!ENTITY bml.copyright '
<copyright>
<year>1997</year>
<year>1998</year>
<year>1999</year>
<year>2000</year>
<year>2001</year>
<year>2002</year>
<holder><ulink url="http://www.bradfitz.com/">Brad Fitzpatrick</ulink></holder>
</copyright>
'>

15
bml/doc/docbook/book.xml Executable file
View File

@@ -0,0 +1,15 @@
<?xml version="1.0"?>
<!DOCTYPE book SYSTEM "/usr/share/sgml/docbook/dtd/xml/4.1.2/docbookx.dtd" [
<!ENTITY % book SYSTEM "book.ent">
%book;
<!ENTITY id.prepend "">
]>
<book id="index">
&bml.bookinfo;
&bml.preface;
&bml.tutorial;
&bml.flags;
&bml.core;
&bml.api.ref;
&appx.gfdl;
</book>

35
bml/doc/docbook/bookinfo.xml Executable file
View File

@@ -0,0 +1,35 @@
<bookinfo>
<title>The Better Markup Language</title>
<titleabbrev><abbrev>BML</abbrev></titleabbrev>
<edition>BML Manual Version 1.0</edition>
<abstract>
<para>
Anyone's who's ever put together a large website or done a lot of server-side
programming will know how hard and annoying it is to keep a consistent look
through a site, and how painful it is to go back and change something globally
later, once their site is up. In addition, looking at <abbrev>HTML</abbrev>
code is ugly and <abbrev>HTML</abbrev> editors don't always do what you want them to.
</para>
<para>
<abbrev>BML</abbrev> was designed to address a lot of these problems.
<abbrev>BML</abbrev> is a server-side markup language that lets you define your own
<abbrev>BML</abbrev> blocks and use them as templates within your <abbrev>BML</abbrev> pages.
Your templates don't even have to be static. Because <abbrev>BML</abbrev> pages are
converted to <abbrev>HTML</abbrev> on the server when users request them, this also
enables you to embed live code within your <abbrev>BML</abbrev> pages, just like a
<abbrev>CGI</abbrev> script.
</para>
<para>
A lot is possible using <abbrev>BML</abbrev>. Whether you want to make a full blown
database driven website, enable a little dynamic content on your site, or just
make things on your site easier to maintain, <abbrev>BML</abbrev> can really help out.
</para>
<para>
The official website for <abbrev>BML</abbrev> is located at <ulink url="http://www.bradfitz.com/bml" />.
</para>
</abstract>
&bml.copyright;
&bml.legalnotice;
</bookinfo>
<title>The Better Markup Language</title>
<titleabbrev><abbrev>BML</abbrev></titleabbrev>

88
bml/doc/docbook/build.pl Executable file
View File

@@ -0,0 +1,88 @@
#!/usr/bin/perl
#
use strict;
use Getopt::Long;
my $XSL_VERSION_RECOMMENDED = "1.45";
my $opt_clean;
my ($opt_myxsl, $opt_getxsl);
exit 1 unless GetOptions('clean' => \$opt_clean,
'myxsl' => \$opt_myxsl,
'getxsl' => \$opt_getxsl,
);
my $home = $ENV{'LJHOME'};
require "$home/cgi-bin/ljlib.pl";
$ENV{'SGML_CATALOG_FILES'} = $LJ::CATALOG_FILES || "/usr/share/sgml/docbook/dtd/xml/4.1/docbook.cat";
unless (-e $ENV{'SGML_CATALOG_FILES'}) {
die "Catalog files don't exist. Either set \$LJ::CATALOG_FILES, install docbook-xml (on Debian), or symlink $ENV{'SGML_CATALOG_FILES'} to XML DocBook 4.1's docbook.cat.";
}
if ($opt_getxsl) {
chdir "$home/doc/raw/build" or die "Where is build dir?";
unlink "xsl-docbook.tar.gz";
my $fetched = 0;
my $url = "http://www.livejournal.org/misc/xsl-docbook.tar.gz";
my @fetcher = ([ 'wget', "wget $url", ],
[ 'lynx', "lynx -source $url > xsl-docbook.tar.gz", ],
[ 'GET', "GET $url > xsl-docbook.tar.gz", ]);
foreach my $fet (@fetcher) {
next if $fetched;
print "Looking for $fet->[0] ...\n";
next unless `which $fet->[0]`;
print "RUNNING: $fet->[1]\n";
system($fet->[1])
and die "Error running $fet->[0]. Interrupted?\n";
$fetched = 1;
}
unless ($fetched) {
die "Couldn't find a program to download things from the web. I looked for:\n\t".
join(", ", map { $_->[0] } @fetcher) . "\n";
}
system("tar", "zxvf", "xsl-docbook.tar.gz")
and die "Error extracting xsl-doxbook.tar.gz; have GNU tar?\n";
}
my $output_dir = "$home/htdocs/doc/bml";
my $docraw_dir = "$home/doc/raw";
my $XSL = "$docraw_dir/build/xsl-docbook";
my $stylesheet = "$XSL/html/chunk.xsl";
open (F, "$XSL/VERSION");
my $XSL_VERSION;
{
local $/ = undef; my $file = <F>;
$XSL_VERSION = $1 if $file =~ /VERSION.+\>(.+?)\</;
}
close F;
my $download;
if ($XSL_VERSION && $XSL_VERSION ne $XSL_VERSION_RECOMMENDED && ! $opt_myxsl) {
print "\nUntested DocBook XSL found at $XSL.\n";
print " Your version: $XSL_VERSION.\n";
print " Recommended: $XSL_VERSION_RECOMMENDED.\n\n";
print "Options at this point. Re-run with:\n";
print " --myxsl to proceed with yours, or\n";
print " --getxsl to install recommended XSL\n\n";
exit 1;
}
if (! $XSL_VERSION) {
print "\nDocBook XSL not found at $XSL.\n\nEither symlink that dir to the right ";
print "place (preferrably at version $XSL_VERSION_RECOMMENDED),\nor re-run with --getxsl ";
print "for me to do it for you.\n\n";
exit 1;
}
chdir "$docraw_dir/build" or die;
print "Generating API reference\n";
system("api/api2db.pl --include=BML:: --book=bml > $docraw_dir/bml.book/api.gen.xml")
and die "Errror generating BML API reference.\n";
system("xsltproc --nonet --catalogs ".
"--stringparam use.id.as.filename '1' ".
"$stylesheet $docraw_dir/bml.book/book.xml")
and die "Error generating HTML.\n";

115
bml/doc/docbook/core.xml Executable file
View File

@@ -0,0 +1,115 @@
<chapter id="bml.core">
<chapterinfo>
<title>Core <abbrev>BML</abbrev> blocks</title>
</chapterinfo>
<title>Core <abbrev>BML</abbrev> blocks</title>
<para>
Core blocks are predefined blocks that are named with a leading underscore.
Most core blocks have a higher purpose than simple template use:
</para>
<variablelist>
<varlistentry>
<term><literal role="core.bml.block">_code</literal></term>
<listitem><para>
<literal>&lt;?_code _code?&gt;</literal> blocks are perhaps the most useful feature of
<abbrev>BML</abbrev> outside of the ability to have global site templates.
These blocks allow template authors to embed pieces of executable Perl code
within the bml page that get executed on the server.
</para><para>
</para><para>
The code you write gets executed in its own package (namespace) called
<computeroutput>BMLCodeBlock::</computeroutput>.
Any variables you declare in one code block on a page without using
<literal>my</literal> are carried on to the next <literal>_code</literal> block.
</para><para>
Because the BML parser must evaluate everything on the page before sending the
<abbrev>HTTP</abbrev> headers, make sure you don't print anything.
Any output printed to <literal>STDOUT</literal> will just be interpreted as
<abbrev>HTTP</abbrev> headers. How the <literal>_code</literal> blocks work is
that you need to return a value at the end.
Whatever value your code fragment returns is what the block evaluates to.
Usually what you end up doing is building a string, concatenating things to it
over and over, and then returning it at the end.
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal role="core.bml.block">_c</literal> - <literal role="core.bml.block">_comment</literal></term>
<listitem><para>
Comment blocks are templates that do not get parsed into resultant text later,
and are useful when <abbrev>HTML</abbrev> style comments
(<quote><literal>&lt;!-- --&gt;</literal></quote>) are not desired.
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal role="core.bml.block">_info</literal></term>
<listitem><para>
Information blocks can be used to include special information about the particular
<abbrev>BML</abbrev> page the block is contained in.
<variablelist>
<title><literal>_info</literal> directives</title>
<varlistentry>
<term><literal>package</literal></term>
<listitem><para>Specify and load a required package</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>nocache</literal></term>
<listitem><para>Specified page is dynamic, and shouldn't be cached</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>static</literal></term>
<listitem><para>Specified page is static; ok to cache</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>noheaders</literal></term>
<listitem><para>Turn off default <abbrev>BML</abbrev> headers</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>nocontent</literal></term>
<listitem><para>Specify that page has no cacheable content</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>localblocks</literal></term>
<listitem><para>Declare page specific <abbrev>BML</abbrev> blocks.</para></listitem>
</varlistentry>
</variablelist>
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal role="core.bml.block">_include</literal></term>
<listitem><para>
Include blocks can be used to integrate a text file straight into a <abbrev>BML</abbrev>
file. Include files can be written in BML or plain text.
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal role="core.bml.block">_e*</literal></term>
<listitem><para>
<literal>_e*</literal> are a variety of escape blocks, each with a different purpose:
<variablelist>
<varlistentry>
<term><literal>_eh</literal></term>
<listitem><para>Replace certain <abbrev>ASCII</abbrev> characters with their <abbrev>HTML</abbrev> entity counterparts</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>_eb</literal></term>
<listitem><para>Replace certain <abbrev>ASCII</abbrev> characters that can trigger <abbrev>BML</abbrev> blocks (<quote><literal>&lt;?xml?&gt;</literal></quote>) with their <abbrev>HTML</abbrev> entity counterparts</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>_eu</literal></term>
<listitem><para>Escape non-compliant <abbrev>ASCII</abbrev> characters in <acronym>URL</acronym>s</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>_ea</literal></term>
<listitem><para>Escape text by passing through <literal>eh</literal> and then <literal>eb</literal></para></listitem>
</varlistentry>
</variablelist>
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal role="core.bml.block">_ml</literal></term>
<listitem><para>
Multi language blocks are used to interchange certain text blocks with the specified language-domain translation.
</para></listitem>
</varlistentry>
</variablelist>
</chapter>

89
bml/doc/docbook/flags.xml Executable file
View File

@@ -0,0 +1,89 @@
<chapter id="bml.flags">
<title>BML Block Types</title>
<para>
This documents the flags in braces at the beginning of <filename>.look</filename> file block template definitions.
The flags fall into one of three classes:
</para>
<para>
<variablelist>
<title>Varible definition types:</title>
<varlistentry>
<term>F</term>
<listitem>
<para>Full, mix of multi &amp; single line property definitions:
<programlisting><![CDATA[<?template
foo<=
Multi
line
string
<=foo
bar=>Single line string
template?>]]></programlisting>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>P</term>
<listitem>
<para>Pipe delimited, properites are named DATA&lt;n&gt;, where &lt;n&gt; starts at 1 and increases.
<programlisting>&lt;?template DATA1|second arg|DATA3 template?&gt;</programlisting>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>D</term>
<listitem>
<para>One property, and it's named DATA
<programlisting>&lt;?template I am the DATA template?&gt;</programlisting>
</para>
</listitem>
</varlistentry>
</variablelist>
<variablelist>
<title>Static template definitions:</title>
<varlistentry>
<term>S</term>
<listitem>
<para>Static: output won't have more BML to expand, or properties to fill-in, so don't try.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>R</term>
<listitem>
<para>Less static: add pRoperties, but then don't BML expand.</para>
</listitem>
</varlistentry>
</variablelist>
<variablelist>
<title>Controlling expansion vs. interpolation order:</title>
<varlistentry>
<term>p</term>
<listitem>
<para>
Pre-parsed.
BML-expand parameters first, then interpolate into template.
By default, parameters are interpolated first, then everything is expanded.
But if you use <literal>%%TITLE%%</literal> twice in your <literal>PAGE</literal>, for example, and your <filename>.bml</filename> file defines <literal>TITLE=></literal> with a <literal>_CODE</literal> block, it will be run twice, so it's generally a good idea to make <literal>PAGE</literal> definitions pre-parsed.
Also, then, you avoid re-running most of your output through the BML expander a second time.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>s</term>
<listitem>
<para>
Expand embedded parameterless static blocks in definition early.
When the template file is read, any blocks of the form <literal>&lt;?foo?&gt;</literal> are expanded ahead of time.
Useful in conjunction with the <literal>{S}</literal> flag. consider:
<programlisting><![CDATA[# Our image server:
IMGPREFIX=>{S}http://www.site.com:8080/
# Some block that has an image:
SPACER=>{Ss}<img src='<?imgprefix?>/spacer.gif' width='1' height='10'>]]></programlisting>
The <literal>SPACER</literal> block isn't really static, but because <literal>{s}</literal> is used and <literal>&lt;?IMGPREFIX?&gt;</literal> is static, then <literal>SPACER</literal> can also be static.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</chapter>

8
bml/doc/docbook/index.xml Executable file
View File

@@ -0,0 +1,8 @@
<book id="bml.index">
&bml.bookinfo;
&bml.preface;
&bml.tutorial;
&bml.flags;
&bml.core;
&bml.api.ref;
</book>

64
bml/doc/docbook/preface.xml Executable file
View File

@@ -0,0 +1,64 @@
<preface id="bml.preface">
<!-- Was going to use <section>s, but we don't need more pages. -->
<!-- Not as clean, but it works -->
<title>Preface</title>
<para>
This is a comprehensive manual aimed towards people wishing to
use <abbrev>BML</abbrev> for their website needs.
Some of the topics covered include setting up <abbrev>BML</abbrev> for
a website, writing a custom <abbrev>BML</abbrev> scheme, and
customization &amp; optimization of a <abbrev>BML</abbrev> installation.
</para>
<formalpara>
<title>Target Audience</title>
<para>
This book was written for anyone interested in installing and using
<abbrev>BML</abbrev> for their own purposes, and for people who are
just generally interested in how <abbrev>BML</abbrev> works.
</para>
</formalpara>
<para>
Readers of this book should be familiar with administering a web
site, and have at least a brief knowledge of <abbrev>HTML</abbrev>.
</para>
<formalpara><title>Organization</title><para>
The Manual is organized into certain chapters:
</para><para>
<variablelist>
<varlistentry>
<term><xref linkend="bml.tutorial" /></term>
<listitem><para>
A tutorial covering the basics of <abbrev>BML</abbrev>, and
explaining how to write a <abbrev>BML</abbrev> document.
</para></listitem>
</varlistentry>
<varlistentry>
<term><xref linkend="bml.flags" /></term>
<listitem><para>
A reference to <abbrev>BML</abbrev> block flags.
</para></listitem>
</varlistentry>
<varlistentry>
<term><xref linkend="bml.core" /></term>
<listitem><para>
A reference to the core <abbrev>BML</abbrev> blocks.
</para></listitem>
</varlistentry>
<varlistentry>
<term><xref linkend="bml.api.ref" /></term>
<listitem><para>
An application programming interface reference.
</para></listitem>
</varlistentry>
</variablelist>
</para></formalpara>
<formalpara>
<title>Versions</title>
<para>
An online version of this book can be found at:
<ulink url="http://www.livejournal.com/doc/server/bml.index.html" />.
To compile these pages for your own, refer to:
<filename>/doc/raw/notes.txt</filename> in <abbrev>CVS</abbrev>.
</para>
</formalpara>
</preface>

552
bml/doc/docbook/tutorial.xml Executable file
View File

@@ -0,0 +1,552 @@
<chapter id="bml.tutorial">
<!-- $Id: tutorial.xml,v 1.4 2004/07/03 00:13:27 deveiant Exp $ -->
<chapterinfo>
<title>A Brief Tutorial</title>
</chapterinfo>
<title>A Brief Tutorial</title>
<para>
The goal of using <abbrev>BML</abbrev> is to become a smarter, lazier
webmaster. The qualities that define a <abbrev>BML</abbrev> author should
be the same as a good Perl programmer: <emphasis>laziness, impatience,
and hubris</emphasis>.
</para>
<section id="bml.tutorial.intro">
<title>Introducing <abbrev>BML</abbrev></title>
<!-- Tutorial: Blocks Section -->
<section id="bml.tutorial.intro.blocks">
<title>Blocks</title>
<para>
<abbrev>BML</abbrev> is essentially a simple macro language. Macros are
called <firstterm>blocks</firstterm> in <abbrev>BML</abbrev>. Blocks are
<wordasword>defined</wordasword> in <firstterm>look files</firstterm>
and are <wordasword>invoked</wordasword> in <abbrev>BML</abbrev> files.
Blocks accept <wordasword>parameters</wordasword> and are divided into
several <wordasword>types</wordasword> according to how parameters are
transmitted and how the definition of the block is able to make use of
them. Definitions of blocks are essentially chunks of
<abbrev>HTML</abbrev> with potentially more recursive
<abbrev>BML</abbrev> block invocations inside them.
</para>
<example id="bml.lookup.example1">
<title>BML lookup file</title>
<programlisting linenumbering="numbered"><![CDATA[
project=>The Alabaster Project
greeting<=
<p>Welcome to <?project project?>, a joint effort between the citizens of earth
and Spumco, Inc.</p>
<=greeting
]]></programlisting>
</example>
<para>The "project" and "greeting" constructs in the above example lookup file are
blocks, and can be used to insert their respective content into HTML
output. The "project" block is a single-line block that consists of
everything immediately following the name of the block and the
<literal>=&gt;</literal> up to the end of the line. The "greeting"
block is a multiline block, and contains all the lines immediately
following the <literal>greeting&lt;=</literal> line and preceding
the <literal>&lt;=greeting</literal> one.</para>
</section>
<!-- Tutorial: BML Files Section -->
<section id="bml.tutorial.intro.bmlfiles">
<title>BML Files</title>
<para>
A <abbrev>BML</abbrev> file is simply an <abbrev>HTML</abbrev> file with
some <abbrev>BML</abbrev> block invocations in it. Each such invocation
specifies the name of the block and the parameters, if any, to pass to it.
The ultimate result of a block's invocation at runtime is <abbrev>HTML</abbrev>
which is put in the outgoing stream exactly at the place where the block's
invocation resided in the <abbrev>BML</abbrev> file.
</para>
<example id="bml.file.example1">
<title>BML file</title>
<programlisting linenumbering="numbered"><![CDATA[
<html>
<head><title><?project project?></title>
<body>
<h1><?project project?></h1>
<?greeting greeting?>
</body>
</html>
]]></programlisting>
</example>
<para>Given the lookup file from the previous example, the BML file above
would yield output like:</para>
<example id="bml.output.example1">
<title>Output</title>
<programlisting linenumbering="numbered"><![CDATA[
<html>
<head><title>The Alabaster Project</title>
<body>
<h1>The Alabaster Project</h1>
<p>Welcome to The Alabaster Project, a joint effort between the citizens of earth
and Spumco, Inc.</p>
</body>
</html>
]]></programlisting>
</example>
<para>The block invocations in the <link linkend="bml.lookup.example1">BML
lookup file example</link> above do not contain parameters, but even
so are still a powerful way of building a document out of aggregate
parts. Adding parameters, of course, increases this usefulness.</para>
</section>
</section>
<!-- Tutorial: Parameters Section -->
<section>
<title>Block Parameters</title>
<section id="bml.tutorial.intro.parameters">
<title>The <varname>DATA</varname> Block Parameter</title>
<para>Sometimes the insertion of simple static content into the output
will not suffice for projects of moderate complexity. A designer
frequently wishes to repeat certain elements throughout the page,
keeping a consistent structure and look-and-feel. BML provides this
functionality by allowing you to declare blocks which take parameters,
which can then be used in building the content inserted into the
document.</para>
<para>The simplest parameter-accepting block is one you've seen already in
the above examples. Unless otherwise designated, all blocks accept one
parameter, which is put into a variable called
<varname>DATA</varname>. This parameter can then be interpolated
into the resulting output with a placeholder that looks like:
<literal>%%DATA%%</literal>.</para>
<example id="bml.lookup.example2">
<title>Lookup file with DATA blocks</title>
<programlisting linenumbering="numbered"><![CDATA[
heading=><h1>%%DATA%%</h1>
subheading=><h2>%%DATA%%</h2>
]]></programlisting>
</example>
<para>This lookup file defines two blocks, one called
<literal>heading</literal> which creates level-one heading HTML, and
another called <literal>subhead</literal>, which creates level-two
headings.</para>
<para>These could be used like so:</para>
<example id="bml.file.example2">
<title>BML file using parameterized blocks</title>
<programlisting linenumbering="numbered"><![CDATA[
<html>
<head><title>Hansel and Grendel Go to Finishing School</title>
<body>
]]>
<emphasis><![CDATA[ <?heading Hansel and Grendel Go to Finishing School heading?>]]></emphasis>
<![CDATA[
<p>Our story begins at a point in the Universe not unlike where you are now
sitting, drinking your government-sanctioned stimulant, dreaming of the
day when you, too, will own your own personalized luxury home on 0.3 acres
of land, with a stunning view of, well, the neighbor's personalized luxury
home on 0.3 acres of land. Except this point in the Universe is much more
exciting, fine-smelling, and generally a better place to be than
yours.</p>
]]>
<emphasis><![CDATA[ <?subheading No, Really, It Is Much Finer subheading?>]]></emphasis>
<![CDATA[
<p>So, anyway, at this particular point in the Universe, on a day not
entirely unlike today, two entirely unrelated mythological pantheons
collided, resulting in a fast friendship between a Little Boy Bound to be
Eaten by the Architypal Crone and a Faceless Beast That Waits for the Hero
to Dispatch It. Which, as you might have guessed, was not the intention of
the various storytellers involved, but that's what happens when people
stop reading all the really cool stories and start checking the Financial
Section every 12 minutes. There's only so much space to go around in the
collective consciousness, you know...</p>
</body>
</html>
]]></programlisting>
</example>
<para>which would result in output like:</para>
<example id="bml.output.example2">
<title>Parameterized Output: Named Parameters</title>
<programlisting linenumbering="numbered"><![CDATA[
<html>
<head><title>Hansel and Grendel Go to Finishing School</title>
<body>
]]>
<emphasis><![CDATA[ <h1>Hansel and Grendel Go to Finishing School heading</h1>]]></emphasis>
<![CDATA[
<p>Our story begins at a point in the Universe not unlike where you are now
sitting, drinking your government-sanctioned stimulant, dreaming of the
day when you, too, will own your own personalized luxury home on 0.3 acres
of land, with a stunning view of, well, the neighbor's personalized luxury
home on 0.3 acres of land. Except this point in the Universe is much more
exciting, fine-smelling, and generally a better place to be than
yours.</p>
]]>
<emphasis><![CDATA[ <h2>No, Really, It Is Much Finer</h2>]]></emphasis>
<![CDATA[
<p>So, anyway, at this particular point in the Universe, on a day not
entirely unlike today, two entirely unrelated mythological pantheons
collided, resulting in a fast friendship between a Little Boy Bound to be
Eaten by the Architypal Crone and a Faceless Beast That Waits for the Hero
to Dispatch It. Which, as you might have guessed, was not the intention of
the various storytellers involved, but that's what happens when people
stop reading all the really cool stories and start checking the Financial
Section every 12 minutes. There's only so much space to go around in the
collective consciousness, you know...</p>
</body>
</html>
]]></programlisting>
</example>
<para>By this point, you might be saying, "But wait! I'd much rather type
<literal>'&lt;h1&gt; ... &lt;/h1&gt;'</literal> than
<literal>'&lt;?heading ... heading?&gt;'</literal>!" If you were
absolutely confident that headings would always be expressed with
<literal>&lt;h1&gt;</literal> tags, and subheadings with
<literal>&lt;h2&gt;</literal> tags, it might be more efficent to
leave them as static HTML. If, however, someone wants all headings and
subheadings to change throughout the site, having the definition of them
expressed as a block makes changing them everywhere a simple matter of
changing the block that defines them:</para>
<example id="bml.lookup.example3">
<title>Alternate Heading Block</title>
<programlisting linenumbering="numbered"><![CDATA[
heading=><h1 class="heading"><img src="logo.png"/> %%DATA%%</h1>
subhead<=
<!-- This is a subheading, which naturally requires a chicken above it -->
<img src="chicken.png" /><br />
<h2 class="subheading">%%DATA%%</h2>
<=subhead
]]></programlisting>
</example>
<para>Instead of a fairly complex search-and-replace session over multiple
files, you instead need only change the definition of what a heading means
in one place, and see it reflected throughout your site. Note that
multiline blocks can also use the <varname>DATA</varname>
parameter.</para>
<para>The examples above are admittedly contrived, and could probably be
accomplished using <acronym>CSS</acronym>, but it should serve to
demonstrate a use which is orthogonal to the role played by style
systems.</para>
</section>
<!-- Tutorial: Multiple Parameters Section -->
<section id="bml.tutorial.intro.multipleparams">
<title>Block Flags and Passing Multiple Parameters</title>
<para>Many tasks will not be able to be accomplished with blocks that have
only one parameter, so BML provides another kind of block that can be
passed multiple parameters. Up 'til now, we've been using blocks with an
implied parameter, but we'll need to tell BML that the block we're
defining is different. This is accomplished by specifying one or more
<firstterm>flags</firstterm> when declaring the block. Flags are single
letters that are placed inside curly braces (<literal>{}</literal>) at
the beginning of the block definition. For example, the flag that
corresponds to the full block type (which we'll be using for blocks that
can accept multiple parameters) is designated with an
<literal>{F}</literal> flag:</para>
<example id="bml.lookup.example4">
<title>Block Definitions with Flags</title>
<programlisting linenumbering="numbered"><![CDATA[
smallcaps=>{D}<span style="font-variant: small-caps">%%DATA%%</span>
topiclink=>{F}<a href="/topic.pl?name=%%name%%">%%linktext%%</a>
section<={F}
<div id="section-%%id%%" class="section">
<h3>%%heading%%</h3>
<p>%%body%%</p>
</div>
<=section
]]>
</programlisting>
</example>
<para>As you can see, two of the blocks declared above have an
<literal>{F}</literal> flag, and one has a <literal>{D}</literal>
flag. The <literal>{D}</literal> flag stands for 'data', which is the
default block type we're already familiar with, so the flag part could
have been omitted. There are other block types which specify other
attributes and behaviors, but for now we'll focus on the
<literal>{F}</literal> type.</para>
<para>In the above example, two <literal>{F}</literal> blocks are defined,
a single-line one and a multi-line one. Both expect multiple parameters
which they use to fill in parts of the HTML fragments they are responsible
for creating. They also use placeholders like <literal>{D}</literal>
blocks do, but they have unique names that will serve as the label given
with the parameter that belongs there when calling it from a BML
file.</para>
<para>Calling an <literal>{F}</literal> block necessarily looks a bit
different than the simple references made to <literal>{D}</literal>
blocks. Calls to a block which requires multiple parameters uses the same
syntax as that used for declaring blocks:</para>
<example id="bml.file.example4">
<title>BML File</title>
<programlisting linenumbering="numbered"><![CDATA[
<?section
id=>listrules
heading=>Rules of the Lists
body<=
There are many considerations when engaging in mounted combat at a tourney, not
the least of which is obeying the convoluted and sometimes confusing localized
<em>Rules of the Lists</em>.
<=body
section?>
]]></programlisting>
</example>
<para>In the above example, the <literal>section</literal> block is being
called with three parameters, two of which are single-line parameters
(<varname>id</varname> and <varname>heading</varname>), and a third
multi-line one (<varname>body</varname>). The output rendered by combining
the above BML file with the previous lookup file would look something
like:</para>
<example id="bml.output.example4">
<title>Example output</title>
<programlisting>
<![CDATA[
<div id="section-listrules" class="section">
<h3>Rules of the Lists</h3>
<p>There are many considerations when engaging in mounted combat at a tourney, not
the least of which is obeying the convoluted and sometimes confusing localized
<em>Rules of the Lists</em>.
</p>
</div>
]]>
</programlisting>
</example>
</section>
<section>
<title>Parameterized Output: Positional Parameters</title>
<para>In addition to the named parameters introduced above, BML also
supports positional parameters. Like with named parameters, a block with
positional parameters is designated with the use of a flag, this time the
<literal>{P}</literal> or "pipe-delimited" flag. Parameters in a
<literal>{P}</literal> block are represented with
<varname>%%DATA1%%</varname>, <varname>%%DATA2%%</varname>, etc. This can
be useful when a routine takes a lot of parameters, or when calling the
same block many times with tabular or list data.</para>
<para>An example of this is building a list of links, each of which is an
item in a definition list:</para>
<example id="bml.lookup.example5">
<title>Block Definitions with Positional Parameters</title>
<programlisting linenumbering="numbered">
<![CDATA[
LINKITEM=>{P}<dt><a href="%%data2%%">%%data1%%</a></dt> <dd>%%data3%%</dd>
LINKLIST<=
{F}
<h4>My Current Reading List</h4>
<dl>
%%items%%
</dl>
<p><small>Last updated: %%date%%</small></p>
<=LINKLIST
]]>
</programlisting>
</example>
<example id="bml.file.example5">
<title>BML File using the 'listlist' and 'linkitem' blocks</title>
<programlisting linenumbering="numbered">
<![CDATA[
<?linklist
date=>2004/10/14
items<=
<?linkitem News of Brad|http://brad.livejournal.com/|Brad's daily adventure linkitem?>
<?linkitem BoingBoing|http://boingboing.net/|A directory of wonderful things linkitem?>
<?linkitem WPGtR|http://poignantguide.net/ruby/|Wow, this book comes with an onion! linkitem?>
<=items
linklist?>
]]>
</programlisting>
</example>
<para>Combining the two files above would render output like this:</para>
<example id="bml.output.example5">
<title>Example output</title>
<programlisting>
<![CDATA[
<h4>My Current Reading List</h4>
<dl>
<dt><a href="http://brad.livejournal.com/">News of Brad</a></dt> <dd>Brad's daily adventure</dd>
<dt><a href="http://boingboing.net/">BoingBoing</a></dt> <dd>A directory of wonderful things</dd>
<dt><a href="http://poignantguide.net/ruby/">WPGtR</a></dt> <dd>Wow, this book comes with an onion!</dd>
</dl>
<p><small>Last updated: 2004/10/14</small></p>
]]>
</programlisting>
</example>
</section>
</section>
<section>
<title>Static Blocks</title>
<para>Sometimes the re-expansion of embedded BMl might not be what you
want. In that case, you can designate a block with a flag which will cause
it to stop or limit the re-expansion of embedded calls.</para>
<section>
<title>Fully-Static Blocks</title>
<para>If you add the <literal>{S}</literal> flag to the block you're
defining, the contents of it will not be re-evaluated afterward. This is
mostly useful when you have blocks that you are sure will never contain
BML to be expanded or properties to fill in, and you want to save the
overhead of trying to re-evaluate them.</para>
<example id="bml.lookup.example6">
<title>Look file with <literal>{S}</literal> block</title>
<programlisting linenumbering="numbered">
<![CDATA[
companyname=>{S}Spumco, Inc.
]]>
</programlisting>
</example>
<para>This defines the <literal>companyname</literal> block as
static.</para>
<example id="bml.file.example6">
<title>BML File that calls the static block</title>
<programlisting linenumbering="numbered">
<![CDATA[
<h1>Welcome to <?companyname companyname?></h1>
]]>
</programlisting>
</example>
<para>Combining the two yields:</para>
<example id="bml.output.example6">
<title>Example output</title>
<programlisting>
<![CDATA[
<h1>Welcome to Spumco, Inc.</h1>
]]>
</programlisting>
</example>
</section>
<section>
<title>Semi-static Blocks</title>
<para>Sometimes you want a block which fits somewhere between the
fully-dynamic <literal>{D}</literal> blocks and the completely-static
behavior of <literal>{S}</literal> blocks. Enter the
<literal>{R}</literal> block flag, which expands
p<emphasis>R</emphasis>operties like those passed to a
<literal>{D}</literal>, <literal>{F}</literal>, or <literal>{P}</literal>
block, but doesn't expand BML that might be inserted by one of
those.</para>
<example id="bml.lookup.example7">
<title>Look file with <literal>{R}</literal> block</title>
<programlisting linenumbering="numbered">
<![CDATA[
]]>
</programlisting>
</example>
<para></para>
<example id="bml.file.example7">
<title></title>
<programlisting linenumbering="numbered">
<![CDATA[]]>
</programlisting>
</example>
<para></para>
<example id="bml.output.example7">
<title>Example output</title>
<programlisting>
<![CDATA[]]>
</programlisting>
</example>
</section>
</section>
<section id="bml.tutorial.example">
<title>A Full Example</title>
<para>
</para>
<para>
<programlisting><![CDATA[
<html>
<head>
<title>FooBar Enterprises - Page</title>
</head>
<body>
<h1 class="header">FooBar Enterprises - Page</h1>
<hr />
<div class="header"><strong>Headers - What good are they?</strong></div>
<p class="para" style="text-align: justify">
This is just an introductory text. The normal way to include text like this
is to write it in Latin, but since I don't know Latin, you'll have to settle
with this little paragraph.
</p>
<div class="header"><strong>Templates are for Wimps!</strong></div>
<p class="para">
I'd rather have to edit all of my pages by hand when I decide to change the
unified look of my site!
</p>
</body>
</html>
]]></programlisting>
</para>
<para>
<programlisting><![CDATA[
header=>{D}<div class="header"><strong>%%DATA%%</strong></div>
]]></programlisting>
</para>
<para>
<programlisting><![CDATA[
<?header Headers - What good are they? header?>
]]></programlisting>
</para>
<!-- :WORK: -->
</section>
</chapter>