webgen 0.3.4 → 0.3.5

data/doc/src/documentation/gettingstarted.page

@@ -73,7 +73,7 @@ Just add page files and other content to your website and let it grow!
 h2. Using Meta Information in Pages
 
 Meta information is specified at the beginning of a page file. Have a look at the
-<a href="{relocatable: plugins/filehandler/pagehandler.html}">documentation</a> to see how that is done
+<a href="{relocatable: plugins/filehandler/pagehandler.page}">documentation</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@

data/doc/src/documentation/index.page

@@ -48,9 +48,13 @@ If you want to get the configuration values you can run webgen like this
   $ webgen show config
 </pre>
 
+(This information is also provided on this website, have a look at the
+<a href="{relocatable: plugins}">plugins section</a>!)
+
 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
+parameter. Each parameter can be overridden in the configuration file by specifing the
+plugin name as top level key and each parameter and value as a key/value pair. A configuration file
 looks like this:
 
 <pre class="webgen-file">{includeFile: /../../../testsite/config.yaml}</pre>
+

data/doc/src/documentation/plugins/filehandler/backing.page

@@ -16,18 +16,31 @@ h2. File Format
 
 The files are written in YAML and have a very easy structure:
 <pre>
-filename1.en.html:
-  metainfo1: value1
-  metainfo2: value2
-filename1.de.html:
-  metainfo21: value21
+filename1.en.page:
+  title: File one
+  orderInfo: 45
+  additional_metainfo: my_used_value
+
+filename1.de.page:
+  title: German version of File one
+
+docu/external.html:
+  dest: http://www.my-homepage.com
+  title: My external homepage
+  inMenu: true
 </pre>
 
-Your can use relative and absoulte paths in the filenames. However, you cannot specify meta
-information for files which are in one of the parent directories of the backing file.
+As you can see, you use the name of a file as top level key and then you specify every meta
+information you want. You can use relative and absolute paths in the filenames. However, you cannot
+specify meta information for files which are in one of the parent directories of the backing file.
+
+If you want to set meta information for an existing page description file, you have to use the
+<a href="{relocatable: pagehandler.page#naming}">standardified name</a> of that page description
+file (e.g. @filename1.page@ or @filename1.de.page@).
 
 Using backing files you can add virtual files and directories. If the file specified in the entry
 does not exist, a node for that file will be created. This will also create the whole directory tree
-this virtual node is in. It allows you, for example, to add external items to the menu. You need
-to specify the +dest+ meta information which points to the actual location of the referenced page.
+this virtual node is in. It allows you, for example, to add external items to the menu. In this case
+you need to specify the +dest+ meta information which points to the actual location of the
+referenced page.
 

data/doc/src/documentation/plugins/filehandler/galleryhandler.page

@@ -76,4 +76,4 @@ DefaultGalleryLayouter and define the layout methods.
 
 h2. Examples
 
-You can view an example gallery <a href="{relocatable: /Design_Gallery_1.html}">here</a>!
+You can view an example gallery <a href="{relocatable: /Design_Gallery_1.page}">here</a>!

data/doc/src/documentation/plugins/filehandler/index.page

@@ -10,14 +10,19 @@ h2. Description
 File handlers are used to handle different types of input files. You can see the currently exisiting
 file handlers in the menu. Choose one to get a description for it!
 
-Each file handler specifies path patterns or extensions for the files he handles. During the
-processing of the website, the FileHandler instance calls the approriate file handler for each file
-and builds the internal representation of the source directory.
+Each file handler specifies path patterns for the files he handles (you can see which paths are
+handled by a file handler in its information section). During the processing of the website, the
+FileHandler instance calls the approriate file handler for each file and builds the internal
+representation of the source directory.
 
 h2. Path Patterns
 
 Path patterns are more like shell globs than regular expressions. One can use any path pattern that
