webgen 0.3.0

data/doc/src/documentation/index.page

@@ -0,0 +1,47 @@
+---
+directoryName: Documentation
+---
+h2. Information
+
+p={font-size: 150%; color: red}. *!!! This documentation is for Webgen {version: } !!!*
+
+h2. Usage
+
+Webgen uses two directories: one to read the source files from and an other to write the output
+files to. The default source directory is @src@ and the default output directory is @output@. The
+source directory can be structured in any way you like, there is no restriction in respect of the
+number of directories or files.
+
+To build the website you simple need to change to the parent directoy of the source directory and
+type @webgen@. If everything is okay, no output will appear and you can point your browser to the
+output directory and view your website. If not, webgen tries to give detailed information about what
+happened and why something could not be done correctly.
+
+Webgen tries to compensate for errors and warnings and _should_ not abort with an error. Instead, it
+uses default values in error or warning cases and only issues messages to the log device (normally
+the screen). This also means that if a library is not found (e.g. RedCloth for Textile support),
+the plugin which uses the library is disabled.
+
+h2. Configuration
+
+Webgen provides a default configuration out of the box. If you can live with that, you do not need
+to write any configuration files. Because most people cannot, you can use your own configuration
+file. The configuration file has to be written in YAML and is called @config.yaml@. Webgen searches
+in the current directory for the configuration file.
+
+If you want to get the configuration values you can run webgen like this
+<pre>
+  $ webgen -c
+</pre>
+
+The list shows sorted by the plugin name the current values and the default values for each
+configuration option. Each option can be overridden in the configuration file by specifing the
+plugin name as top level key and each configuration option as a key/value pair. A configuration file
+looks like this:
+
+<pre class="webgen-file">{includeFile: /../../../testsite/config.yaml}</pre>
+
+h2. Plugins
+
+Webgen is written with extensibility in mind; therefore most of its features are implemented with
+plugins, only the core functions are not plugins.

data/doc/src/documentation/tags/date.page

@@ -0,0 +1,19 @@
+---
+title: Date
+inMenu: true
+---
+h2. Information
+
+<notextile>{describe: DateTag}</notextile>
+
+h2. Description
+
+The date tag is used to display the current time in a specific format. You can see how the default
+output looks like in the footer.
+
+h2. Examples
+
+table{border:1px solid black}.
+|_.Command|_.Output|
+|\{date: {format: %Y-%m-%d %H:%M:%S}}|{date: {format: %Y-%m-%d %H:%M:%S}}|
+|\{date: {format: %x - %X}}|{date: {format: %y - %X}}|

data/doc/src/documentation/tags/executecommand.page

@@ -0,0 +1,19 @@
+---
+title: Execute Command
+inMenu: true
+---
+h2. Information
+
+<notextile>{describe: ExecuteCommandTag}</notextile>
+
+h2. Description
+
+The execute command tag is used to include the output from a shell command.
+
+h2. Examples
+
+table{border:1px solid black}.
+|_.Command|_.Output|
+|\{execute: date}|<pre class="webgen-file">{execute: date}</pre>|
+|\{execute: ls}|<pre class="webgen-file">{execute: ls}</pre>|
+|\{execute: uname -p}|<pre class="webgen-file">{execute: uname -p}</pre>|

data/doc/src/documentation/tags/includefile.page

@@ -0,0 +1,15 @@
+---
+title: Include File
+inMenu: true
+---
+h2. Information
+
+<notextile>{describe: IncludeFileTag}</notextile>
+
+h2. Description
+
+The include file tag is used to include the contents of a file.
+
+h2. Examples
+
+<pre class="webgen-file">{includeFile: {filename: includefile.page, processOutput: false}}</pre>

data/doc/src/documentation/tags/index.page

@@ -0,0 +1,39 @@
+---
+directoryName: Tags
+---
+h2. About
+
+Tags are used to generate content. During processing of the page description files so called 'tags'
+are substituted. For example, the menu you see to left was generated. 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.
+
+Webgen comes bundled with some default tag plugins. All currently available tags are exercised in
+this online demo. Choose a tag from the menu to get a detailed description of the tag.
+
+h2. Usage
+
+Tags are defined by a special markup code. A tag has the following structure:
+
+<pre class="webgen-file">\{tagname: {parameters}}</pre>
+
+Every time a tag is found in a source 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 <a href="{relocatable: meta.html}">
+Meta Tag</a> plugin copies any additional info specified in the source file verbatim
+into the correct place in the output file. And in contrast, the <a href="{relocatable: menu.html}">
+Menu Tag</a> plugin generates a whole menu tree.
+
+h2. Tag 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 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.
+
+h2. Examples
+
+table{border: 1px solid black}.
+|^. @\{tagname: }@|^. No parameter specified|
+|^. @\{tagname: test.html}@|^. The default mandatory parameter is set to @test.html@. This form can only be used if there is only one mandatory parameter|
+|^. @\{tagname: {param1: value1, param2: value2}}@|^. Two parameters (param1 and param2) specified|

