Thoughts on the new wikistate variable

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

diff --git a/doc/usage.mdwn b/doc/usage.mdwn
index 3075cb1075f0b2c6e18a702d048e7ba72b6dd2c2..b6af75ac81dcd104a3d7be95578de49bf9ef0045 100644 (file)
--- a/doc/usage.mdwn
+++ b/doc/usage.mdwn
@@ -11,7 +11,7 @@ ikiwiki --setup configfile
 # DESCRIPTION
 
 `ikiwiki` is a wiki compiler. It builds static HTML pages for a wiki, from
 # DESCRIPTION
 
 `ikiwiki` is a wiki compiler. It builds static HTML pages for a wiki, from

-`source` in the [[Markdown]] language (or others), and writes it out to
+`source` in the [[ikiwiki/Markdown]] language (or others), and writes it out to

 `destination`.
 
 Note that most options can be shortened to single letters, and boolean
 `destination`.
 
 Note that most options can be shortened to single letters, and boolean


@@ -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 configfile
+
+  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.
+  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.
+

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


@@ -114,6 +116,11 @@ configuration options of their own.
   build time. If the templatedir is changed, missing templates will still
   be searched for in the default location as a fallback.
 
   build time. If the templatedir is changed, missing templates will still
   be searched for in the default location as a fallback.
 

+  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
 
   Specify the directory that is used to underlay the source directory.
 * --underlaydir
 
   Specify the directory that is used to underlay the source directory.


@@ -125,10 +132,13 @@ configuration options of their own.
 
   Specify a mode to chmod the wrapper to after creating it.
 
 
   Specify a mode to chmod the wrapper to after creating it.
 

-* --notify, --no-notify
+* --wrappergroup group

 
 

-  Enable email notification of commits. This should be used when running
-  ikiwiki as a [[post-commit]] hook.
+  Specify what unix group the wrapper should be owned by. This can be
+  useful if the wrapper needs to be owned by a group other than the default.
+  For example, if a project has a repository with multiple committers with
+  access controlled by a group, it makes sense for the ikiwiki wrappers
+  to run setgid to that group.

 
 * --rcs=svn|git|.., --no-rcs
 
 
 * --rcs=svn|git|.., --no-rcs
 


@@ -138,15 +148,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
 


@@ -157,13 +165,25 @@ configuration options of their own.
 
 * --rss, --norss
 
 
 * --rss, --norss
 

-  If rss is set, ikiwiki will generate RSS feeds for pages that inline
-  a [[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 [[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
 


@@ -207,10 +227,13 @@ configuration options of their own.
 
 * --adminuser name
 
 
 * --adminuser name
 

-  Specifies a username of a user who has the powers of a wiki admin.
-  Currently allows locking of any page; other powers may be added later.
+  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|banned_users]] users; other powers may be added later.

   May be specified multiple times for multiple admins.
 
   May be specified multiple times for multiple admins.
 

+  For an openid user specify the full URL of the login, including "http://".
+

 * --plugin name
 
   Enables the use of the specified [[plugin|plugins]] in the wiki. 
 * --plugin name
 
   Enables the use of the specified [[plugin|plugins]] in the wiki. 


@@ -266,6 +289,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 --no-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,


@@ -292,12 +320,20 @@ configuration options of their own.
   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.
 

+# ENVIRONMENT
+
+* CC
+
+  This controls what C compiler is used to build wrappers. Default is 'cc'.
+

 # SEE ALSO
 
 * [[ikiwiki-mass-rebuild]](8)
 # SEE ALSO
 
 * [[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