X-Git-Url: http://git.vanrenterghem.biz/git.ikiwiki.info.git/blobdiff_plain/5afeca81546796673531d6e25fa1c84ab6da9733..2f6da5fd2b17541ff88072862d37c4d6f95a50b5:/doc/usage.mdwn diff --git a/doc/usage.mdwn b/doc/usage.mdwn index e25989a49..db1e36a10 100644 --- a/doc/usage.mdwn +++ b/doc/usage.mdwn @@ -6,7 +6,7 @@ ikiwiki - a wiki compiler ikiwiki [options] source destination -ikiwiki --setup configfile +ikiwiki --setup setupfile # DESCRIPTION @@ -30,19 +30,19 @@ These options control the mode that ikiwiki operates in. 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 - 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. -* --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 @@ -50,6 +50,14 @@ These options control the mode that ikiwiki operates in. 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 @@ -103,13 +111,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 @@ -121,7 +130,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 @@ -166,24 +175,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 @@ -225,6 +234,12 @@ 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) @@ -248,8 +263,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 @@ -292,7 +307,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 @@ -307,18 +322,40 @@ configuration options of their own. * --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 - 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 - 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 options 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 + + 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 @@ -326,6 +363,10 @@ 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) @@ -336,4 +377,4 @@ configuration options of their own. Joey Hess -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