data/doc/src/documentation/tags/lang.de.page

@@ -0,0 +1,6 @@
+---
+title: Tag für Sprache
+---
+h2. Information
+
+Die deutsche Seite... enthält nicht viel Information :-)

data/doc/src/documentation/tags/lang.page

@@ -0,0 +1,27 @@
+---
+title: Language
+inMenu: true
+---
+h2. Information
+
+<notextile>{describe: LanguageTag}</notextile>
+
+h2. Description
+
+The language tag is used to display a list of languages for a page. Take a look at the lower right
+corner of the header. There you will find a link titled 'en'. This is the link to the english (=en)
+version of this page. As this page is not translated into any other language, there is only this one
+item.
+
+h2. Examples
+
+Here is a <a href="{relocatable: multilang.html}">link</a> to a page which is translated to several
+languages (more or less ;-). Have a look at it and don't forget to view the page in the other
+languages!
+
+table{border:1px solid black}.
+|_.Command|_.Output|
+|<notextile>\{lang: }</notextile>|<notextile>{lang: }</notextile>|
+|\{lang: {separator: Hallo}}|{lang: {separator: Hallo}}|
+|\{lang: {showSingleLang: false}}|{lang: {showSingleLang: false}}|
+

data/doc/src/documentation/tags/menu.de.page

@@ -0,0 +1,11 @@
+---
+title: Menütag
+---
+<div class="section">
+
+h2. Information
+
+Auf der linken Seite sehen sie jetzt die deutschen Menüeinträge (now you can see the german menu
+entries on the left).
+
+ </div>

data/doc/src/documentation/tags/menu.page

@@ -0,0 +1,30 @@
+---
+title: Menu
+inMenu: true
+---
+h2. Information
+
+<notextile>{describe: MenuTag}</notextile>
+
+h2. Description
+
+The menu tag is used to generate a menu for the website. You can see such a menu on the left of this
+page. To get a list of all supported parameters for the menu tag, have a look at its API
+documentation.
+
+This page is available in <a href="{relocatable: menu.html/menu.de.html}">German</a>. Try and go to
+the german version of this page. You will see that the menu items for which translations exist
+change their names.
+
+The menu to the left is generated with the default settings:
+
+* level = 1
+* subtreeLevel = 3
+* showCurrentSubtreeOnly = true
+
+h2. Examples
+
+Below are some other menus generated from the same source but with different settings:
+
+table{border: 1px solid black}.
+|^. \{menu: {subtreeLevel: 1}}{menu: {subtreeLevel: 1}}|^. \{menu: {showCurrentSubtreeOnly: false}} {menu: {showCurrentSubtreeOnly: false}}|

data/doc/src/documentation/tags/meta.page

@@ -0,0 +1,20 @@
+---
+title: Meta
+inMenu: true
+dummyForMeta: This is content specified in the meta information section.
+---
+h2. Information
+
+<notextile>{describe: MetaTag}</notextile>
+
+h2. Description
+
+The meta tag is used to copy meta information verbatim to the output file. For example, if you
+define a meta information with the key <code>revision</code>, you could put the tag
+<code>\{revision: }</code> into the content part of the file and the value gets substituted
+automatically.
+
+h2. Examples
+
+There is a meta information called 'dummyForMeta' defined for this page, so when this tag
+is used @\{dummyForMeta:}@, you get this '@{dummyForMeta:}@'.

data/doc/src/documentation/tags/multilang.de.page

@@ -0,0 +1,4 @@
+---
+title: Seite in verschiedenen Sprachen
+---
+Das ist jetzt die deutsche Version der Seite.

data/doc/src/documentation/tags/multilang.fr.page

@@ -0,0 +1,4 @@
+---
+title: Francais
+---
+Parle vouz francais?

data/doc/src/documentation/tags/multilang.page

@@ -0,0 +1,4 @@
+---
+title: Multi language page
+---
+This is the english version of this page.

data/doc/src/documentation/tags/navbar.page

@@ -0,0 +1,19 @@
+---
+title: Navigation Bar
+inMenu: true
+---
+h2. Information
+
+<notextile>{describe: NavbarTag}</notextile>
+
+h2. Description
+
+The navigation bar tag is used to display the hierarchy for the current page. You can see it in
+action in the lower left corner of the header.
+
+h2. Examples
+
+table{border:1px solid black}.
+|_.Command|_.Output|
+|<notextile>\{navbar: {separator: " HALLO "}}</notextile>|<notextile>{navbar: {separator: " HALLO "}}</notextile>|
+|\{navbar:}|{navbar:}|

