thewoolleyman-webgen 0.5.8.20090419

data/doc/extensions.metainfo

@@ -0,0 +1,29 @@
+contentprocessor/:
+  index_path: ~
+
+contentprocessor/*:
+  template: ../contentprocessor.template
+
+sourcehandler/:
+  index_path: ~
+
+sourcehandler/*:
+  template: ../sourcehandler.template
+
+tag/:
+  index_path: ~
+
+tag/*:
+  template: ../tag.template
+
+source/:
+  index_path: ~
+
+source/*:
+  template: ../extensions.template
+
+output/:
+  index_path: ~
+
+output/*:
+  template: ../extensions.template

data/doc/extensions.page

@@ -0,0 +1,16 @@
+---
+title: Extensions
+---
+# Extension Listing
+
+Following is a listing of all available extensions:
+
+<%
+pattern = /#{File.join(node.parent.absolute_lcn, '/')}(contentprocessor|output|source|sourcehandler|tag|)\/.*html$/
+context.content_node.tree.node_access[:alcn].select {|alcn, n| alcn =~ pattern}.sort.each do |alcn, n|
+next if n.is_fragment?
+%>
+* <%= dest_node.link_to(n) %>
+<%
+end
+%>

data/doc/extensions.template

@@ -0,0 +1,17 @@
+--- pipeline:erb,tags,maruku,blocks
+[Back]({relocatable: extensions.html}) to the extension listing.
+{.backlink}
+
+# {title:}
+
+<% if (context[:chain][1] || context[:chain][0]).node_info[:page].blocks.has_key?('summary') %>
+## Summary
+
+<webgen:block name='summary' />
+
+<% end %>
+
+<webgen:block name='content' />
+
+[Back]({relocatable: extensions.html}) to the extension listing.
+{.backlink}

data/doc/faq.page

@@ -0,0 +1,219 @@
+---
+title: FAQ
+---
+# General Questions
+
+*   **webgen fails with an error after upgrading to a newer version - what to do?**
+
+    Delete the cache file and try again. The structure of the cache may not be valid anymore after a
+    version update. So it is always good to delete the cache after installing a new webgen version.
+
+*   **Why can I specify multiple blocks in a page/template file?**
+
+    This allows you to provide different content parts for one page. For example, image you have a
+    layout with a sidebar and you want to have page specific sidebar contents. The easiest way to
+    achieve that is to add a `sidebar` block to the page files that provide a page specific sidebar
+    content and conditionally include the `sidebar` block in your `default.template`, like this:
+
+        <%% if node.node_info[:page].blocks.has_key?('sidebar') %>
+          \<webgen:block name='sidebar' />
+        <%% end %>
+
+*   **What do I have to do to use the extensions?**
+
+    Nothing! Extensions are initialized and used automatically when needed. So, for example, if you
+    add a `my.feed` file to your website, the `Webgen::SourceHandler::Feed` extension gets
+    automatically used. The same is true for all types of extensions (source handler, content
+    processors, tags, ...).
+
+*   **Is there any way to add comments to my webgen website?**
+
+    Surely! There are several comment engines out there, however, the following two look very
+    promising:
+
+    * [JS-Kit](http://js-kit.com/comments/)
+    * [DISQUS](http://disqus.com)
+
+# How to ...
+
+This section provides quick answers and links to more information for the most commonly asked
+questions.
+
+### ... create a website?
+
+Use the `webgen` command to create the needed directories
+
+    webgen create -t project -s andreas07 my_site
+
+This will create a webgen website in the directory `my_site` using the specified template and style.
+
+### ... set configuration options?
+
+You can set any configuration options via the configuration file called `config.yaml`. For example,
+say you want to set the option `website.link_to_current_page` to `true`, then you would add the
+following to the configuration file:
+
+    website.link_to_current_page: true
+
+There is a second possibility for webgen tags: you can set the options directly in the tag
+definition, like this:
+
+    \{menu: {start_level: 2, min_levels: 3}}
+
+And if you want to have complete control over the configuration options, you can use the file
+`ext/init.rb`. For example, the following specifies that all page files should be in the menu by
+default:
+
+    config = Webgen::WebsiteAccess.website.config
+    config['sourcehandler.default_meta_info']['Webgen::SourceHandler::Page']['in_menu'] = true
+
+### ... change the default language?
+
+To use, for example, German as the default language, put the following into the configuration file:
+
+    website.lang: de
+
+The value needs to be a valid ISO-639-1/2 language code.
+
+### ... use a different processing pipeline for page files?
+
+If you want to change the processing pipeline (ie. how a page file get rendered), you need to add
+the following to your configuration file:
+
+    default_processing_pipeline:
+      Page: erb,tags,textile,blocks
+
+The `default_processing_pipeline` key is a special key which allows to directly set the processing
+pipeline (instead of going through all the meta information).
+
+If you just want to change the pipeline for one block, you can do it like this:
+
+    --- pipeline:erb,tags,textile,blocks
+    This is the content of the block
+
+### ... set the default meta information for files created by a specific source handler?
+
+Use the configuration file! For example, to change the meta information `in-menu` sothat it defaults
+to `true` for all page files use the following in your configuration file:
+
+    default_meta_info:
+      Page:
+        inMenu: true
+
+The key `default_meta_info` is a special key in the configuration file which allows to update the
+default meta information for a source handler and not to substitute it.
+
+### ... ignore files in the source directory?
+
+This can be done using the `sourcehandler.ignore` configuration options. For example, to ignore all
+files starting with `core`, you would put the following in the configuration file:
+
+    sourcehandler.ignore: [**/core*]
+
+The value of this option has to be an array of path patterns. Be aware that this overwrites the
+default setting.
+
+### ... change the output name style?
+
+You have several options of varying granularity:
+
+* Set the meta information `output_path_style` for all source handlers:
+
+      default_meta_info:
+        :all:
+          output_path_style: [:parent, :cnbase, [., :lang], :ext]
+
+* Set the meta information `output_path_style` for a specific source handler to only change the
+  output paths of this source handler (the page source handler in the following example):
+
+      default_meta_info:
+        Page:
+          output_path_style: [:parent, :cnbase, [., :lang], :ext]
+
+* Add the meta information `output_path_style` to a single file via, for example, a meta information
+  backing file.
+
+### ... modify the template chain?
+
+To stop the template chain at a specific template or even at the page file itself, specify a
+null template in the meta information, like this:
+
+    template: ~
+
+To nest templates, you just need to specify the template, in which this template/page file should be
+nested, in the meta information:
+
+    template: my_special.template
+
+Be aware that if no `template` meta information is specified for a page or template file, the
+template handler automatically searches for a default template in the directory and the parent
+directories of the file!
+
+### ... localize a directory name?
+
+Just set the `routed_title` meta information on the correct localized directory index files.
+
+### ... provide additional attributes on links to a file?
+
+You can specify additional attributes for a link to a file by using the `link_attrs` meta
+information. Take the following page file:
+
+    ---
+    title: Tutorial
+    in_menu: true
+    link_attrs:
+      title: This is a rather large tutorial
+      accesskey: D
+      tabindex: 5
+    ---
+    Yippieh, this is my tutorial!
+
+When a link to this page is created, the specified attributes get additionally set on the link!
+
+### ... add page specific sidebar content?
+
+There are many ways to accomplish this, I will show only one way here using blocks. Add the
+following to the sidebar part in your `default.template` (ensure that you haven't disabled `erb` in
+the processing pipeline):
+
+    <%% if node.node_info[:page].blocks.has_key?('sidebar') %>
+      <webgen:block name='sidebar' />
+    <%% end %>
+
+This will include the contents of the block `sidebar` in the sidebar if such a block exists for a
+page. You can then add a sidebar block to each page file which needs it. Following is such a sample
+page file:
+
+    This is the main content block
+    --- name:sidebar
+    This is the sidebar block and everything in here goes to the sidebar!
+
+You can avoid using the ERB processor if you use the following syntax (available from version 0.5.7
+upwards):
+
+    <webgen:block name='sidebar' node='first' notfound='ignore' />
+
+### ... create XML output?
+
+This can be achieved manually (by removing any markup processor in the processing pipeline of the
+page file and then directly creating the XML elements) or by changing the processing pipeline to
+include content processor `builder` which provides an easy way of programmatically creating an XML
+compliant file. More information on this can be found on the documentation page of
+Webgen::ContentProcessor::Builder!
+
+### ... create a static menu?
+
+You can use virtual nodes to define virtually any menu structure you like, including things like
+having menu entries that point to the same page and links to external pages.
+
+### ... use short menu title?
+
+You can use a special of the meta information `link_attrs` to achieve that. Just use the following
+in the meta information block of the page file for which you want a short menu title:
+
+    link_attrs:
+      :link_text: Short title
+
+> Be aware that this changes not only how the page appears in a menu but also how it appears in
+> breadcrumb trails and other links generated by webgen.
+{.important}