-the @Dir.glob@ method understands. Here are some examples:
+the @Dir.glob@ method understands. If two path patterns would match the same path, the one with
+fewer asterisks and question marks is used because that one "seems" to be more specific.
+
+
+Here are some examples:
 
 table{border: 1px solid black}.
 |^. <notextile><code>*/*.html</code></notextile>|^. All files with the extension @html@ in the subdirectories of the root source directory|

data/doc/src/documentation/plugins/filehandler/pagehandler.page

@@ -8,7 +8,7 @@ h2. Information
 
 h2. Description
 
-Page description files are used to specify the actual content for the website. The contain the
+Page description files are used to specify the actual content for the website. They contain the
 content for the webpage and, optionally, meta information.
 
 h2(#structure). File format
@@ -35,7 +35,8 @@ This is the content of the file
 In this example, meta information is specified ("more info":#meta). Note the three dashes at the
 beginning of the file. This indicates that the following 'block' is used for meta information. If
 the three dashes at the beginning are omitted, then the parser won't know that the following block
-contains meta information and thinks it is content.
+contains meta information and thinks it is content. If not specified, the default name for the
+content block is @content@.
 
 If you want to include a line in your file which only has three dashes, you have to write this:
 <pre>
@@ -111,28 +112,50 @@ If meta information is specified in a page description file, the default values
 
 The following defaults are used:
 
-* Content format
+* Content format and name
 
   If there is only one content in a page description file, its formatting defaults to the parameter
-  value @defaultContentFormat@.
+  value @defaultContentFormat@ and it is named @content@.
 
 * Title, ordering and language
 
   These values are taken from the filename, so the filename of a page description file has to be
-  formatted like this: @[ordering.]title[.language].page@ (the values in square brackets are
+  formatted like this: @[ordering.]name[.language].page@ (the values in square brackets are
   optional). In detail:
   * ordering: The ordering is a number which is used for menu generation and the like, where it is
     necessary to order the items. If not specified, defaults to @0@.
-  * title: This is the title of the page. Hyphens and underscores are replaced with spaces and the
-    title must not contain any dots.
+  * name: This is used for the title of the page. Hyphens and underscores are replaced with spaces
+    and @name@ must not contain any dots. Also: if two page descriptions files have the same
+    @name@ part, they should define the same content for different languages as webgen consideres
+    them as "one" page file in two languages.
   * language: This is the language code for this file. It is the international two letter acronym
     and if it is not specified, it defaults to @en@.
 
   Consider the following examples:
-  * @name.page@ -> title: Name, language: en, ordering: 0
-  * @name.de.page@ -> title: Name, language: de, ordering: 0
-  * @01.name_of-file.de.page@ -> Title: Name of file, language: de, ordering: 01
+    * @name.page@ -> title: Name, language: en, ordering: 0
+    * @name.de.page@ -> title: Name, language: de, ordering: 0
+    * @01.name_of-file.de.page@ -> Title: Name of file, language: de, ordering: 01
 
+  Notice: The first two examples define content for two different languages (en and de) as they have
+  the same @name@ part.
+
+
+h2(#naming). Referencing page description files
+
+The output name of page description files can be specified using the parameter @outputNameStyle@. If
+you want to reference a page description file, you can use this output name (e.g. @name.de.html@).
+However, if you want to change the @outputNameStyle@ parameter later or set the parameter
+@defaultLangInFilename@, this link (@name.de.html@) will not work anymore.
+
+Therefore, each page description file can be referenced by specifing the name
+<code>[name_of_page_desc_file].[language].page</code> (e.g. @name.de.page@ instead of
+@name.de.html@). However, most of the time, you do not want to explicitly specify the @lang@ part in
+this standardified name because you want to reference the page description file and display it in
+the currently used language. Thus you can also use <code>[name_of_page_desc_file].page</code> (e.g.
+@name.page@). This will always reference the page description file in the correct language!
+
+I could have used the extension @html@ instead of @page@, but I think the latter is better because
+the output files need not have to have the extension @html@.
 
 h2(#meta). Meta Information
 

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

@@ -17,4 +17,12 @@ Writing your own plugins is not difficult, too! If you need a specific functiona
 plugin and put it under the site specific @plugin@ directory - then the plugin gets loaded with the
 others. It's so easy!
 
-For more information have a look at the <a href="{relocatable: /rdoc/index.html}">API documentation</a>!
+For more information have a look at the <a href="{relocatable: /rdoc/index.html}">API documentation</a>!
+
+h2. Parameters
+
+Each plugin can define parameters which can be used to configure the plugin. These parameters are
+listed in the "Information" section of each plugin page. Also note that plugins can use the
+parameters from their "super plugins" - this allows a group of plugins which have similar
+functionality (e.g. the menu style plugins) to share common configuration values. The names of the
+"super plugins" are enclosed in parentheses after the plugin name in the "Information" section.

data/doc/src/documentation/plugins/menustyles/horizontal-dropdown.page

@@ -0,0 +1,42 @@
+---
+title: Horizontal Dropdown
+inMenu: true
+---
+h2. Information
+
+<notextile>{describe: HorizontalDropdownMenuStyle}</notextile>
+
+h2. Description
+
+Builds a horizontal menu with CSS drop down menus. This menu should work fine in any browser
+supporting CSS and the @:hover@ selector (Mozilla based browsers like Firefox, Opera and Konqueror
+are fine, does NOT work in IE 6 on Windows XP).
+
+h2. Style Advice
+
+The menu works by only using CSS, not DHTML or anything else. Here is a list of CSS selectors and
+descriptions how these selectors can be used to style various parts of the menu. You have to pay
+attention to the last element in the selector (@ul@, @li@, or @a@). When you want to style menu
+items, you normally want to use @a@. You should also be aware of the use of the @>@ sign, there is a
+dramatic difference between writing @li a@ and @li > a@ (the former selecting ALL @a@ elements of
+the list item, i.e. all @a@ elements in submenus too; and the latter only selecting the direct
+descendant)!
+
+table{border: 1px solid black}.
+|<code>.webgen-menu-horiz-dd ul > li > a</code>|Style the top level menu items (the ones that are always shown)|
+|<code>.webgen-menu-horiz-dd ul ul</code>|Style the drop down menus|
+|<code>.webgen-menu-horiz-dd ul ul > li > a</code>|Style the drop down menu items|
+|<code>.webgen-menu-horiz-dd li:hover > a</code>|Style the hovered-over menu item|
+
+h2. Example
+
+Basic menu as it appears by default, nothing styled additionally with CSS:
+
+<notextile>{menu: {menuStyle: horizontal-dropdown}}</notextile>
+
+<br />
+The same menu with a little CSS magic:
+
+<notextile>{menu: {menuStyle: horizontal-dropdown, options: {divClass: horiz-dd-menu}}}</notextile>
+
+<br/>

data/doc/src/documentation/plugins/menustyles/horizontal.page

@@ -0,0 +1,21 @@
+---
+title: Horizontal
+inMenu: true
+---
+h2. Information
+
+<notextile>{describe: HorizontalMenuStyle}</notextile>
+
+h2. Description
+
+Builds a horizontal menu; each menu level gets its own menu bar.
+
+h2. Example
+
+Basic menu as it appears by default, nothing styled additionally with CSS:
+
+<notextile>{menu: {menuStyle: horizontal}}</notextile>
+
+The same menu with a little CSS magic:
+
+<notextile>{menu: {menuStyle: horizontal, options: {divClass: horiz-menu}}}</notextile>

data/doc/src/documentation/plugins/menustyles/index.page

@@ -0,0 +1,12 @@
+---
+directoryName: Menu Styles
+---
+h2. Information
+
+<notextile>{describe: DefaultMenuStyle}</notextile>
+
+h2. Description
+
+Menu Styles are used to build different types of menus. Some web sites use vertical menus on the
+left or right side, some horizontal menus at the top. It's up to you to chose the best suited
+menu style for your website!

data/doc/src/documentation/plugins/menustyles/partial.page

@@ -0,0 +1,27 @@
+---
+title: Partial
+inMenu: true
+---
+h2. Information
+
+<notextile>{describe: PartialMenuStyle}</notextile>
+
+h2. Description
+
+Builds a simple menu showing only the menu levels under the current page. This means that if you are
+in the third level of the hierarchy, the first two menu levels are not shown.
+
+h2. Style Advice
+
+The menu is constructed using HTML lists with @ul@ and @li@ tags. However, the menu looks better if
+no discs are shown for the menu items (using <code>list-style-type: none</code>).
+
+h2. Examples
+
+Basic menu as it appears by default, nothing styled additionally with CSS:
+
+<notextile>{menu: {menuStyle: partial}}</notextile>
+
+The same menu with a little CSS magic:
+
+<notextile>{menu: {menuStyle: partial, options: {divClass: partial-menu}}}</notextile>

data/doc/src/documentation/plugins/menustyles/vertical-dropdown.page

@@ -0,0 +1,23 @@
+---
+title: Vertical Dropdown
+inMenu: true
+---
+h2. Information
+
+<notextile>{describe: VerticalDropdownMenuStyle}</notextile>
+
+h2. Description
+
+Builds a vertical menu with CSS drop down menus. This one is similar to the horizontal dropdown menu
+and the information on the <a href="{relocatable: horizontal-dropdown.page}">Horizontal
+Dropdown</a> page also applies for this menu style.
+
+h2. Example
+
+Basic menu as it appears by default, nothing styled additionally with CSS:
+
+<notextile>{menu: {menuStyle: vertical-dropdown}}</notextile>
+
+The same menu with a little CSS magic:
+
+<notextile>{menu: {menuStyle: vertical-dropdown, options: {divClass: vert-dd-menu}}}</notextile>

data/doc/src/documentation/plugins/menustyles/vertical.page

@@ -0,0 +1,32 @@
+---
+title: Vertical
+inMenu: true
+---
+h2. Information
+
+<notextile>{describe: VerticalMenuStyle}</notextile>
+
+h2. Description
+
+Builds a simple vertical menu. This is the most basic of all menus. Use the various parameters to
+change how many menu levels should be shown.
+
+h2. Style Advice
+
+The menu is constructed using HTML lists with @ul@ and @li@ tags. However, the menu looks better if
+no discs are shown for the menu items (using <code>list-style-type: none</code>).
+
+h2. Examples
+
+Basic menu as it appears by default, nothing styled additionally with CSS:
+
+<notextile>{menu: {menuStyle: vertical}}</notextile>
+
+The same menu with a little CSS magic:
+
+<notextile>{menu: {menuStyle: vertical, options: {divClass: vert-menu}}}</notextile>
+
+Examples of the menu with other parameter settings
+
+table{border: 1px solid black}.
+|^. \{menu: {menuStyle: vertical, options: {subtreeLevel: 1}}}{menu: {menuStyle: vertical, options: {subtreeLevel: 1}}}|^. \{menu: {menuStyle: vertical, options: {subtreeLevel: 4, showCurrentSubtreeOnly: false}}} {menu: {menuStyle: vertical, options: {subtreeLevel: 4, showCurrentSubtreeOnly: false}}}|

data/doc/src/documentation/plugins/resourcemanager.page

@@ -0,0 +1,30 @@
+---
+title: Resource Manager
+inMenu: true
+---
+h2. Information
+
+<notextile>{describe: ResourceManager}</notextile>
+
+h2. Description
+
+The ResourceManager plugin is used to define and access various resources. A resource is identified
+via the resource name and is written to a certain output path (relative to the output directory).
+There are two different types of resources: file resources and memory resources.
+
+*   A *file* resources references a certain file which gets copied to its output path when webgen is
+    writing out all files. These files resources can refernce any kind of file (images, videos,
+    audio files, HTML files,...).
+
+*   A *memory* resource only exists during a run of webgen. Plugins can use such resources to provide
+    additional information, such as CSS formatting rules or Javascript.
+
+Resources are only written to the output path if they are referenced (i.e. their output path is
+included in a page file) at least once by the <a href="{relocatable: tags/resource.page}">resource
+tag</a>.
+
+h2. Predefined Resources
+
+webgen provides some predefined resources which can be used by any website created with it.
+
+<notextile>{predefinedResources:}</notextile>

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

@@ -19,9 +19,9 @@ Tags are defined by a special markup code. A tag has the following structure:
 
 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}">
+produce ranges from something simple to something complex. For example, the <a href="{relocatable: meta.page}">
 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}">
+into the correct place in the output file. And in contrast, the <a href="{relocatable: menu.page}">
 Menu Tag</a> plugin generates a whole menu tree.
 
 If you want to use the markup code used for tags, you need to escape the tag, like this:

data/doc/src/documentation/plugins/tags/langbar.page

@@ -4,18 +4,17 @@ inMenu: true
 ---
 h2. Information
 
-<notextile>{describe: LanguageBarTag}</notextile>
+<notextile>{describe: LangbarTag}</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.
+version of this page.
 
 h2. Examples
 
-Here is a <a href="{relocatable: multilang.html}">link</a> to a page which is translated to several
+Here is a <a href="{relocatable: multilang.page}">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!
 
@@ -24,4 +23,5 @@ table{border:1px solid black}.
 |<notextile>\{langbar: }</notextile>|<notextile>{langbar: }</notextile>|
 |\{langbar: {separator: Hallo}}|{langbar: {separator: Hallo}}|
 |\{langbar: {showSingleLang: false}}|{langbar: {showSingleLang: false}}|
+|\{langbar: {showOwnLang: false}}|{langbar: {showOwnLang: false}}|
 

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

@@ -9,22 +9,11 @@ h2. Information
 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.
+page.
 
-This page is available in <a href="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.
+This page is available in <a href="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}}|
+There exist serveral different predefined styles of menus (vertical, horizontal, ...). Have a look
+at the <a href="{relocatable: ../menustyles}">Menu Styles</a> section to see which menu styles are
+available.