ctime: 2009-06-24
mtime: 2009-06-26
-= Help =
+Note that command line options can also be specified via [[configuration]].
+
+= Invoke help =
As usualy, you can get command line help with "`-h`" or "`--help`":
+ $ webber/webber --help
usage: webber [options]
-
+
options:
-h, --help show this help message and exit
-i DIR, --in=DIR input directory
With "`-k`" or "`--keepgoing`" you can tell webber to ignore errors in one
page and continue with the next page.
-
-
parent: Webber
lang: en
ctime: 2009-06-24
-mtime: 2009-06-24
+mtime: 2010-07-06
+change: enhanced, fixed and clarified
-Configuration happens either the [[commandline]] or
-via the configuration file (described below). All Configurations are
-[[inherited|inheritance]] and or overwritable on a per-directory and
-per-file basis.
+Configuration happens either via [[commandline]] or with the
+configuration file (described below). All configurations are subject
+to [[inheritance]]. You can also overwritable any of them on a
+per-directory and/or per-file basis.
-The main means for configuration is the config file:
-= Format =
+= Config file format =
-Webber expects a `webber.conf` file in it's root directory. It should look like this:
+Webber expects file named "`webber.conf`" file in the root directory.
+It could look like this:
template: "default"
date_format: "%d.%m.%Y"
- input_encoding: "iso-8859-1"
- output_encoding: "iso-8859-1"
plugins: [
- "skeleton",
- "hierarchy",
- "link",
- "read_rst",
- "read_html",
- "read_copyonly",
- "read_markdown",
- "template_mako",
- ]
+ "skeleton",
+ "hierarchy",
+ "link",
+ "read_rst",
+ "read_html",
+ "read_copyonly",
+ "read_markdown",
+ "template_mako",
+ "my_plugin",
+ ]
plugin_dirs: [
"my_plugins"
]
- exclude_dir: [
- "webber.conf",
- "*.tmpl",
- ]
- exclude_files: [
- ]
-You could also some options with are normally defined by [[commandline]].
-This saves you from specifying them on ever run of webber:
+Options for the [[commandline]] can also be specified in the config file:
in_dir: "in"
out_dir: "out"
style_dir: "in/style"
verbose: 5
-Beside those entries, you can specify any additional entries that will then
-be available in your plugins or templates.
+= Webber's configuration =
+
+== in_dir ==
+
+Directory, where the source files (in [[markdown|read_markdown]],
+[[rst|read_rst]] or [[html|read_html]] format) reside.
+
+Default: "`in`".
+
+See [[commandline]].
+
+
+== out_dir ==
+
+Directory where webber creates the output files.
+
+Default: "`out`".
+
+See [[commandline]].
+
+
+== style_dir ==
+
+Directory where webber reads the [[template_mako]].
+
+Default: "`in/style`".
+
+See [[commandline]] and "`template`".
-= Meaning =
== template ==
-Used by the [[template_mako]] to select the template.
+Used by [[template_mako]] to select the template.
-== date_format ==
+Default: `"template`"
-Used in `format_date()`.
== input_encoding ==
-Encoding ('utf-8', 'iso-8859-1' etc) used for reading files.
+Encoding (e.g. 'utf-8', 'iso-8859-1' etc) used when reading [[source pages|pageformat]].
+
+Default: `"iso-8859-1`"
+
== output_encoding ==
-Encoding ('utf-8', 'iso-8859-1' etc) used when writing the final HTML pages.
+Encoding (e.g. 'utf-8', 'iso-8859-1' etc) used when writing the final HTML pages.
+
+Default: `"iso-8859-1`"
+
== plugins ==
-List of to load.
+List of [[Plugins]] to load.
+
== plugin_dirs ==
-List of directories that should be search for [[plugins|Plugins]]. Can be empty or
+List of directories that should be search for [[Plugins]]. Can be empty or
completely omitted.
+
== exclude_dirs ==
-List of directories below `cfg.in_dir` to skip.
+List of directories below "`in_dir`" to skip.
+
+Default: "`[]`"
+
== exclude_files ==
-List of files below `cfg.in_dir` to skip.
+List of files below "`in_dir`" to skip.
+
+Default: "`['webber.conf', 'directory.conf', '*.tmpl']`"
+
+
+== date_format ==
+
+Used in `format_date()`. The format is the same as in `"man 2 strftime`".
+
+
+== verbose ==
-== in_dir, out_dir, style_dir ==
+How verbose webber should be.
See [[commandline]].
+
+
+== keep_going ==
+
+If webber should continue after an error.
+
+See [[commandline]].
+
+
+= Plugin's configuration =
+
+Many [[Plugins]] can use custom options. Read more about them in their
+documentation.
+
+
+= User defined configuration =
+
+Beside those entries, you can specify any additional entries that will
+then be available in user-defined [[Plugins]], [[functions]],
+[[macros]] or [[template_mako]]. For example, after adding:
+
+ category: "Webber"
+
+you can access in [[template_mako]] with:
+
+ <p>Category: ${page.category}</p>
mtime: 2010-06-24
change: described get_toc()
-= Calling functions =
+You can call functions only from [[template_mako]], not from
+[[pages|pageformat]]. If you need the latter, look at [[macros]].
-You can call functions only from [[template_mako]]. An example:
+= Example =
Modified ${format_date(mtime)}
+= List of functions =
+
Here's list of functions defined by webber and it's default plugins:
Defined in [[toc.py|toc]], where you find an example.
-== func ==
-
-A sample function in the [[skeleton.py|skeleton]]. See below.
-
= Writing functions =
parent: Webber
lang: en
ctime: 2009-06-24
-mtime: 2010-06-24
-change: changed behavior of linkify hook
+mtime: 2010-07-06
+change: new introductory text about hooks
-= At Startup =
+Webber can read and use any number of [[Plugins]], even user-supplied.
+Therefore, while writing "`webber.py`", it was not clear which plugins
+will exist. So a flexible way to share data between "`webber.py`" and
+the plugins was needed.
+
+Borrowed from IkiWiki came the idea of "Hooks". At various points
+during the exection "`webber.py`" fires some hooks. Any plugin can act
+to any hook and has a chance to get the current page or configuration
+attributes.
+
+It can then generate local data, change page attributes, generate HTML
+or whatever else is needed.
+
+
+= How to implement hooks =
+
+When you program your own [[Plugins]], you simply write python
+functions and mark then with the "`@set_hook(name)`" Decorator. See
+the Example at <a href="#addoptions">addoptions</a> below.
+
+
+= Hooks fired at startup =
+
+When you start "`webber`", the following hooks are executed:
== addoptions ==
print "in start hook"
-= While reading source files =
+= Hooks fired while reading source files =
+
+For each file read, the following hooks are fired:
== read ==
Now webber walks the directory tree specified in "`cfg.in_dir"`, excluding
-anything from "`cfg.exclude_dir`" and "`cfg.exclude_file"`. For each of the
+anything from "`cfg.exclude_dirs`" and "`cfg.exclude_files"`. For each of the
remaining files this hook is called.
Usually the the "`read_*`" plugins implement this hook. And usually they look
However, it can be something else. In this case "`file.render`" specifies a
hook that get's called for this file.
-The first hook that returns contents wins, no other hooks will be called.
+The first hook that returns contents wins, no further hook-functions
+will be called.
* "`params.direc`" contains a "`class Directory`" object
* "`params.file`" contains a "`class File`" object
params.content = params.content.replace("e", "EEEEE")
-= After reading files =
+= Hooks fired after files are read =
-At this stage all pages and their meta-information has been read. Now we can
-generate additional data, e.g. page hierarchy, tag-clouds, lists of recently
-changed files, etc. This is done via the following two hooks.
+Now all pages and their meta-information has been read.
-The webber-supplied plugin [[hierarchy]] uses this
-mechanism.
+The following hooks allow plugins to use this data and generate
+additional data, e.g. a page hierarchy, tag-clouds, lists of recently
+changed files, etc.
+
+For example, the plugin [[hierarchy]] uses this mechanism.
== scan ==
* "`params`" is empty.
-= While rendering files =
-The following hooks are called for each file that has a rendered in
-"`file.render`" set. See the "`read"`-hook in how to set it.
+= Hooks fired while creating HTML =
+
+The following hooks are called for each file that renders itself. This is indicated
+by the "`file.render`" attribute. See the "`read"`-hook on how to set that.
If "`file.render`" is "`html"`, then the hooks "`htmlize"`, "`linkify`" and
-"`pagetemplate`" are run in this order. Otherwise the hook specified
-in "`file.render`" is called.
+"`pagetemplate`" are run (in that order).
+
+Otherwise the hook specified in "`file.render`" is called. This can
+even be a custom hook.
== htmlize ==
This hook converts contents into HTML.
-The first hook that returns HTML, no other hooks will be called.
+If more than one plugin receive this hook, then the first function
+returning HTML "wins". No other hook-functions will be called
+afterwards.
* "`params.direc`" contains a "`class Directory`" object
* "`params.file`" has a "`class File`" object
Functions that are called by this hook receive a pre-rendered HTML page.
They can now modify this HTML further, e.g. py converting links to HTML.
-They can directly modify params.file.contents and don't need to return anything.
+They can directly modify params.file.contents and don't need to return
+anything.
Implemented by the plugin [[link]] and [[toc]].
== pagetemplate ==
The implementation for this is responsible to generate the final html page,
-ready to be written. Implemented by [[template_mako]] plugin.
+ready to be written. Implemented in the [[template_mako]] plugin.
-The first hook that returns a finished HTML page, no other hooks will be
-called.
+The first hook that returns a finished HTML page wins, no further
+hook-functions will be called.
* "`params.direc`" contains a "`class Directory`" object
* "`params.file`" has a "`class File`" object
== copyfile ==
-This is one local hook, run instead of the "`htmlize"`, "`linkify`" and
-"`pagetemplate`" hooks. It's defined and implemented by the plugin
-[[read_copyonly]].
+This is an example of a plugin-defined hook. It's run instead of the
+"`htmlize"`, "`linkify`" and "`pagetemplate`" hooks by virtue of the
+"`file.render`" attribute.
+
+It's defined and implemented by the plugin [[read_copyonly]].
-The first hook that returs anything wins, no other hooks will be called.
+The first hook that returns anything wins, no further hook-functions
+will be called.
* "`params.direc`" contains a "`class Directory`" object
* "`params.file`" has a "`class File`" object
= At the end =
Now everythings has been converted to HTML and written out. And we're just
-one hook away from finishing webber:
+one hook away from finishing program execution:
== finish ==
-This hook is called at the end of webber's execution. No webber-supplied
-plugin uses it currently, but you could use this to save local state into some
-file.
+This hook is called at the end of webber's execution.
* "`params`" is empty
+
+Plugins that use this are [[link]] (to warn about wrong links),
+[[google_sitemap]] (to generate the "`sitemap.xml`" file) and [[rss_feed]]
+(to generate the "`feed.rss`" file).
title: Configuration inheritance
linktitle: Inheritance
-parent: Webber
+parent: Configuration
lang: en
ctime: 2009-06-24
-mtime: 2009-06-26
+mtime: 2010-07-06
+change: various clarifications, a better example
= Overview =
-Internally, webber uses a bunch of `Holder` classes to store information
-(command-line options, config file options, parameters for a directory,
-parameters for a file).
+Internally, webber uses a bunch of `Holder` classes to store information.
-Each `Holder` "inherits" configuration entries from the layer above:
+We have objects of class `Holder` for this entities:
-* `options` for command-line options
-* `cfg` for entries from the command line
-* `direc` for information about a directory
-* `file` (either directly or via `get_current_file()` for data about the
- currently rendered file
+* "`cfg`" stores [[configuration]] and [[commandline]].
+* "`direc`" stores per-directory variables
+* "`file`" stores attributes for each file that webber processes
-= Example =
+This is like the inheritance works:
+
+* "`direc`" inherits everything from "`cfg`". It can, however,
+ override anything. <small>In a future version of webber, the "`direc`"
+ object for directory "`foo/bar/`" will inherit from the
+ directory object for "`bar/`" and only the last one will inherit from
+ "`cfg`". But that's not yet coded.</small>
+* "`file`" inherits from "`direc`" and again is free to override
+ anything on a per-file basis.
-Due to parsing the [[command line|commandline]] there will exist an entry
-`options.style_dir`.
-However, you can also access this same value via `cfg.style_dir`,
-`direc.style_dir` and `file.style_dir`. Any one of them however could
-over-write the settings that originally was in `options`.
+= Example =
-Quite often you'll use this for the page template. In `webber.conf`, you
-specify `template: "default"`, which will be used for most pages. Any
-page that needs a different template will get `template: history` entry
-in it's header.
+Due to parsing the [[commandline]] the attribute "`style_dir`" have
+some value. If you don't specify one, it will be "default" by default.
+
+Now the [[configuration]] file "`webber.conf`" get's processed. It may
+set "`style`" to "twoframe", if you want a two-frame template for your
+web-site.
+
+Assuming you have a subdirectory with source-code examples. In this
+directory you have a file "`directory.conf`" which re-sets it to "default".
+This makes the default template work now only for your source-code
+examples.
+
+There's one page where you use the [[hierarchy]] plugin to generate a
+sitemap. This one page should have it's own template. Simply make the
+[[page|pageformat]] be like this:
+
+ title: Sitemap
+ template: sitemap
+
+ <%
+ site = get_linear_sitemap()
+ %>
+ <ul>
+ % for level, page, link in site:
+ <li id="sidemap${level}"><a href="${link}">${page.title}</a></li>
+ % endfor
+ </ul>
ctime: 2009-06-24
mtime: 2009-06-26
-= Calling macros =
-
Macros are executed whenever the sequence
-"<code>[</code><code>[!name]]</code>" or
-"<code>[</code><code>[!name args]]</code>" is in the source-file.
+"<code>[</code><code>[!name]]</code>" or "<code>[</code><code>[!name
+arg1="1" arg2="2"...]]</code>" is found in a [[source page|pageformat]].
-Webber itself doesn't define any macros.
+Webber itself doesn't define any macros, that's your task. Use custom
+[[Plugins]] for this.
= Defining macros =
print "in macro skeleton.sample_macro, params:", params
return "{ output of sample macro }"
-If you call this macro, you'll see the output "[[!sample]]".
+If you call this macro, the returned text "`{
+output of sample macro }`" will end up in your HTML file.
+
+Inside the macro, you can access this parameters:
* "`params.name`" contains the name of the macro
* "`params.file`" contains the current "`class File`" object
-You can submit additional string arguments, e.g. "<code>[</code><code>[!sample
-arg1="string"]]</code>". This will yield
+You can submit additional string arguments, e.g. with
+"<code>[</code><code>[!sample arg1="string"]]</code>". Now you get
+additionally:
* "`params.arg1`" contains "`string`"
parent: Webber
lang: en
ctime: 2009-06-26
-mtime: 2009-06-26
+mtime: 2010-07-06
+change: enhanced section on page body
-Every page contains a header, then a blank line, and then the text that
-should show up in the web page.
+Every page contains a <a href="#page_header">header</a>, then a blank
+line, then the <a href="#page_body">page body</a>. This is the
+main text that end up in the rendered HTML page.
The header consists of several keywords, followed by a color and a space,
-and the the value.
+and the the value. After this, the page body comes.
-Here's an example:
-
- title: Impressum
-
- Hi, I'm Mario and I won't tell you more about me :-)
-
-
-= Your own keywords =
-
-Inside the template, functions and macros you can access all entries
-by "`file.XXXX`" and you're free to invent your own keywords:
- title: Impressum
- subtitle: What you should know about this web-site
+= Page header =
- Hi, I'm Mario and I won't tell you more about me :-)
-
-Now you can access "`${file.subtitle}`" in your template or
-"`params.file.subtitle`" in your [[macros|macros]] and
-[[functions|functions]].
+In the page header, you can define any attribute. Some of those keywords
+have special meaning for webber or it's plugins:
-= Overriding configuration =
-
-As "`file`" inherits all configuration from "`cfg`" (see [[inheritance]]),
-you can also specify a different template on a per-file basis:
-
- title: Impressum
- template: boring_bg
-
- Hi, I'm Mario and I won't tell you more about me :-)
-
-
-= Webber's keywords =
-
== title ==
Full (long) title for the page. End's up in
Very mandatory. Extremely important. You cannot have a page without a title.
Never. Forget. The. Title.
-Depending on your template it will also be set inside "`<h1>...</h1>`" at the
-start of your web page.
+Here's a [[template_mako]] excerpt that uses this:
+
+ <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="${file.lang}" lang="${file.lang}">
+ <head>
+ <title>${file.title | entity}</title>
+ ...
+ </head>
+ <body>
+ <h1>${file.title</h1>
+ ...
+ </html>
== linktitle ==
If you don't specify this, then the documents "`mtime`" will be used instead.
+Here's a [[template_mako]] excerpt that uses this:
+
+ <%def name="footer()">\
+ <%
+ mtime = format_date(file.mtime)
+ ctime = format_date(file.ctime)
+ %>
+ <span id="foot">Created\
+ % if ctime == mtime:
+ ${mtime} \
+ % else:
+ ${ctime}, modified ${mtime} \
+ % endif
+ </span>
+ </%def>\
+
+This uses the named block feature of Mako, you can then place this
+text into your template with something like this:
+
+ <div class="content" id="foot">${self.footer()}</div>
+
+
== mtime ==
Here you can specify an ISO formatted date and or time specifier, which contains
If you don't specify this, then the "last-modified"-time from the file-system
will be used instead.
+For an example, look at <a href="#ctime">ctime</a> above.
+
== template ==
If you don't specify a description, then ${description} will be the empty string.
+Here's a [[template_mako]] excerpt that uses this:
+
+ <head>
+ ...
+ % if len(description):
+ <meta name="description" content="${description | entity}" />
+ % endif
+ ...
== keywords ==
If you don't specify a description, then ${keywords} will be the empty string.
+Here's a [[template_mako]] excerpt that uses this:
+
+ <head>
+ ...
+ % if len(keywords):
+ <meta name="keywords" content="${keywords | entity}" />
+ % endif
+ ...
+
== main_url ==
Used by [[google_sitemap]]:
-Internally, [[Webber]] works with relative URLs and is quite agonistic about
-the final website. However, the [[google_sitemap]] plugin needs absolute URLs,
-complete with host name. So we need this configuration ...
+Internally, [[Webber]] works with relative URLs and is quite agonistic
+about URL of the final website. However, the [[google_sitemap]] plugin
+needs absolute URLs, complete with host name.
Used by [[google_sitemap]]:
* monthly
* yearly
* never
+
+
+= Your own keywords =
+
+Inside the template, functions and macros you can access all entries
+by "`file.XXXX`" and you're free to invent your own keywords:
+
+ title: Impressum
+ subtitle: What you should know about this web-site
+
+ Hi, I'm Mario and I won't tell you more about me :-)
+
+Now you can access "`${file.subtitle}`" in your template or
+"`params.file.subtitle`" in your [[macros|macros]] and
+[[functions|functions]].
+
+
+= Page body =
+
+== Markdown page body ==
+
+Used for files ending with "`*.md`" and implemented by [[read_markdown]].
+
+Here's an example:
+
+ title: Nothin' about me
+
+ Hi, I'm Holger and I won't tell you more about me :-)
+
+
+== RST formatted ==
+
+Used for files ending with "`*.rst`" and implemented by
+[[read_rst]].
+
+
+
+== HTML formatted ==
+
+Used for files ending with "`*.html`" and implemented by [[read_html]].
+
+This is actually <b>not</b> really HTML, only the page body is HTML.
+You can use it when RST or Markdown can't format the contents the way
+you like it, e.g. when using complex tables.
+
+Here's an example:
+
+ title: Beruflicher Werdegang
+ linktitle: Werdegang
+ parent: Beruf
+ keywords: Lebenslauf, Werdegang
+ sitemap_changefreq: yearly
+ ctime: 2004-08-30
+ mtime: 2009-12-12
+
+ <hr size="1" />
+ <a href="#1979">1979</a>
+ <a href="#1980">1980</a>
+ ...
+ <hr size="1" />
+ ...
-title: Mako template
+title: Mako templates
linktitle: template_mako.py
parent: Plugins
lang: en
projects / webber.git / commitdiff