]> git.vanrenterghem.biz Git - git.ikiwiki.info.git/blobdiff - doc/usage.mdwn
(no commit message)
[git.ikiwiki.info.git] / doc / usage.mdwn
index 354e266f1d4c31a3c34c45ea7a8a13f9e3ceabbe..2325b6502dc11762bc6932bde2542b05291df18e 100644 (file)
@@ -6,7 +6,7 @@ ikiwiki - a wiki compiler
 
 ikiwiki [options] source destination
 
-ikiwiki --setup configfile
+ikiwiki --setup setupfile
 
 # DESCRIPTION
 
@@ -30,11 +30,46 @@ These options control the mode that ikiwiki operates in.
 
   Force a rebuild of all pages.
 
+* --setup setupfile
+
+  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.
+
+* --changesetup setupfile
+
+  Reads the setup file, adds any configuration changes specified by other
+  options, and writes the new configuration back to the setup file. Also
+  updates any configured wrappers. In this mode, the wiki is not fully
+  rebuilt, unless you also add --rebuild.
+
+  Example, to enable some plugins:
+
+       ikiwiki --changesetup ~/ikiwiki.setup --plugin goodstuff --plugin calendar
+
+* --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.
+
+* --clean
+
+  This makes ikiwiki clean up by removing any files it denerated in the 
+  `destination` directory, as well as any configured wrappers, and the
+  `.ikiwiki` state directory. This is mostly useful if you're running
+  ikiwiki in a Makefile to build documentation and want a corresponding
+  `clean` target.
+
 * --cgi
 
   Enable [[CGI]] mode. In cgi mode ikiwiki runs as a cgi script, and
-  supports editing pages, signing in, registration, and displaying
-  [[RecentChanges]].
+  supports editing pages, signing in, and registration.
 
   To use ikiwiki as a [[CGI]] program you need to use --wrapper or --setup
   to generate a wrapper. The wrapper will generally need to run suid 6755 to
@@ -51,23 +86,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.
-
-* --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
@@ -101,20 +119,27 @@ 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.
+  Specify the directory that [[templates|templates]] are stored in.
   Default is `/usr/share/ikiwiki/templates`, or another location as configured at
   build time. If the templatedir is changed, missing templates will still
-  be searched for in the default location as a fallback.
+  be searched for in the default location as a fallback. Templates can also be
+  placed in the "templates/" subdirectory of the srcdir.
 
-* --underlaydir
+  Note that if you choose to copy and modify ikiwiki's templates, you will need
+  to be careful to keep them up to date when upgrading to new versions of
+  ikiwiki. Old versions of templates do not always work with new ikiwiki
+  versions.
+
+* --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
@@ -141,11 +166,14 @@ configuration options of their own.
   whatever the revision control system you select uses.
 
   In [[CGI]] mode, with a revision control system enabled, pages edited via
-  the web will be committed. Also, the [[RecentChanges]] link will be placed
-  on pages.
+  the web will be committed.
 
   No revision control is enabled by default.
 
+* --svnrepo /svn/wiki
+
+  Specify the location of the svn repository for the wiki.
+
 * --svnpath trunk
 
   Specify the path inside your svn repository where the wiki is located.
@@ -155,13 +183,25 @@ configuration options of their own.
 
 * --rss, --norss
 
-  If rss is set, ikiwiki will generate RSS feeds for pages that inline
-  a [[ikiwiki/blog]].
+  If rss is set, ikiwiki will default to generating RSS feeds for pages
+  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 inline directive can
+  override this default and generate a feed.
 
 * --atom, --noatom
 
-  If atom is set, ikiwiki will generate Atom feeds for pages that inline
-  a [[ikiwiki/blog]].
+  If atom is set, ikiwiki will default to generating Atom feeds for pages
+  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 inline directive can
+  override this default and generate a feed.
 
 * --pingurl URL
 
@@ -203,12 +243,18 @@ configuration options of their own.
   Specifies a rexexp of source files to exclude from processing.
   May be specified multiple times to add to exclude list.
 
+* --include regexp
+
+  Specifies a rexexp of source files, that would normally be excluded,
+  but that you wish to include in processing.
+  May be specified multiple times to add to include list.
+
 * --adminuser name
 
   Specifies a username of a user (or, if openid is enabled, an openid) 
   who has the powers of a wiki admin. Currently allows locking of any page,
-  and banning of users; other powers may be added later. May be specified
-  multiple times for multiple admins.
+  and [[banning|banned_users]] users; other powers may be added later.
+  May be specified multiple times for multiple admins.
 
   For an openid user specify the full URL of the login, including "http://".
 
@@ -226,8 +272,8 @@ configuration options of their own.
 
   Makes ikiwiki look in the specified directory first, before the regular
   locations when loading library files and plugins. For example, if you set
-  libdir to "/home/you/.ikiwiki/", you can install a Foo.pm plugin as
-  "/home/you/.ikiwiki/IkiWiki/Plugin/Foo.pm".
+  libdir to "/home/you/.ikiwiki/", you can install a foo.pm plugin as
+  "/home/you/.ikiwiki/IkiWiki/Plugin/foo.pm".
 
 * --discussion, --no-discussion
 
@@ -267,6 +313,11 @@ configuration options of their own.
 
   Toggle creating output files named page/index.html (default) instead of page.html.
 
+* --prefix-directives, --no-prefix-directives
+
+  Toggle new '!'-prefixed syntax for preprocessor directives.  ikiwiki currently
+  defaults to --prefix-directives.
+
 * --w3mmode, --no-w3mmode
 
   Enable [[w3mmode]], which allows w3m to use ikiwiki as a local CGI script,
@@ -278,20 +329,40 @@ configuration options of their own.
   intercepted. If you enable this option then you must run at least the 
   CGI portion of ikiwiki over SSL.
 
-* --getctime
+* --gettime, --no-gettime
 
-  Pull last changed 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
-  Subversion checkout. It is unoptimised and quite slow. It is best used
-  with --rebuild, to force ikiwiki to get the ctime for all pages.
+  Extract creation and modification times for each new page from the
+  the revision control's log. This is done automatically when building a
+  wiki for the first time, so you normally do not need to use this option.
 
 * --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
-  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.
+  were set via a setup file. Since most commonly used options can be
+  configured using command-line switches, you will rarely need to use this.
+
+* --set-yaml var=value
+
+  This is like --set, but it allows setting configuration variables that
+  use complex data structures, by passing in a YAML document.
+
+# EXAMPLES
+
+* ikiwiki --setup my.setup
+
+  Completely (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
 
@@ -299,13 +370,18 @@ configuration options of their own.
 
   This controls what C compiler is used to build wrappers. Default is 'cc'.
 
+* CFLAGS
+
+  This can be used to pass options to the C compiler when building wrappers.
+
 # SEE ALSO
 
 * [[ikiwiki-mass-rebuild]](8)
 * [[ikiwiki-update-wikilist]](1)
+* [[ikiwiki-transition]](1)
 
 # AUTHOR
 
 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