remove patch, and more comments

[git.ikiwiki.info.git] / doc / usage.mdwn

diff --git a/doc/usage.mdwn b/doc/usage.mdwn
index 473d1c9b10e37f467c7f66403948abeef0de9ce6..e411b127a406c9fde7f69c31853bdd7e7050ebdf 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,6 +30,26 @@ These options control the mode that ikiwiki operates in.
 
   Force a rebuild of all pages.
 
 
   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
 * --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.
 
 
   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
 * --aggregate
 
   If the [[plugins/aggregate]] plugin is enabled, this makes ikiwiki poll


@@ -105,7 +103,8 @@ 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
 


@@ -168,24 +167,24 @@ configuration options of their own.
 * --rss, --norss
 
   If rss is set, ikiwiki will default to generating RSS feeds for pages
 * --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
 
 * --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
 
 * --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
 
 * --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
 
 
 * --pingurl URL
 


@@ -318,10 +317,28 @@ configuration options of their own.
 * --set var=value
   
   This allows setting an arbitrary configuration variable, the same as if it
 * --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


@@ -338,4 +355,4 @@ configuration options of their own.
 
 Joey Hess <joey@ikiwiki.info>
 
 
 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