manual.page in gettalong-webgen-0.5.8.20090507

- old
+ new

@@ -10,19 +10,20 @@
 webgen website. This means that first the information on how to use the webgen CLI comes, then how a
 webgen website is structured and how content can be added and so on.
 
 
 
-# The `webgen` command
+# The `webgen` command {#cli}
 
 The executable for webgen is called... webgen ;-) It uses a command style syntax (like Subversion's
 `svn` or Rubygem's `gem` commands) through the [cmdparse] library. To get an overview of the
 possible commands run `webgen help`.
 
 The main command is the `render` command which does the actual website generation. This command uses
 either the environment variable `WEBGEN_WEBSITE` (if it is set and non-empty) or the current working
-directory as website directory if none was specified via the gloabl `-d` option.
+directory as website directory if none was specified via the gloabl `-d` option. All other commands
+that need a valid webgen website directory specified work in the same way.
 
 You can invoke a command by specifying its name after the executable name. Also counting the
 executable `webgen` as a command, the options for a command are specified directly after the command
 name and before the next command or any arguments. For example, all the following command lines are
 valid:
@@ -33,15 +34,34 @@
     $ webgen -v create -t project new_site
     $ webgen help create
 
 Following is a short overview of the available commands:
 
-*   `create [-t TEMPLATE] [-s STYLE] SITE_DIR`
+*   `apply [-f] (BUNDLE_NAME|BUNDLE_URL)`
 
-    Creates a basic webgen website in `SITE_DIR` using the optional template and styles. All
-    available templates and styles are listed in the help output for the command.
+    The argument may either be a valid bundle name or an URL to a bundle archive (a (gzipped) tar
+    archive). The command applies the bundle to the given webgen website. The files that will be
+    written to website directory are shown and the user is asked to confirm that the shown files
+    should indeed be written (and sometimes overwritten). If the `-f` option is used, the files are
+    always written.
 
+    You can get the full list of available bundle names by running `webgen help apply`!
+
+*   `create [-b BUNDLE] SITE_DIR`
+
+    Creates a basic webgen website in `SITE_DIR` using the optionally specified bundles. The option
+    `-b` can be used more than once to specify more than one bundle - the bundles are applied in the
+    order they are specified. As with the `apply` command, `BUNDLE` may either be a valid bundle
+    name or a bundle URL.
+
+    > If you don't specify the `-b` option, the default value is used which applies the `default`
+    > and the `style-andreas07` bundles. The former only creates a simple `src/index.page` sothat
+    > some output can be seen and the latter applies a nice layout.
+    {.information}
+
+    All available bundles are listed in the help output for the command.
+
 *   `help`
 
     Displays usage information. Can be used to show information about a command by using the command
     name as argument, eg. `webgen help create`.
 
@@ -72,15 +92,15 @@
 The root directory of webgen website is called the website directory. You can have the following
 files and directories under this directory:
 
 * `src`: The source directory in which all the source files for the website are. If this directory
   should not be called `src` or you want to include additional source directories, you need to
-  change the `sources` configuration option.
+  change the [`sources` configuration option]({relocatable: reference_configuration.html#sources}).
 
 * `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. The name of this directory can be changed by setting
-  the `output` configuration option.
+  the [`output` configuration option]({relocatable: reference_configuration.html#output}).
 
 * `ext`: The extension directory (optional). You can put self-written extensions into this directory
   so that they are used by webgen. See the [extension directory]({relocatable: '#website-ext'})
   section for more information.
 
@@ -222,13 +242,14 @@
 SourceHandler::Template as they are responsible for handling these page and template files!
 
 You can naturally use any other type of file. However, be aware that some files may not be processed
 by webgen when no source handler class for them exists. For example, there is currently no source
 handler class for `.svg` files, so those files would be ignored. If you just want to have files
-copied from a source to the output directory (like images or CSS files), the SourceHandler::Copy
-class is what you need! Look through the documentation of the [availabe source handler
-classes]({relocatable: extensions.html}) to get a feeling of what files are handled by webgen.
+copied from a source to the output directory (like images or CSS files), the
+[SourceHandler::Copy]({relocatable: sourcehandler/copy.html}) class is what you need! Look through
+the documentation of the [availabe source handler classes]({relocatable: extensions.html}) to get a
+feeling of what files are handled by webgen.
 
 
 ## Source Paths Naming Convention {#source-naming}
 
 webgen assumes that the paths provided by the sources follow a special naming convention sothat meta
@@ -287,31 +308,56 @@
 
 
 ## Canonical Name of a File ### {#source-cn}
 
 webgen provides the functionality to define the same content in more than one language, ie. to
-localize content. This is achieved with the _canonical name_ of a path.
+localize content. This is achieved with the _canonical name_ of a path, short CN.
 
 When multiple paths share the same canonical name, webgen assumes that they have the same content
-but in different languages. It is also possible to specify a _language independent_ path which is
-used as a fallback. Therefore when a path should be resolved using a canonical name and a given
-language, it is first tried to get the path in the requested language. If this is not possible
-(ie. no such localization exists), the unlocalized path is returned if it exists.
+but in different languages. It is also possible to specify a _language independent_ path (i.e. one
+without a language) which is used as a fallback. Therefore when a path should be resolved using a
+canonical name and a given language, it is first tried to get the path in the requested language. If
+this is not possible (ie. no such localization exists), the unlocalized path is returned if it
+exists.
 
+For example, assume that we have the following `src` directory:
+
+    /test.jpg
+    /images/my.jpg
+    /images/my.de.jpg
+    /index.page
+    /index.fr.page
+    /index.de.page
+
+Since the path `images/my.jpg` has no language part, it is assumed to be unlocalized. In contrast,
+`images/my.de.jpg` has the "same" picture but in a German version. So, when specifying
+`images/my.jpg` in `index.de.page`, the correct localized version will be returned, i.e.
+`images/my.de.jpg`. When specifying `images/my.jpg` in `index.page` or in `index.fr.page`, the
+unlocalized version will be returned since no localized version exists.
+
 > Directories and fragments are never localized, only files are!
 {.important}
 
-It is also possible to use the _localized canonical name_ of a path to resolve it. The localized
-canonical name is the same as the canonical name but with a language code inserted before the
-extension. If the localized canonical name is used to resolve a path, a possibly additionally
+It is also possible to use the _localized canonical name_ of a path (short: LCN) to resolve it. The
+localized canonical name is the same as the canonical name but with a language code inserted before
+the extension. If the localized canonical name is used to resolve a path, a possibly additionally
 specified language is ignored as it is assumed that the user really only wants the path in the
 specified language!
 
-This also means that all paths are not resolved using their real source or output names but using
-the (localized) canonical name! This is different from previous webgen versions!
+Continuing the above example, this means that `images/my.de.jpg` is always returned when one
+specifies `images/my.de.jpg` in any of the index page files, e.g. in `index.fr.page`.
 
+Both canonical and localized canonical names can be absolute (ACN and ALCN) which is done by using
+the full path starting with a slash. This is especially useful when you don't exactly know in which
+hierarchy level a certain canoncial name gets evaluated.
 
+Everything said above also means that all paths are not resolved using their real source or output
+names but using the (localized) canonical name! So when specifying paths for extensions, for example
+when using the [relocatable tag]({relocatable: tag/relocatable.html}), you always have to use the
+(absolute) (localized) canonical names. This is different from previous webgen versions!
+
+
 ## Output Path Name Construction ### {#source-output}
 
 There is currently only one method, called `standard`, for creating output path names which is
 described here. However, webgen allows developers to create other output path name creation
 methods. More information on this can be found in the [API documentation]({relocatable: api.html}).
@@ -415,18 +461,21 @@
 
 ## Handling of files in the source directory {#source-handling}
 
 Following is the list of rules how source files are handled by webgen:
 
-* All path names of all sources specified in the configuration option `sources` are fetched. Prior
-  listed sources have priority over later listed sources if both specify the same path.
+* All path names of all sources specified in the configuration option [`sources`]({relocatable:
+  reference_configuration.html#sources}) are fetched. Prior listed sources have priority over later
+  listed sources if both specify the same path.
 
-* Those paths which match a pattern of the configuration option `sourcehandler.ignore` are excluded.
+* Those paths which match a pattern of the configuration option
+  [`sourcehandler.ignore`]({relocatable: reference_configuration.html#sourcehandlerignore}) are excluded.
 
 * The source handler classes are invoked according to the invocation order specified in
-  `sourcehandler.invoke` and they use only those paths that match one of their path patterns
-  specified in `sourcehandler.patterns`.
+  [`sourcehandler.invoke`]({relocatable: reference_configuration.html#sourcehandlerinvoke}) and
+  they use only those paths that match one of their path patterns specified in
+  [`sourcehandler.patterns`]({relocatable: reference_configuration.html#sourcehandlerpatterns}).
 
 As you might have deduced from the processing list above, it is possible that one path is handled by
 multiple source handlers. This can be used, for example, to render an XML file as HTML and copy it
 verbatim.
 
@@ -436,16 +485,18 @@
 Each path can have meta information, i.e. information about the path itself, associated with it, for
 example the title of the path, if it should appear in a menu and so on. This meta information can be
 specified in several ways, including:
 
 * Source handlers can provide default meta information for their handled paths (set using the
-  configuration option `sourcehandler.default_meta_info`)
+  configuration option [`sourcehandler.default_meta_info`]({relocatable:
+  reference_configuration.html#sourcehandlerdefault_meta_info}).
 
 * Some file types allow meta information to be specified directly in the file, for example page
   files in [Webgen Page Format]({relocatable: webgen_page_format.html}).
 
 * Meta information can also be specified in special meta information backing files. These files are
-  handled by the source handler SourceHandler::Metainfo.
+  handled by the source handler [SourceHandler::Metainfo]({relocatable:
+  sourcehandler/metainfo.html}).
 
 There is clearly defined order in which meta information is applied to a node for a path:
 
 1. The path gets read by a source and some meta information is extracted from the path name.
 