webgen 0.4.7 → 0.5.0

data/doc/src/documentation/references/webpage_format.page

@@ -1,253 +0,0 @@
----
-title: WebPage Format
-inMenu: true
----
-
-h1. The WebPage Format
-
-
-The WebPage Format is a custom format designed for page and template files. It consists of one or
-more blocks of data, is very simple and easy to use.
-
-
-h2(#structure). Structure
-
-
-A file using the WebPage Format consists of one or more blocks which are the smallest units
-recongnized. Blocks are separated from each other through a line containing only three dashes. This
-is illustrated in the following examples which are all valid files in WebPage Format:
-
-<pre>
-Here is a block!
-</pre>
-
-<pre>
-This is one block of the file
-\---
-This is another block.
-</pre>
-
-<pre>
-Block 1
-\--- block2
-Block 2
-\--- block3
-Block 3...
-</pre>
-
-If you want to use three dashes in a block but you don't want to end the block, you have to escape
-them with a backslash character, like this:
-
-<pre>
-Block 1
-\\---
-still Block 1
-\--- block2
-Block 2
-</pre>
-
-All of the above examples show one kind of block, the content block. However, there may also be
-another type of block: the meta information block. Following is a short description of both kinds,
-starting with the meta information block.
-
-
-h3(#metainfo-block). Meta Information Block
-
-
-Each file in WebPage Format can have zero or one meta information blocks. This block is specified at
-the beginning of the file. To tell the parser that the first block is the meta information block and
-not a content block, you have to start the file with three dashes:
-
-<pre>
-\---
-title: The title set by Meta info
-\---
-This is the content of the file
-</pre>
-
-The above defines a meta information block and a content block. The meta information block has to be
-in YAML format and should contain key-value pairs of meta information. YAML is a simple markup
-language designed for ease of use. For more information about YAML, have a look at
-"www.yaml.org":http://www.yaml.org!
-
-
-h3(#content-blocks). Content Blocks
-
-
-A content block is used to provide content in a specific format. Each file in WebPage Format needs
-to have at least one content block which may be empty. However, it can have as many content blocks
-as necessary. Each content block needs to have a unique name and a format specifier.
-
-The name uniquely identifies a content block and is used to access it. The format specifier defines
-in which format the content block was written. The important thing is that all the formats can be
-converted into HTML/XML! There are several different formats available - have a look a the {plugin:
-ContentConverter} section.
-
-There may also be defaults for the two identifiers but they can be overwritten. There are two ways
-to do this:
-
-* you either specify the name and format of the block on the line with the three dashes
-* or you use the special meta information block to define the names and formats of all blocks.
-
-The following example uses the first technique to override the name and/or the format:
-
-<pre>
-1. content block of the file
-\--- sidebar, markdown
-2. content block of the file
-\--- other
-3. content block of the file
-</pre>
-
-The first block has no identifieres set (there is no line with three dashes and the identifieres).
-Therefore the default values for both are used: @content@ is the default block name and @default@ is
-the default format specifier. However, these defaults can be overridden by the plugins.
-
-The second block is named @sidebar@ and uses the format @markdown@. As you see, first the name of
-the block is specified and then, separated by a comma, the format specifier. The format identifier
-can be omitted as shown for the third block, the default value is then used.
-
-You can also set the name and format of the content blocks by using the special @blocks@ meta
-information. It is an array of arrays and each sub-array contains, in this order, the name of the
-block and its format. The above example can therefore also be written like this:
-
-<pre>
-\---
-blocks: [[content,default], [sidebar, markdown], [other, ~]]
-\---
-1. content block of the file
-\---
-2. content block of the file
-\---
-3. content block of the file
-</pre>
-
-With everything said above the example should be clear except maybe for the last sub-array. The
-first entry specifies the name, @other@, and the second the format, @~@. The tilde has a special
-meaning in YAML format, namely null or empty. This means that we want to use the default format for
-the last block.
-
-The *default name* for a block is @content@ and is used if no explicit name is given on the line
-with the three dashes or in the blocks meta information at the correct index. The precedence is
-(from high to low): --- line, blocks meta information, default value.
-
-The *default format* for a block is @default@ and the rules stated above for the block name apply to
-the default format as well.
-
-
-h2(#tags). webgen Tags
-
-
-Tags are used to generate content. During processing of a file in WebPage Format so called 'tags'
-are replaced with dynamic content. For example, the menu you can see to the left was generated by a
-tag. This makes it easier to add or remove menu items. If the menu was not generated, you would have
-to change every file which uses the menu.
-
-
-h3(#tags-usage). Usage
-
-
-Tags are defined by a special markup code. A tag has the following structure:
-
-<pre>\{tagname: {parameters}}</pre>
-
-Every time a tag is found in a file, the registered plugin for the tag is called. The plugin returns
-a string which is put into the output file instead of the tag. The output a tag plugin can produce
-ranges from something simple to something complex. For example, the {plugin: Tag/Meta} plugin copies
-any additional meta information specified in the file verbatim into the correct place in the output
-file. And in contrast, the {plugin: Tag/Menu} plugin generates a whole menu tree.
-
-If you want to use the markup code used for tags, you need to escape the tag with a backslash, like
-this:
-
-<pre>\\\{tagname: {parameters}}</pre>
-
-
-h3(#tags-params). Parameters
-
-
-A tag can have zero or more parameters some of which are mandatory. You can see the supported
-parameters (and if they are mandatory) for each tag on the tag's plugin page. The default mandatory
-parameter can be specified in a special way, see the examples below. The format used for parsing the
-parameters is YAML.
-
-Here some examples with tags and parameters:
-
-<table class="examples">
-<tr>
-  <th>Usage</th><th>Output</th>
-</tr>
-<tr>
-  <td>@\{tagname: }@</td>
-  <td>No parameters specified</td>
-</tr>
-<tr>
-  <td>@\{tagname: test.html}@</td>
-  <td>The default mandatory parameter is set to @test.html@. This form can only be used if there is only one mandatory parameter</td>
-</tr>
-<tr>
-  <td>@\{tagname: {param1: value1, param2: value2}}@</td>
-  <td>Two parameters (param1 and param2) specified</td>
-</tr>
-</table>
-
-
-h2(#processing). Processing
-
-
-There is a well defined procesing order for files in WebPage Format:
-
-* After reading in the file, it is split into the blocks.
-* Each content block is converted to HTML (depends on the format specifier) and the HTML sections
-  are resolved (caveat: only those with an @id@ attribute)
-* When writing out the file, the converted content is first processed with ERB (if specified to do
-  so),
-* then webgen tags are replaced and,
-* finally, the result is written.
-
-The first two steps happen when the file is read and the last three when the file is written.
-
-
-h3(#proc-html). Converting to HTML
-
-
-The conversion of a content block to HTML is done via the {plugin: ContentConverter} plugins. Each
-plugin is able to convert a special marked-up text to HTML.
-
-
-h3(#proc-erb). Evaluating ERB Tags
-
-
-The evaluation of ERB (embedded ruby) tags is optional and only done if the meta information
-@useERB@ is set to @true@. The use of ERB allows to add dynamic content without using webgen tags.
-Following is an example of a file which uses ERB:
-
-<notextile>
-<pre>
-\---
-title: Test page with ERB
-useERB: true
-\---
-This page has the following meta info items:
-&lt;% node.meta_info.each do |key, value| %&gt;
-    * &lt;%=key %&gt;: &lt;%=value %&gt;
-&lt;% end %&gt;
-</pre>
-</notextile>
-
-This would output all meta information for the file. There are some objects available which you can
-use in your ERB code:
-
-* @node@: the node for the current file (normally a page file)
-* @ref_node@: the reference node, i.e. the node in which the content will be embedded (normally a
-  template file)
-
-*Caveat*: you may need to ensure that the ERB start and end tags are not processed by the content
-converter. For example, with Textile you may need to surround the ERB code with &lt;textile&gt;
-tags!
-
-
-h3(#proc-tags). Evaluating webgen Tags
-
-
-Tags have already been mentioned in the <a href="{relocatable: '#tags'}">webgen tags</a> section.

data/doc/src/documentation/tutorial.page

@@ -1,167 +0,0 @@
----
-title: Tutorial
-inMenu: true
----
-h1(#website-creation). Tutorial
-
-
-This short tutorial shows you how to create a website with webgen.
-
-
-h2(#website-structure). Creating the Basic Directories
-
-
-First, you need to create the basic directories. You can either do this by hand or you can let
-webgen do this:
-
-<pre>
-  $ webgen create sample_site
-</pre>
-
-webgen created the @sample_site@ directory which holds all directories necessary for running webgen.
-
-The @create@ command also accepts two options: one for a website template and one for a website
-style:
-
-* A *website template* defines a structure 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 some predefined
-  styles which you can use (most of them are converted open source web design styles).
-
-You can change the website style later by using the @use website_style@ command for @webgen@, for
-example:
-
-<pre>
-  $ webgen use website_style default
-</pre>
-
-Existing files may be overwritten by this command (after asking). However, this command is not able
-to delete previously copied website style files, so you have to remove them yourself!
-
-Have a look at the <a href="{relocatable: /examples}">examples</a> sections to see demonstrations
-for all shipped website templates and styles!
-
-Now you can run webgen to create your website. There are two possibilities:
-
-* Either change into the @sample_site@ directory and run webgen there, like this
-  <pre>
-  $ cd sample_site
-  sample_site $ webgen
-  </pre>
-* Or you can run webgen like this
-  <pre>
-  $ webgen -d sample_site
-  </pre>
-
-Easy! webgen has parsed the @src@ directory and has created the HTML output. However, as we did not
-write any content yet, there is not much to see (only the default page). So let's do that now!
-
-
-h2(#website-content). Adding Content to the Website
-
-
-When using the @create@ command, webgen does not only create the needed directories but it also
-provides you with some default files, you should 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 page for the root directory of the website.
-
-The basic scaffolding is already in place, we only have to change @index.page@ and add other page
-files. Just open the file @index.page@ in your favorite text editor and change its content. After
-that we create a new file, @hello.page@, with the following content:
-
-<pre>
-\---
-title: Sample hello page
-inMenu: true
-\---
-This is a sample page with the title "{title:}" and it is in the menu!!!
-</pre>
-
-After that, run webgen and then open @output/index.html@ to view your website.
-
-Then just add page files and other content to your website and let it grow!
-
-
-h2(#website-metainfo). Using Tags and Meta Information in Pages
-
-
-Meta information is specified at the beginning of a page file. Have a look at the
-<a href="{relocatable: /documentation/references/webpage_format.page}">WebPage Format reference</a>
-to see how that is done in detail!
-
-We are now going to use meta information to customize our website! Open the file @default.template@
-and add this before the &lt;/body&gt; tag:
-
-<pre>
-  File last changed on \{filemdate: }!
-</pre>
-
-The part @\{filemdate: }@ is called a tag. Tags are implemented using plugins and they can be used to
-insert dynamic content when webgen is run. For example, the menu on the page is generated with the
-@\{menu: }@ tag! If webgen sees a tag during the processing of a page for which no tag plugin
-exists, it looks at the meta information of the page. If there is a meta information entry with the
-tag name, it uses that content instead. We will use that now!
-
-Open the file @hello.page@ and add the following meta information:
-
-<pre>
-filemdate: 10.4.2005
-</pre>
-
-so that @hello.page@ looks like this:
-
-<pre>
-\---
-title: Sample hello page
-inMenu: true
-filemdate: 10.4.2005
-\---
-This is a sample page with the title "{title:}" and it is in the menu!!!
-</pre>
-
-Run webgen and view the output! The tag @\{filemdate: }@ got substituted by the value specified in
-the meta information. As we have not put any meta information in the @index.page@ file, a warning is
-issued when webgen is run and no date is shown on the page!
-
-
-h2(#website-plugin). Writing a Simple Plugin
-
-
-Because we are not quite happy with our basic file modification time tag, we are going to write a
-simple tag plugin.
-
-Create the file @plugin/filemdate.rb@ with the following content:
-
-<pre>
-class FileMDateTag < Tags::DefaultTag
-
-  infos( :name => 'Custom/FileMDate',
-         :summary => "Puts the modification time of the file on the page" )
-
-  register_tag 'filemdate'
-
-  def process_tag( tag, chain )
-    return File.mtime( chain.last.node_info[:src] ).to_s
-  end
-
-end
-</pre>
-
-That's all! The new plugin gets loaded when webgen starts and it is used when the tag @filemdate@ is
-encountered. We can now safely remove the @filemdate@ meta info from the file @hello.page@ although
-you can leave it there - it won't do any harm.
-
-Again, just run webgen and view the output!
-
-For more information on how to write plugins have a look at the
-<a href="{relocatable: extending_webgen.page}">extending webgen section</a>!
-
-
-h2(#website-conclusio). Conclusion
-
-
-You have just created a simple static website using webgen. For further information on how to
-procede from here have a look at the <a href="{relocatable: plugins}">plugins section</a> and the
-other documentation.

data/doc/src/download.page

@@ -1,74 +0,0 @@
----
-title: Download & Installation
-inMenu: true
----
-h2(#download). Download
-
-
-The newest version of webgen can be downloaded from Rubyforge.
-
-Homepage: "webgen.rubyforge.org":http://webgen.rubyforge.org
-
-Download: "http://rubyforge.org/frs/?group_id=296":http://rubyforge.org/frs/?group_id=296
-
-
-h2(#deps). Dependencies
-
-
-* "cmdparse":http://cmdparse.rubyforge.org version 2.0.0 or higher
-
-* "RedCloth":http://redcloth.rubyforge.org version 2.0.10 or higher for Textile support (needed for examples
-  and included website templates)
-
-* [optional] "BlueCloth":http://www.deveiate.org version 1.0.0 or higher if you want Markdown
-  support
-
-* [optional] "RMagick":http://rmagick.rubyforge.org/ version 1.7.1 or higher if you want automatic
-  thumbnail creation for image galleries
-
-* [optional] "builder":http://builder.rubyforge.org/ version 2.0.0 or higher if you want programatic
-  HTML/XML file generation
-
-* [optional] "exifr":http://exifr.rubyforge.org/ version 0.10 or higher if you want to be able to
-  have EXIF information available for image galleries
-
-* [optional] "coderay":http://coderay.rubychan.de/ version 0.7.4.215 or higher if you want syntax
-  highlighting to be available for certain plugins
-
-
-All the optional libraries can be installed via Rubygems (which I recommend). You can check the
-availability of the libraries by executing
-
-  $ webgen check libs
-
-The output tells you whether webgen has been able to load the optional libraries or not!
-
-
-h2(#installation). Installation
-
-
-The easiest way to install webgen is via Rubygems
-
-  $ gem install webgen
-
-However, you can also use the included @setup.rb@ installation method:
-
-  $ ruby setup.rb config
-  $ ruby setup.rb setup
-  $ ruby setup.rb install
-
-Or all commands together via
-
-  $ rake install
-
-
-The above listed methods also work when installing on Windows (preferred way is via Rubygems).
-
-
-
-
---- sidebar, textile
-
-<h1>Information</h1>
-
-webgen has been tested on Linux and on Windows XP with Ruby 1.8.4.