data/doc/src/documentation/tags/relocatable.page

@@ -0,0 +1,16 @@
+---
+title: Relocatable
+inMenu: true
+---
+h2. Information
+
+<notextile>{describe: RelocatableTag}</notextile>
+
+h2. Description
+
+The relocatable tag is used to change the path of the supplied file and is most often used in
+template files. A relocatable tag looks like this: @\{relocatable: default.css}@. If this
+was put into a template and the template was used by a file in a subdirectory, then the
+@relocatable@ tag would put @../default.css@ into the output file.
+
+This ensures that the relative path to the referenced file is always correct.

data/doc/src/documentation/tags/wikilink.page

@@ -0,0 +1,18 @@
+---
+title: WikiLink
+inMenu: true
+---
+h2. Information
+
+<notextile>{describe: WikiLinkTag}</notextile>
+
+h2. Description
+
+This tag can be used to add a link to a wiki page. It is used on this website to automatically
+provide a "Feedback" link for each page.
+
+table{border:1px solid black}.
+|_.Command|_.Output|
+|\{wikilink: }|{wikilink: }|
+|\{wikilink: {relURL: hallo}}|{wikilink: {relURL: hallo}}|
+|\{wikilink: {relURL: hallo, title: MoinMoin}}|{wikilink: {relURL: hallo, title: MoinMoin}}|

data/doc/src/download.page

@@ -0,0 +1,42 @@
+---
+title: Download & Installation
+inMenu: true
+---
+h2. 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. Dependencies
+
+* "RedCloth":http://redcloth.rubyforge.org version 2.0.10 or higher if you want Textile support
+* "BlueCloth":http://www.deveiate.org version 1.0.0 or higher if you want Markdown support
+
+h2. Installation
+
+There are many ways to install webgen. Choose the one you like best:
+
+* Via RPA
+ <pre>
+  $ rpa install webgen
+ </pre>
+
+* Via RubyGems
+ <pre>
+  $ gem install webgen
+ </pre>
+
+* The do-it-yourself way
+ <pre>
+  $ ruby setup.rb config
+  $ ruby setup.rb setup
+  $ ruby setup.rb install
+ </pre>
+
+* The simplified do-it-yourself way
+ <pre>
+  $ rake install
+ </pre>

data/doc/src/features.page

@@ -0,0 +1,14 @@
+---
+title: Features
+inMenu: true
+---
+h2. Feature list
+
+* Easily extendable through plugins
+* Uses templates for separating layout from content
+* Supports several different page description languages (YAML, XML, plain HTML), new ones are easy to add
+* Uses 'tags' to add generated content to the web pages
+* Standard distribution provides often used tags
+* Supports 'virtual files' via meta information backing files
+* Easy to configure if one needs to
+* Relatively fast: process ~1000 files in ~25 seconds on an {execute: uname -p}

data/doc/src/index.page

@@ -0,0 +1,48 @@
+---
+title: Home
+inMenu: true
+directoryName: Webgen
+---
+h2. Welcome
+
+... to the homepage of _*webgen*_, a template based web page generator.
+
+This whole site was generated with webgen and provides an online demonstration of its features.
+Choose from the menu what you want to see from or know about webgen!
+
+h2. News
+
+*Webgen 0.3.0 was released!!!*
+
+Major changes:
+
+* Textile, Markdown, RDOC and HTML as content format supported!!!
+* New tags: <a href="{relocatable: documentation/tags/wikilink.html}">wikilink</a>
+* Improved plugin system
+* On-the-fly creation of new tags
+* Fixed bugs
+* Improved online documentation: pages on file handlers and tags now show parameters and other
+  additional info
+* Added comprehensive test suite --> TODO
+* and more...
+
+h2. Description
+
+Webgen can be used to generate web pages from page description and template files. You create one
+template file in which you define the layout of your page and where the content should go. After
+that you can create page description files in which you only define the content.
+
+When webgen is run it combines the template with each of the page description files and generates
+the HTML output files. During this process special tags are substituted so that, for example, a menu
+is generated.
+
+h2. Author
+
+* *Thomas Leitner*
+* Web: "http://webgen.rubyforge.org":http://webgen.rubyforge.org
+* e-Mail: "t_leitner@gmx.at":mailto:t_leitner@gmx.at
+* GPG Key-Id: 0xD942E7F6
+
+h2. And so ...
+
+... have fun!

data/doc/src/meta.info

@@ -0,0 +1,22 @@
+index.html:
+  en:
+    menuOrder: 1
+
+download.html:
+  en:
+    menuOrder: 3
+
+features.html:
+  en:
+    menuOrder: 5
+
+api.html:
+  en:
+    dest: rdoc/index.html
+    title: API Reference
+    menuOrder: 7
+    inMenu: true
+
+documentation/index.html:
+  en:
+    menuOrder: 9