move security to discussion

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

diff --git a/doc/usage.mdwn b/doc/usage.mdwn
index 136e969c2752d145b29491d80668141d858a566a..e2fe85ff60d8b5a91901ef9ec235e5b8e09d4b69 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,11 +30,30 @@ 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

-  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
 
   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 +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.
-
-* --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


@@ -101,20 +103,26 @@ 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
   build time. If the templatedir is changed, missing templates will still
   be searched for in the default location as a fallback.
 
 
   Specify the directory that the page [[templates|wikitemplates]] 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.
 

-* --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
 
   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


@@ -133,11 +141,6 @@ configuration options of their own.
   access controlled by a group, it makes sense for the ikiwiki wrappers
   to run setgid to that group.
 
   access controlled by a group, it makes sense for the ikiwiki wrappers
   to run setgid to that group.
 

-* --notify, --no-notify
-
-  Enable email notification of commits. This should be used when running
-  ikiwiki as a [[post-commit]] hook.
-

 * --rcs=svn|git|.., --no-rcs
 
   Enable or disable use of a [[revision_control_system|rcs]].
 * --rcs=svn|git|.., --no-rcs
 
   Enable or disable use of a [[revision_control_system|rcs]].


@@ -146,15 +149,13 @@ 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
   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
 
 
   No revision control is enabled by default.
 
 * --svnrepo /svn/wiki
 

-  Specify the location of the svn repository for the wiki. This is required
-  for using --notify with [[Subversion|rcs/svn]].
+  Specify the location of the svn repository for the wiki.

 
 * --svnpath trunk
 
 
 * --svnpath trunk
 


@@ -165,13 +166,25 @@ configuration options of their own.
 
 * --rss, --norss
 
 
 * --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
 
 
 * --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
 
 
 * --pingurl URL
 


@@ -217,8 +230,8 @@ configuration options of their own.
 
   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,
 
   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://".
 
 
   For an openid user specify the full URL of the login, including "http://".
 


@@ -277,6 +290,11 @@ configuration options of their own.
 
   Toggle creating output files named page/index.html (default) instead of page.html.
 
 
   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,
 * --w3mmode, --no-w3mmode
 
   Enable [[w3mmode]], which allows w3m to use ikiwiki as a local CGI script,


@@ -299,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


@@ -313,9 +349,10 @@ configuration options of their own.
 
 * [[ikiwiki-mass-rebuild]](8)
 * [[ikiwiki-update-wikilist]](1)
 
 * [[ikiwiki-mass-rebuild]](8)
 * [[ikiwiki-update-wikilist]](1)

+* [[ikiwiki-transition]](1)

 
 # AUTHOR
 
 Joey Hess <joey@ikiwiki.info>
 
 
 # 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