]> git.vanrenterghem.biz Git - git.ikiwiki.info.git/blobdiff - doc/usage.mdwn
move security to discussion
[git.ikiwiki.info.git] / doc / usage.mdwn
index 473d1c9b10e37f467c7f66403948abeef0de9ce6..e2fe85ff60d8b5a91901ef9ec235e5b8e09d4b69 100644 (file)
@@ -6,7 +6,7 @@ ikiwiki - a wiki compiler
 
 ikiwiki [options] source destination
 
-ikiwiki --setup configfile
+ikiwiki --setup setupfile
 
 # DESCRIPTION
 
@@ -30,6 +30,26 @@ These options control the mode that ikiwiki operates in.
 
   Force a rebuild of all pages.
 
+* --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
+  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.
+
+* --dumpsetup setupfile
+
+  Causes ikiwiki to write to the specified setup file, dumping out
+  its current configuration.
+
+* --wrappers
+
+  If used with --setup --refresh, this makes it also update any configured
+  wrappers.
+
 * --cgi
 
   Enable [[CGI]] mode. In cgi mode ikiwiki runs as a cgi script, and
@@ -50,28 +70,6 @@ These options control the mode that ikiwiki operates in.
 
   Note that the generated wrapper will ignore all command line parameters.
 
-* --setup configfile
-
-  In setup mode, ikiwiki reads the config file, which is really a perl
-  program that can call ikiwiki internal functions.
-
-  [[ikiwiki.setup]] is an example of such a config file.
-
-  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.
-  If you only want to build any changed pages, you can use --refresh with
-  --setup.
-
-* --dumpsetup configfile
-
-  Causes ikiwiki to write to the specified config file, dumping out
-  its current configuration.
-
-* --wrappers
-
-  If used with --setup --refresh, this makes it also update any configured
-  wrappers.
-
 * --aggregate
 
   If the [[plugins/aggregate]] plugin is enabled, this makes ikiwiki poll
@@ -105,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
-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".
 
-* --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
@@ -123,7 +122,7 @@ configuration options of their own.
   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
@@ -168,24 +167,24 @@ configuration options of their own.
 * --rss, --norss
 
   If rss is set, ikiwiki will default to generating RSS feeds for pages
-  that inline a [[ikiwiki/blog]].
+  that inline a [[blog]].
 
 * --allowrss
 
   If allowrss is set, and rss is not set, ikiwiki will not default to
-  generating RSS feeds, but setting `rss=yes` in the blog can override
-  this default and generate a feed.
+  generating RSS feeds, but setting `rss=yes` in the inline directive can
+  override this default and generate a feed.
 
 * --atom, --noatom
 
   If atom is set, ikiwiki will default to generating Atom feeds for pages
-  that inline a [[ikiwiki/blog]].
+  that inline a [[blog]].
 
 * --allowatom
 
   If allowatom is set, and rss is not set, ikiwiki will not default to
-  generating Atom feeds, but setting `atom=yes` in the blog can override
-  this default and generate a feed.
+  generating Atom feeds, but setting `atom=yes` in the inline directive can
+  override this default and generate a feed.
 
 * --pingurl URL
 
@@ -294,7 +293,7 @@ configuration options of their own.
 * --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
 
@@ -318,10 +317,28 @@ configuration options of their own.
 * --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.
 
+# 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
@@ -338,4 +355,4 @@ configuration options of their own.
 
 Joey Hess <joey@ikiwiki.info>
 
-Warning: this page is automatically made into ikiwiki's man page via [mdwn2man](http://ikiwiki.info/cgi-bin/viewvc.cgi/trunk/mdwn2man?root=ikiwiki&view=markup).  Edit with care
+Warning: this page is automatically made into ikiwiki's man page via [mdwn2man](http://git.ikiwiki.info/?p=ikiwiki;a=blob;f=mdwn2man;hb=HEAD).  Edit with care