data/doc/getting_started.page

@@ -0,0 +1,135 @@
+---
+title: Getting Started Guide
+---
+## Tutorial: Creating a Basic Website
+
+
+### Creating the Basic Directories
+
+webgen needs a special directory structure so that it works out of the box. Basically, you have a
+website directory under which the following directories are located:
+
+* `src`: The source directory in which all the source files for the website are.
+
+* `out`: This directory is created, if it does not exist, when webgen generates the HTML files. All
+  the output files are put into this directory.
+
+* `ext`: The extension directory (optional). You can put self-written extensions into this directory
+  so that they are used by webgen.
+
+The directory in which these directories are in is called the *website directory*.
+
+Don't worry too much about these directories since webgen is able to create the correct directory
+structure for you. By running the command `webgen create sample_site`, the website directory
+`sample_site` is created with the default website template and website style. You can naturally use
+any available template or style by passing their names to the respective options of the `create`
+command.
+
+> A *website template* provides a starting point for your website. For example, the `project`
+> template defines several pages including a features and about page.
+>
+> A *website style* defines the look and feel of your website. webgen comes with many predefined
+> styles (nearly all of them are converted open source web design styles).
+{.information}
+
+Don't worry if you don't like the used website style - you can easily change it later using the
+`webgen apply` command. Have a look at [the examples
+section](0.4.x/examples/website_styles/index.html) (note: these are still the example from the
+previous version of webgen but the styles haven't changed) to see demonstrations for all shipped
+website templates and styles!
+
+Since the basic parts are now in place, you can generate the HTML files. There are two
+possibilities:
+
+* Either you change into the `sample_site` directory and run the command `webgen`.
+
+* Or you run webgen from any directory and specify the website directory using the `-d` option, for
+  example `webgen -d sample_site`.
+
+Easy! webgen has used all files in the `src` directory and created the HTML output in the directory
+`out`. Now you just need to open the `out/index.html` file to view your website! However, as we did
+not write any content yet, there is not much to see (only the default pages). So let's do that now!
+
+> Since webgen automatically creates relative links, you will have a fully functional website
+> without needing a web server! This also implies that you can deploy your website to any directory
+> on your web server and it will just work!
+{.information}
+
+
+### Adding Content
+
+When using the `create` command, webgen does not only create the needed directories but it also
+provides you with some default files, you will normally have at least the following ones:
+
+* `src/default.template`: The default template for the new website.
+* `src/default.css`: The default css file for the new website.
+* `src/index.page`: The index file for the root directory of the website.
+* `config.yaml`: The configuration file for setting configuration options.
+
+> *Template files* and *page files* are the heart of webgen. Template files are used to define a
+> general layout for web pages and page files define the real content. Both file types are written
+> in [Webgen Page Format]({relocatable: webgen_page_format.html}). Page files are normally written
+> in a markup language like Markdown or Textile which is easier to learn and edit for non-technical
+> persons.
+{.information}
+
+The basic scaffolding is already in place. Now we only have to adapt the page file `index.page` and
+add other page files.
+
+All page files are written using the Webgen Page Format. Basically, you have an optional meta
+information block at the beginning of the file and one or more content blocks. Blocks are separated
+by three dashes (ie. `---`) on a separate line and if you want to have a meta information block you
+need to have a block separator line at the beginning of your file.
+
+Open the file `index.page` in your favorite text editor and change its content (ie. the first
+content block). After that create a new file, `hello.page`, in the source directory with the
+following content:
+
+    ---
+    title: Sample hello page
+    in_menu: true
+    ---
+    This is a sample page with the title "\{title:}" and it is in the menu!!!
+
+We define two meta information items (namely `title` and `in_menu`) and added some content to the
+first content block. Run webgen again and open `out/index.html` to view your changes. Add
+page files and other content to your website and let it grow!
+
+
+### Adding Dynamic Content
+
+A static website is, as the name implies, static. However, since we generate the website it is
+possible to add some dynamicity to it. For example, it gets very tedious to update menu links every
+time we add a file that should be in the menu.
+
+Therefore webgen provides two ways to add dynamic content out of the box:
+
+* *ERB*: This term stands for "embedded ruby". It means that you can embed ruby statements in page
+   and templates files that get evaluated when the files are rendered.
+
+* *webgen tags*: These are a way to add dynamic content without knowing a programming language
+   (although limiting you to the existing tags). You just state what tag you want to use and it does
+   its job. For example, there exists a very flexible menu generation tag.
+
+You have already encountered a webgen tag in the last section when you created the `hello.page`
+file: the `\{title:}` part. webgen tags can generally be specified like this: `\{tagname: {param:
+value, param2: value2}}`. For detailed information on tags have a look at the
+[Webgen::ContentProcessor::Tags]({relocatable: contentprocessor/tags.html}) documentation.
+
+
+### Setting configuration options
+
+webgen provides a default configuration out of the box. If you can live with that, you do not need
+to change any configuration option. However, most users need to change some configuration option
+sometime. The configuration file is called `config.yaml` and has to be placed directly under the
+website directory. It uses YAML as file format.
+
+> Have a look at the [Configuration Options Reference]({relocatable: reference_configuration.html})
+> to get an overview over all available configuration options.
+{.information}
+
+Each configuration option can be set in the configuration file by specifing the configuration option
+name and the new value as a key/value pair. A sample configuration file looks like this:
+
+    website.lang: de
+    website.link_to_current_page: true

data/doc/index.page

@@ -0,0 +1,65 @@
+---
+title: Overview
+in_menu: false
+---
+
+This documentation is for the *repository version*{: style='color: red; font-weight: bold'} of
+webgen and therefore may state features that are not available in the latest released version.
+
+* The documentation for the *latest released 0.5.x*{: style='color: red; font-weight: bold'} version
+  can be found [here](http://webgen.rubyforge.org/documentation/0.5.x/index.html)
+
+* If you are looking for the documentation of the *0.4.x*{: style='color: red; font-weight: bold'}
+  series, it can be found [here](http://webgen.rubyforge.org/documentation/0.4.x/index.html).
+
+If you don't find an answer to your questions in the documentation, there are also:
+
+* [forums][forum] hosted on Rubyforge
+* [mailing lists][ml] hosted on Rubyforge (the `webgen-users` mailing list is mirrored to the
+  [webgen-users google group][google-group])
+* the IRC channel `#webgen` on Freenode where I can be found whenever I'm online.
+
+[forum]: http://rubyforge.org/forum/?group_id=296
+[ml]: http://rubyforge.org/mail/?group_id=296
+[google-group]: http://groups.google.com/group/webgen-users/
+
+# User Documentation
+
+Depending on whether you are new to webgen, you want more information about a specific topic or read
+a reference, go to one of the following pages:
+
+* [**Getting Started Guide**]({relocatable: getting_started.html}): If you are new to webgen, this
+  should be your first read. It explains the usage of the CLI command and how to create your first
+  website with webgen.
+
+* [**Manual**]({relocatable: manual.html}): Detailed information about how webgen works can be found
+  here. After reading the Getting Started Guide, this should be the next read. Have a look at the
+  section headers to get a quick overview of what can be found here.
+
+* [**FAQ**]({relocatable: faq.html}): If you want to do something with webgen, but you don't know
+  how, this page is exactly for you. It provides answers to frequently asked questions and
+  HowTos. If you have a question which you think should be added, just mail me.
+
+* [**Upgrade information**]({relocatable: upgrading.html}): This document provides some information
+  on upgrading a website from the 0.4.x to the 0.5.x series.
+
+
+Following is a list of all the reference documentation of webgen:
+
+* [**Extensions Documentation**]({relocatable: extensions.html}): Detailed information on every usage
+  related extension class (**source handlers, tags, content processors**, ...)
+
+* [**Webgen Page Format**]({relocatable: webgen_page_format.html}): Information about/Specification of
+  the format used, for example, by page and template files
+
+* [**Meta Information Reference**]({relocatable: reference_metainfo.html}): Descriptions for every
+  meta information key that is used by webgen.
+
+* [**Configuration Options Reference**]({relocatable: reference_configuration.html}): Overview of all
+  configuration options.
+
+# Developer Documentation
+
+webgen makes it easy to extend its functionality by writing simple extension classes. All
+information about how to do this is provided in the [API documentation](rdoc/index.html). You will
+also find examples for all existing extension types there.