respond

[ikiwiki.git] / doc / usage.mdwn

diff --git a/doc/usage.mdwn b/doc/usage.mdwn
index b6af75ac81dcd104a3d7be95578de49bf9ef0045..0c618de5c1eac91ac31b11407c90cc4585e0cab6 100644 (file)
--- a/doc/usage.mdwn
+++ b/doc/usage.mdwn
@@ -6,7 +6,7 @@ ikiwiki - a wiki compiler
 
 ikiwiki [options] source destination
 
 
 ikiwiki [options] source destination
 

-ikiwiki --setup configfile
+ikiwiki --setup setupfile

 
 # DESCRIPTION
 
 
 # DESCRIPTION
 


@@ -30,19 +30,19 @@ These options control the mode that ikiwiki operates in.
 
   Force a rebuild of all pages.
 
 
   Force a rebuild of all pages.
 

-* --setup configfile
+* --setup setupfile

 
   In setup mode, ikiwiki reads the config file, which is really a perl
   program that can call ikiwiki internal functions.
 
   The default action when --setup is specified is to automatically generate
 
   In setup mode, ikiwiki reads the config file, which is really a perl
   program that can call ikiwiki internal functions.
 
   The default action when --setup is specified is to automatically generate

-  wrappers for a wiki based on data in a config file, and rebuild the wiki.
+  wrappers for a wiki based on data in a setup file, and rebuild the wiki.

   If you only want to build any changed pages, you can use --refresh with
   --setup.
 
   If you only want to build any changed pages, you can use --refresh with
   --setup.
 

-* --dumpsetup configfile
+* --dumpsetup setupfile

 
 

-  Causes ikiwiki to write to the specified config file, dumping out
+  Causes ikiwiki to write to the specified setup file, dumping out

   its current configuration.
 
 * --wrappers
   its current configuration.
 
 * --wrappers


@@ -103,13 +103,14 @@ These options control the mode that ikiwiki operates in.
 # CONFIG OPTIONS
 
 These options configure the wiki. Note that [[plugins]] can add additional
 # CONFIG OPTIONS
 
 These options configure the wiki. Note that [[plugins]] can add additional

-configuration options of their own.
+configuration options of their own. All of these options and more besides can
+also be configured using a setup file.

 
 

-* --wikiname
+* --wikiname name

 
   The name of the wiki, default is "wiki".
 
 
   The name of the wiki, default is "wiki".
 

-* --templatedir
+* --templatedir dir

 
   Specify the directory that the page [[templates|wikitemplates]] are stored in.
   Default is `/usr/share/ikiwiki/templates`, or another location as configured at
 
   Specify the directory that the page [[templates|wikitemplates]] are stored in.
   Default is `/usr/share/ikiwiki/templates`, or another location as configured at


@@ -121,7 +122,7 @@ configuration options of their own.
   ikiwiki. Old versions of templates do not always work with new ikiwiki
   versions.
 
   ikiwiki. Old versions of templates do not always work with new ikiwiki
   versions.
 

-* --underlaydir
+* --underlaydir dir

 
   Specify the directory that is used to underlay the source directory.
   Source files will be taken from here unless overridden by a file in the
 
   Specify the directory that is used to underlay the source directory.
   Source files will be taken from here unless overridden by a file in the


@@ -292,7 +293,7 @@ configuration options of their own.
 * --prefix-directives, --no-prefix-directives
 
   Toggle new '!'-prefixed syntax for preprocessor directives.  ikiwiki currently
 * --prefix-directives, --no-prefix-directives
 
   Toggle new '!'-prefixed syntax for preprocessor directives.  ikiwiki currently

-  defaults to --no-prefix-directives.
+  defaults to --prefix-directives.

 
 * --w3mmode, --no-w3mmode
 
 
 * --w3mmode, --no-w3mmode
 


@@ -307,19 +308,37 @@ configuration options of their own.
 
 * --getctime
 
 
 * --getctime
 

-  Pull last changed time for each new page out of the revision control
+  Pull creation time for each new page out of the revision control

   system. This rarely used option provides a way to get the real creation
   times of items in weblogs, such as when building a wiki from a new
   system. This rarely used option provides a way to get the real creation
   times of items in weblogs, such as when building a wiki from a new

-  Subversion checkout. It is unoptimised and quite slow. It is best used
+  VCS checkout. It is unoptimised and quite slow. It is best used

   with --rebuild, to force ikiwiki to get the ctime for all pages.
 
 * --set var=value
   
   This allows setting an arbitrary configuration variable, the same as if it
   with --rebuild, to force ikiwiki to get the ctime for all pages.
 
 * --set var=value
   
   This allows setting an arbitrary configuration variable, the same as if it

-  were set via a configuration file. Since most options can be configured
+  were set via a setup file. Since most options can be configured

   using command-line switches, you will rarely need to use this, but it can be
   useful for the odd option that lacks a command-line switch.
 
   using command-line switches, you will rarely need to use this, but it can be
   useful for the odd option that lacks a command-line switch.
 

+# EXAMPLES
+
+* ikiwiki --setup my.setup
+
+  Completly (re)build the wiki using the specified setup file.
+
+* ikiwiki --setup my.setup --refresh
+
+  Refresh the wiki, using settings from my.setup, and avoid
+  rebuilding any pages that have not changed. This is faster.
+
+* ikiwiki --setup my.setup --refresh --wrappers
+
+  Refresh the wiki, including regnerating all wrapper programs,
+  but do not rebuild all pages. Useful if you have changed something
+  in the setup file that does not need a full wiki rebuild to update
+  all pages, but that you want to immediatly take effect.
+

 # ENVIRONMENT
 
 * CC
 # ENVIRONMENT
 
 * CC