From: Holger Schurig Date: Tue, 6 Jul 2010 11:22:23 +0000 (+0200) Subject: docs: many misc enhancements and clarifications X-Git-Url: https://oss.titaniummirror.com/gitweb?p=webber.git;a=commitdiff_plain;h=07e692ef713a7d0d65296cd62b978539ac1ed683 docs: many misc enhancements and clarifications --- diff --git a/in/commandline.md b/in/commandline.md index a2c49d4..2774b99 100644 --- a/in/commandline.md +++ b/in/commandline.md @@ -5,12 +5,15 @@ lang: en 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 @@ -51,5 +54,3 @@ to increase even more. With "`-k`" or "`--keepgoing`" you can tell webber to ignore errors in one page and continue with the next page. - - diff --git a/in/configuration.md b/in/configuration.md index f5e2809..1c6969d 100644 --- a/in/configuration.md +++ b/in/configuration.md @@ -2,89 +2,153 @@ title: Configuration 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: + +

Category: ${page.category}

diff --git a/in/functions.md b/in/functions.md index 9ee7949..38a5d1e 100644 --- a/in/functions.md +++ b/in/functions.md @@ -5,12 +5,15 @@ ctime: 2009-06-24 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: @@ -87,10 +90,6 @@ Returns an unsorted list with the hierarchy of the table-of-contents. Defined in [[toc.py|toc]], where you find an example. -== func == - -A sample function in the [[skeleton.py|skeleton]]. See below. - = Writing functions = diff --git a/in/hooks.md b/in/hooks.md index 6a3284a..d1cfdb8 100644 --- a/in/hooks.md +++ b/in/hooks.md @@ -2,10 +2,33 @@ title: Hooks 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 addoptions below. + + += Hooks fired at startup = + +When you start "`webber`", the following hooks are executed: == addoptions == @@ -54,12 +77,14 @@ Example: 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 @@ -68,7 +93,8 @@ If they do, the plugin should also set "`file.render`" is normally "`html"`. 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 @@ -103,14 +129,15 @@ Example: 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 == @@ -127,20 +154,25 @@ uses this to sort links. * "`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 @@ -151,7 +183,8 @@ The first hook that returns HTML, no other hooks will be called. 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]]. @@ -162,10 +195,10 @@ 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 @@ -173,11 +206,14 @@ called. == 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 @@ -185,12 +221,14 @@ The first hook that returs anything wins, no other hooks will be called. = 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). diff --git a/in/inheritance.md b/in/inheritance.md index a165173..89c7502 100644 --- a/in/inheritance.md +++ b/in/inheritance.md @@ -1,34 +1,58 @@ 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. 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. +* "`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() + %> + diff --git a/in/macros.md b/in/macros.md index abf9634..757e7ad 100644 --- a/in/macros.md +++ b/in/macros.md @@ -4,13 +4,12 @@ lang: en ctime: 2009-06-24 mtime: 2009-06-26 -= Calling macros = - Macros are executed whenever the sequence -"[[!name]]" or -"[[!name args]]" is in the source-file. +"[[!name]]" or "[[!name +arg1="1" arg2="2"...]]" 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 = @@ -26,13 +25,17 @@ to be decorated with "`@set_macro(name)`". There's an example in 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. "[[!sample -arg1="string"]]". This will yield +You can submit additional string arguments, e.g. with +"[[!sample arg1="string"]]". Now you get +additionally: * "`params.arg1`" contains "`string`" diff --git a/in/pageformat.md b/in/pageformat.md index 12a1d48..01568fb 100644 --- a/in/pageformat.md +++ b/in/pageformat.md @@ -2,49 +2,23 @@ title: Page format 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 header, then a blank +line, then the page body. 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 @@ -53,8 +27,17 @@ 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 "`

...

`" at the -start of your web page. +Here's a [[template_mako]] excerpt that uses this: + + + + ${file.title | entity} + ... + + +

${file.title

+ ... + == linktitle == @@ -97,6 +80,28 @@ the document creation date/time. Examples: 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) + %> + Created\ + % if ctime == mtime: + ${mtime} \ + % else: + ${ctime}, modified ${mtime} \ + % endif + + \ + +This uses the named block feature of Mako, you can then place this +text into your template with something like this: + +
${self.footer()}
+ + == mtime == Here you can specify an ISO formatted date and or time specifier, which contains @@ -108,6 +113,8 @@ the document modification date/time. Examples: If you don't specify this, then the "last-modified"-time from the file-system will be used instead. +For an example, look at ctime above. + == template == @@ -132,6 +139,14 @@ You can use this for HTML meta information, see [[template_mako]]. If you don't specify a description, then ${description} will be the empty string. +Here's a [[template_mako]] excerpt that uses this: + + + ... + % if len(description): + + % endif + ... == keywords == @@ -140,14 +155,23 @@ You can use this for HTML meta information, see [[template_mako]]. If you don't specify a description, then ${keywords} will be the empty string. +Here's a [[template_mako]] excerpt that uses this: + + + ... + % if len(keywords): + + % 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]]: @@ -171,3 +195,64 @@ Should be one of the following values: * 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 not 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 + +
+ 1979 + 1980 + ... +
+ ... diff --git a/in/plugins/template_mako.md b/in/plugins/template_mako.md index 5a7f8f1..b7ae137 100644 --- a/in/plugins/template_mako.md +++ b/in/plugins/template_mako.md @@ -1,4 +1,4 @@ -title: Mako template +title: Mako templates linktitle: template_mako.py parent: Plugins lang: en