Introduction to Bear

Welcome to the Bear CMS docs. This page is a basic documentation effort by way of example. The source file is available at staging/index.text.

Installation

1. Copy bear to wherever you want it to reside.

2. optional: Install Text::Markdown from CPAN. If you don't know how to install CPAN modules then you probably want to ask someone who does (it's not hard, but it's quirky and if you didn't know already then you probably have better things to do with your time).

Staging

You set up bear by putting files in a directory structure like this:

$DOCROOT  
    staging/  
        %template.txt
        file1.txt  
        file2.txt  
        nontextfile.doc  
        nontextfile.gif  
        otherdir/  
            %template.txt
            file1.txt  
            file2.txt  

Running

You run bear like this:

    bear $DOCROOT destination-path

Rendering

When you run the program it sweeps the staging area looking for files to do something with, and then attempts to render or copy those files so that the $DOCROOT mirrors the structure of the staging area but in rendered form. In general it only does things if the file in the staging area is newer than the file in $DOCROOT, or if the equivalent file does not exist in $DOCROOT.

• Directories are created if needed.
• . files are ignored.
• CVS and .svn directories are ignored, as well as svn meta files (e.g. svn-commit.tmp~).
• The %template.txt and %prefs.txt files are used to render .txt files but are not copied themselves.
• Other non-.txt files are copied into the $DOCROOT area.
• .txt files are rendered.

Rendering is the process of turning a raw (or somewhat marked up) text file and turning it into an HTML page.

• Preference directives are inherited from the preference files.
• The header of the .txt file is examined for preference directives.
• If Markdown is turned on, the content of the .txt file is handled using Markdown format.
• The text is entered into the template.
• If the directory inherits its template, the rendered text is then entered into the parent template.
• The contents of any directive from the source file, and any preference directives, are used to replace tags in the final output.

Preferences

A directory can have a %prefs.txt file, which specifies preferences applying to that directory and all subdirectories that don't override. Each preference is inherited by all subdirectories that do not override the preference. Each line in the preference file is a directive with a name value pair:

    #name value

Only the first space is relevant, so you can do things like

    #footer This is a global footer.

You can define your own preferences -- just stored text to use in your web pages -- but there are two (currently) special preferences that bear relies on:

BEAR_template_inherits -- tells bear to shove the output of this directory's template into the next higher level template:

    %BEAR_template_inherits true

BEAR_use_markdown -- tells bear to render this directory's files using the Markdown syntax

    %BEAR_use_markdown true

Other special preferences may be defined in the future, using the BEAR_ prefix.

File Specific Preferences

Text files to be rendered can set their own preference directives by starting the file with a block of directives in the same format as the general preference files use. In general, any preference can be set or overridden, but setting or overriding directives affecting how bear renders (e.g. BEAR_template_inherits) is not supported (they may work, but may have perverse effects).

Templates

%template.txt files should be formatted using normal HTML or XHTML, unless they inherit, in which case they should be the relevant fragment of HTML/XHTML.

Templates have two special tags that bear uses to render contained text:

The bodytext tag is replaced by the source file's text, or the rendered output of a template which inherits from this one.

    <%bodytext%>

The transform tag will eventually support a number of special text transformations, but currently is a one-time hack to get Faisal's Quotes File to work.

Templates cannot declare their own preference directives.

Publishing

If you declare a destination path then the contents of $DOCROOT are synchronized to the destination location by rsync (via SSH if to a remote site).

Note: that the staging area is published to the server along with the rendered output. This is intentional. You may wish to put a .htaccess file in there.