diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/bugs/Command-line_arguments_should_override_settings_in_the_setup_file.mdwn | 2 | ||||
| -rw-r--r-- | doc/ikiwiki-update-wikilist.mdwn | 10 | ||||
| -rw-r--r-- | doc/ikiwiki.setup | 206 | ||||
| -rw-r--r-- | doc/plugins.mdwn | 2 | ||||
| -rw-r--r-- | doc/plugins/mirrorlist.mdwn | 3 | ||||
| -rw-r--r-- | doc/plugins/write.mdwn | 159 | ||||
| -rw-r--r-- | doc/rcs/details.mdwn | 3 | ||||
| -rw-r--r-- | doc/security.mdwn | 3 | ||||
| -rw-r--r-- | doc/setup.mdwn | 46 | ||||
| -rw-r--r-- | doc/tips/nearlyfreespeech.mdwn | 9 | ||||
| -rw-r--r-- | doc/todo/Make_example_setup_file_consistent.mdwn | 8 | ||||
| -rw-r--r-- | doc/todo/cas_authentication.mdwn | 2 | ||||
| -rw-r--r-- | doc/todo/color_plugin.mdwn | 3 | ||||
| -rw-r--r-- | doc/todo/conditional_underlay_files.mdwn | 2 | ||||
| -rw-r--r-- | doc/todo/online_configuration.mdwn | 59 | ||||
| -rw-r--r-- | doc/usage.mdwn | 7 | ||||
| -rw-r--r-- | doc/w3mmode/ikiwiki.setup | 20 |
17 files changed, 226 insertions, 318 deletions
diff --git a/doc/bugs/Command-line_arguments_should_override_settings_in_the_setup_file.mdwn b/doc/bugs/Command-line_arguments_should_override_settings_in_the_setup_file.mdwn index f1ccf5896..22b1c2cb5 100644 --- a/doc/bugs/Command-line_arguments_should_override_settings_in_the_setup_file.mdwn +++ b/doc/bugs/Command-line_arguments_should_override_settings_in_the_setup_file.mdwn @@ -1,5 +1,5 @@ In setting up my wiki I followed the [[setup]] instruction which point -to an [[ikiwiki.setup]] file that contains "verbose => 0". +to an ikiwiki.setup file that contains "verbose => 0". I hadn't noticed that setting in there, but later when I changed my standard command of: diff --git a/doc/ikiwiki-update-wikilist.mdwn b/doc/ikiwiki-update-wikilist.mdwn index 4e87f92e6..e5ea72e36 100644 --- a/doc/ikiwiki-update-wikilist.mdwn +++ b/doc/ikiwiki-update-wikilist.mdwn @@ -4,14 +4,16 @@ ikiwiki-update-wikilist - add or remove user from /etc/ikiwiki/wikilist # SYNOPSIS -ikiwiki-update-wikilist +ikiwiki-update-wikilist [-r] # DESCRIPTION -`ikiwiki-update-wikilist` is designed to be made suid root, but not installed +`ikiwiki-update-wikilist` is designed to be made suid root, but is not installed suid by default. If made suid, it allows users to add or remove their names -from the `/etc/ikiwiki/wikilist` file. If a user's name is not in the file, -it will be added; if the name is already present, it will be removed. +from the `/etc/ikiwiki/wikilist` file. + +By default, the user's name will be added. +The `-r` switch causes the user's name to be removed. If your name is in `/etc/ikiwiki/wikilist`, the [[ikiwiki-mass-rebuild]](8) command will look for a ~/.ikiwiki/wikilist file, and rebuild the wikis listed diff --git a/doc/ikiwiki.setup b/doc/ikiwiki.setup deleted file mode 100644 index 31a60b9ca..000000000 --- a/doc/ikiwiki.setup +++ /dev/null @@ -1,206 +0,0 @@ -#!/usr/bin/perl -# Configuration file for ikiwiki. -# Passing this to ikiwiki --setup will make ikiwiki generate wrappers and -# build the wiki. -# -# Remember to re-run ikiwiki --setup any time you edit this file. - -use IkiWiki::Setup::Standard { - wikiname => "MyWiki", - #adminuser => ["yourname", ], - adminemail => 'me@example.org', - - # Be sure to customise these.. - srcdir => "/path/to/source", - destdir => "/var/www/wiki", - - url => "http://example.org/wiki", - cgiurl => "http://example.org/wiki/ikiwiki.cgi", - #templatedir => "/usr/share/ikiwiki/templates", - #underlaydir => "/usr/share/ikiwiki/basewiki", - - # Subversion stuff. - #rcs => "svn", - #historyurl => "http://svn.example.org/trunk/[[file]]", - #diffurl => "http://svn.example.org/trunk/[[file]]?root=wiki&r1=[[r1]]&r2=[[r2]]", - #svnrepo => "/svn/wiki", - #svnpath => "trunk", - - # Git stuff. - #rcs => "git", - #historyurl => "http://git.example.org/gitweb.cgi?p=wiki.git;a=history;f=[[file]]", - #diffurl => "http://git.example.org/gitweb.cgi?p=wiki.git;a=blobdiff;h=[[sha1_to]];hp=[[sha1_from]];hb=[[sha1_parent]];f=[[file]]", - #gitorigin_branch => "origin", - #gitmaster_branch => "master", - - # Tla stuff. - #rcs => "tla" - #historyurl => ??, - #diffurl => ??, - - # Mercurial stuff. - #rcs => "mercurial", - #historyurl => "http://localhost:8000/log/tip/[[file]]", # hg serve'd local repository - #diffurl => "http://localhost:8000/?fd=[[r2]];file=[[file]]", - - # Bazaar stuff. - #rcs => "bzr", - #historyurl => "", - #diffurl => "http://example.com/revision?start_revid=[[r2]]#[[file]]-s", # using loggerhead - - # Monotone stuff - #rcs => "monotone", - #mtnkey => "web\@machine.company.com", - #historyurl => "http://viewmtn.example.com/branch/head/filechanges/com.example.branch/[[file]]", - #diffurl => "http://viewmtn.example.com/revision/diff/[[r1]]/with/[[r2]]/[[file]]", - # Set if you want the wiki to sync on update and commit. - #mtnsync => 0, - # The path to your workspace (defaults to the srcdir itself) - # e.g. use if your srcdir is a subdirectory of the workspace. - #mtnrootdir => "path/to/root/of/workspace", - - wrappers => [ - #{ - # # The cgi wrapper. - # cgi => 1, - # wrapper => "/var/www/wiki/ikiwiki.cgi", - # wrappermode => "06755", - #}, - #{ - # # The svn post-commit wrapper. - # # Note that this will overwrite any existing - # # post-commit hook script, which may not be - # # what you want. - # wrapper => "/svn/wikirepo/hooks/post-commit", - # wrappermode => "04755", - # # Log to syslog since svn post-commit hooks - # # hide output and errors. - # syslog => 1, - #}, - #{ - # # The git post-update wrapper. - # # Note that this will overwrite any existing - # # post-update hook script, which may not be - # # what you want. - # wrapper => "/git/wiki.git/hooks/post-update", - # wrappermode => "06755", - #}, - #{ - # # The monotone netsync hook. - # wrapper => "path/to/root/of/workspace/_MTN/ikiwiki-netsync-hook", - # wrappermode => "06755", - #}, - ], - - # Default to generating rss feeds for pages with feeds? - #rss => 1, - # Default to generating atom feeds for pages with feeds? - #atom => 1, - # Allow generating feeds even if not generated by default? - #allowrss => 1, - #allowatom => 1, - # Urls to ping with XML-RPC when feeds are updated - #pingurl => [qw{http://rpc.technorati.com/rpc/ping}], - # Include discussion links on all pages? - discussion => 1, - # To exclude files matching a regexp from processing. This adds to - # the default exclude list. - #exclude => qr/\.wav$/, - # To change the extension used for generated html files. - #htmlext => 'htm', - # Time format (for strftime) - #timeformat => '%c', - # Locale to use. Must be a UTF-8 locale. - #locale => 'en_US.UTF-8', - # Only send cookies over SSL connections. - #sslcookie => 1, - # Logging settings: - #verbose => 1, - syslog => 0, - # To link to user pages in a subdirectory of the wiki. - #userdir => "users", - # To create output files named page.html rather than page/index.html. - #usedirs => 0, - # Simple spam prevention: require an account-creation password. - #account_creation_password => "example", - # Cost of generating a password using Authen::Passphrase::BlowfishCrypt - #password_cost => 8, - # Uncomment to force ikiwiki to run with a particular umask. - #umask => 022, - # Default settings for the recentchanges page. - #recentchangespage => "recentchanges", - #recentchangesnum => 100, - # Use new '!'-prefixed preprocessor directive syntax - #prefix_directives => 1, - # Attempt to make hardlinks to source files instead of copying them. - # Useful if the wiki contains large media files. - #hardlink => 1, - # Enable use of multimarkdown features in .mdwn files. - #multimarkdown => 1, - - # To add plugins, list them here. - #add_plugins => [qw{goodstuff search wikitext camelcase - # htmltidy fortune sidebar map rst anonok}], - # If you want to disable any of the default plugins, list them here. - #disable_plugins => [qw{inline htmlscrubber passwordauth openid}], - # To add a directory to the perl search path, use this. - #libdir => "/home/me/.ikiwiki/", - - # To override environment variable settings, you can list values here. - #ENV => { - # TZ => "America/New_York", - # PATH => "/home/me/bin:/usr/local/bin:/usr/bin:/bin", - #}, - - # For use with the tag plugin, make all tags be located under a - # base page. - #tagbase => "tag", - - # For use with the search plugin if the omega cgi is located - # somewhere else. - #omega_cgi => "/usr/lib/cgi-bin/omega/omega", - - # For use with the openid plugin, to give an url to a page users - # can use to signup for an OpenID. - #openidsignup => "http://myopenid.com/", - - # For use with the mirrorlist plugin, a list of mirrors. - #mirrorlist => { - # mirror1 => "http://hostname1", - # mirror2 => "http://hostname2/mirror", - #}, - - # For use with the anonok plugin, a PageSpec specifying what - # pages anonymous users can edit - #anonok_pagespec => "*", - - # For use with the aggregate plugin. - # Enable aggregation to internal pages. New wikis should set this to 1, - # but if you use aggregate already, read the aggregate plugin docs - # before enabling it. - #aggregateinternal => 1, - # Allow aggregation to be triggered via the web. - #aggregate_webtrigger => 1, - - # For use with the pinger plugin, how many seconds to wait before - # timing out. - #pinger_timeout => 15. - - # For use with the amazon S3 plugin, your public access key id. - #amazon_s3_key_id => 'XXXXXXXXXXXXXXXXXXXX', - # And a file holding your secret key. This file *must* not be - # readable by others! - #amazon_s3_key_file => "/home/me/.hide/.s3_key - # The globally unique name of the bucket to use to store the wiki. - #amazon_s3_bucket => "mywiki", - # A prefix to prepend to each page name. - #amazon_s3_prefix => "wiki/", - # Uncomment to use the S3 European datacenter. - #amazon_s3_location => "EU", - # Uncomment if you need to store each index file twice. - #amazon_s3_dupindex => 1, - - # For use with the attachment plugin, a program that returns - # nonzero if its standard input contains an virus. - #virus_checker => "clamdscan -", -} diff --git a/doc/plugins.mdwn b/doc/plugins.mdwn index 5ee2bae89..83735c5fd 100644 --- a/doc/plugins.mdwn +++ b/doc/plugins.mdwn @@ -7,7 +7,7 @@ There's documentation if you want to [[write]] your own plugins, or you can [[install]] plugins [[contributed|contrib]] by others. To enable a plugin, use the `--plugin` switch described in -[[usage]], or the equivalent `add_plugins` line in [[ikiwiki.setup]]. +[[usage]], or the equivalent `add_plugins` line in ikiwiki.setup. Enable the [[goodstuff]] plugin to get a nice selection of plugins that will fit most uses of ikiwiki. diff --git a/doc/plugins/mirrorlist.mdwn b/doc/plugins/mirrorlist.mdwn index 89022e5ab..b371e8eb7 100644 --- a/doc/plugins/mirrorlist.mdwn +++ b/doc/plugins/mirrorlist.mdwn @@ -4,5 +4,4 @@ This plugin allows adding links a list of mirrors to each page in the wiki. For each mirror, a name and an url should be specified. Pages are assumed to exist in the same location under the specified url on each -mirror. The [[ikiwiki.setup]] file has an example of configuring a list of -mirrors. +mirror. diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn index 7c28088de..04b6ea8e9 100644 --- a/doc/plugins/write.mdwn +++ b/doc/plugins/write.mdwn @@ -357,6 +357,47 @@ something. The hook is passed named parameters: `page`, `oldpage`, `newpage`, and `content`, and should try to modify the content to reflect the name change. For example, by converting links to point to the new page. +### getsetup + + hook(type => "getsetup", id => "foo", call => \&getsetup); + +This hooks is not called during normal operation, but only when setting up +the wiki, or generating a setup file. Plugins can use this hook to add +configuration options. + +The hook is passed no parameters. It returns data about the configuration +options added by the plugin. It can also check if the plugin is usable, and +die if not, which will cause the plugin to not be offered in the configuration +interface. + +The data returned is a list of `%config` options, followed by a hash +describing the option. For example: + + return + option_foo => { + type => "boolean", + description => "enable foo", + safe => 1, + rebuild => 1, + }, + option_bar => { + type => "string", + example => "hello", + description => "what to say", + safe => 1, + rebuild => 0, + }, + +* `type` can be "boolean", "string", "integer", "pagespec", or "internal" + (used for values that are not user-visible). The type is the type of + the leaf values; the `%config` option may be an array or hash of these. +* `example` can be set to an example value. +* `description` is a short description of the option. +* `safe` should be false if the option should not be displayed in unsafe + configuration methods, such as the web interface. Anything that specifies + a command to run, a path on disk, or a regexp should be marked as unsafe. +* `rebuild` should be true if changing the option will require a wiki rebuild. + ## Plugin interface To import the ikiwiki plugin interface: @@ -376,7 +417,7 @@ it's not exported, the wise choice is to not use it. A plugin can access the wiki's configuration via the `%config` hash. The best way to understand the contents of the hash is to look at -[[ikiwiki.setup]], which sets the hash content to configure the wiki. +your ikiwiki setup file, which sets the hash content to configure the wiki. ### %pagestate @@ -613,15 +654,107 @@ PageSpecs glob patterns, but instead only by a special `internal()` ### RCS plugins -ikiwiki's support for [[revision_control_systems|rcs]] also uses pluggable -perl modules. These are in the `IkiWiki::RCS` namespace, for example -`IkiWiki::RCS::svn`. +ikiwiki's support for [[revision_control_systems|rcs]] is also done via +plugins. See [[RCS_details|rcs/details]] for some more info. + +RCS plugins must register a number of hooks. Each hook has type 'rcs', +and the 'id' field is set to the name of the hook. For example: + + hook(type => "rcs", id => "rcs_update", call => \&rcs_update); + hook(type => "rcs", id => "rcs_prepedit", call => \&rcs_prepedit); + +#### `rcs_update()` + +Updates the working directory with any remote changes. + +#### `rcs_prepedit($)` + +Is passed a file to prepare to edit. It can generate and return an arbitrary +token, that will be passed into `rcs_commit` when committing. For example, +it might return the current revision ID of the file, and use that +information later when merging changes. + +#### `rcs_commit($$$;$$)` + +Passed a file, message, token (from `rcs_prepedit`), user, and ip address. +Should try to commit the file. Returns `undef` on *success* and a version +of the page with the rcs's conflict markers on failure. + +#### `rcs_commit_staged($$$)` + +Passed a message, user, and ip address. Should commit all staged changes. +Returns undef on success, and an error message on failure. + +Changes can be staged by calls to `rcs_add, `rcs_remove`, and +`rcs_rename`. + +#### `rcs_add($)` + +Adds the passed file to the archive. The filename is relative to the root +of the srcdir. + +Note that this should not check the new file in, it should only +prepare for it to be checked in when rcs_commit (or `rcs_commit_staged`) is +called. Note that the file may be in a new subdir that is not yet in +to version control; the subdir can be added if so. + +#### `rcs_remove($)` + +Remove a file. The filename is relative to the root of the srcdir. + +Note that this should not check the removal in, it should only prepare for it +to be checked in when `rcs_commit` (or `rcs_commit_staged`) is called. Note +that the new file may be in a new subdir that is not yet inversion +control; the subdir can be added if so. + +#### `rcs_rename($$)` + +Rename a file. The filenames are relative to the root of the srcdir. + +Note that this should not commit the rename, it should only +prepare it for when `rcs_commit` (or `rcs_commit_staged`) is called. +The new filename may be in a new subdir, that is not yet added to +version control. If so, the subdir will exist already, and should +be added to revision control. + +#### `rcs_recentchanges($)` + +Examine the RCS history and generate a list of recent changes. +The parameter is how many changes to return. + +The data structure returned for each change is: + + { + rev => # the RCSs id for this commit + user => # name of user who made the change, + committype => # either "web" or the name of the rcs, + when => # time when the change was made, + message => [ + { line => "commit message line 1" }, + { line => "commit message line 2" }, + # etc, + ], + pages => [ + { + page => # name of page changed, + diffurl => # optional url to a diff of changes + }, + # repeat for each page changed in this commit, + ], + } + +#### `rcs_diff($)` + +The parameter is the rev from `rcs_recentchanges`. +Should return a list of lines of the diff (including \n) in list +context, and the whole diff in scalar context. + +#### `rcs_getctime($)` -Each RCS plugin must support all the `IkiWiki::rcs_*` functions. -See IkiWiki::RCS::Stub for the full list of functions. It's ok if -`rcs_getctime` does nothing except for throwing an error. +This is used to get the page creation time for a file from the RCS, by looking +it up in the history. -See [[RCS_details|rcs/details]] for some more info. +It's ok if this is not implemented, and throws an error. ### PageSpec plugins @@ -636,15 +769,15 @@ IkiWiki::FailReason object if the match fails. ### Setup plugins -The ikiwiki setup file is loaded using a pluggable mechanism. If you -look at the top of [[ikiwiki.setup]], it starts with -'use IkiWiki::Setup::Standard', and the rest of the file is passed to -that module's import method. +The ikiwiki setup file is loaded using a pluggable mechanism. If you look +at the top of a setup file, it starts with 'use IkiWiki::Setup::Standard', +and the rest of the file is passed to that module's import method. It's possible to write other modules in the `IkiWiki::Setup::` namespace that can be used to configure ikiwiki in different ways. These modules should, when imported, populate `$IkiWiki::Setup::raw_setup` with a reference -to a hash containing all the config items. +to a hash containing all the config items. They should also implement a +`gendump` function. By the way, to parse a ikiwiki setup file, a program just needs to do something like: diff --git a/doc/rcs/details.mdwn b/doc/rcs/details.mdwn index 9bf65762f..e62f3ef49 100644 --- a/doc/rcs/details.mdwn +++ b/doc/rcs/details.mdwn @@ -266,8 +266,7 @@ on the same local machine, I suggest to create the latter with the "`git clone - command to save disk space. Note that, as a rule of thumb, you should always put the rcs wrapper (`post-update`) -into the master repository (`.git/hooks/`) as can be noticed in the Git wrappers of -the sample [[ikiwiki.setup]]. +into the master repository (`.git/hooks/`). Here is how a web edit works with ikiwiki and git: diff --git a/doc/security.mdwn b/doc/security.mdwn index 498d2b4e7..0841abf49 100644 --- a/doc/security.mdwn +++ b/doc/security.mdwn @@ -66,8 +66,7 @@ So it's best if only one person can ever directly write to those directories. ## setup files Setup files are not safe to keep in the same revision control repository -with the rest of the wiki. Just don't do it. [[ikiwiki.setup]] is *not* -used as the setup file for this wiki, BTW. +with the rest of the wiki. Just don't do it. ## page locking can be bypassed via direct commits diff --git a/doc/setup.mdwn b/doc/setup.mdwn index 174d6ceb9..2989485f9 100644 --- a/doc/setup.mdwn +++ b/doc/setup.mdwn @@ -7,6 +7,21 @@ This tutorial will walk you through setting up a wiki with ikiwiki. If you're using Debian or Ubuntu, ikiwiki is an `apt-get install ikiwiki` away. If you're not, see the [[download]] and [[install]] pages. +## Quick start + +If you'd like to set up a wiki now, and learn more later, just run this command +and answer a couple of questions. + + % ikiwiki -setup /etc/ikiwiki/auto.setup + What will the wiki be named? mywiki + What revision control system to use? git + What wiki user (or openid) will be wiki admin? joey + +Wait for it to tell you an url for your new wiki.. Done! + +(If the CGI doesn't seem to let you edit pages, you might need to +[[configure_apache|apache_cgi]]).) + ## Decide where your wiki's files will go. As a wiki compiler, ikiwiki builds a wiki from files in a source directory, @@ -74,11 +89,16 @@ and `--rebuild` too. Get comfortable with its command line (see By now you should be getting tired of typing in all the command line options each time you change something in your wiki's setup. Time to introduce setup files. - -A sample setup file is [[ikiwiki.setup]]. Download it (or copy it from -`doc/ikiwiki.setup` in the ikiwiki sources), and edit it. Note that this -file should *not* be put in your wiki's directory with the rest of the -files. A good place to put it is in a ~/.ikiwiki/ subdirectory. + +To generate a setup file, use `ikiwiki --dumpsetup`. You can pass +all the options have you been including at the command line, and they +will be stored in the setup file. + + ikiwiki $SRCDIR $DESTDIR --url=http://example.org/~you/wiki/ --dumpsetup ikiwiki.setup + +Note that this file should *not* be put in your wiki's directory with +the rest of the files. A good place to put it is in a ~/.ikiwiki/ +subdirectory. Most of the options, like `wikiname` in the setup file are the same as ikiwiki's command line options (documented in [[usage]]. `srcdir` and @@ -91,12 +111,12 @@ will set everything up. ## Turn on additional features. -Now you have a basic wiki with a configuration file. Time to experiment +Now you have a basic wiki with a setup file. Time to experiment with ikiwiki's many features. Let's first enable a key wiki feature and set up [[CGI]] to allow editing the wiki from the web. Just edit ikiwiki.setup, uncomment the -block for the cgi wrapper, make sure the filename for the cgi wrapper +settings for the `cgi_wrapper`, make sure the filename for the cgi wrapper is ok, run `ikiwiki --setup ikiwiki.setup`, and you're done! There are lots of other configuration options in ikiwiki.setup that you @@ -113,7 +133,7 @@ on the revision control system you choose, the way this is done varies. Note that the .ikiwiki subdirectory is where ikiwiki keeps its state, and should be preserved, but not checked into revision control. -The new [[ikiwiki-makerepo]] command automates setting up a wiki in +The [[ikiwiki-makerepo]] command automates setting up a wiki in revision control. [[!toggle id=subversion text="Subversion"]] @@ -167,7 +187,7 @@ about using the git repositories. # remember the password you use in the next step and # substitute it for 'wikiKeyPass' in the get_passphrase() hook below # note the you should never generate two monotone keys with the same name - mtn genkey web@machine.company.com + mtn genkey web@example.com mtn db init --db=$REPOSITORY mv $SRCDIR $SRCDIR-old cd $SRCDIR-old @@ -188,11 +208,11 @@ about using the git repositories. Once your wiki is checked in to the revision control system, you should configure ikiwiki to use revision control. Edit your -ikiwiki.setup, and uncomment the lines for the revision control system +ikiwiki.setup, set `rcs` to the the revision control system you chose to use. Be sure to set `svnrepo` to $REPOSITORY, if using -subversion. Uncomment the block for the wrapper for your revision -control system, and configure the wrapper path in that block -appropriately (for Git, it should be `$REPOSITORY/hooks/post-update`). +subversion. Uncomment the configuration for the wrapper for your revision +control system, and configure the wrapper path appropriately +(for Git, it should be `$REPOSITORY/hooks/post-update`). Once it's all set up, run `ikiwiki --setup ikiwiki.setup` once more. Now you should be able to edit files in $SRCDIR, and use your revision diff --git a/doc/tips/nearlyfreespeech.mdwn b/doc/tips/nearlyfreespeech.mdwn index 435743bf9..6715f0c29 100644 --- a/doc/tips/nearlyfreespeech.mdwn +++ b/doc/tips/nearlyfreespeech.mdwn @@ -76,16 +76,15 @@ Here is an example of how I set up a wiki: mkdir ~/wiki cd ~/wiki - cp ~/ikiwiki/doc/ikiwiki.setup . cp -r ~/ikiwiki/doc/examples/blog/* . + ikiwiki -dumpsetup ikiwiki.setup nano ikiwiki.setup # Set destdir to /home/htdocs # Set srcdir to /home/private/wiki # Set url to http://yoursite.nfshost.com/ , set cgiurl likewise - # Uncomment the `rcs => "git"` line, and the cgi and git - # post-update wrapper blocks. - # Set the cgi wrapper path to /home/htdocs/ikiwiki.cgi - # Set the git wrapper path to /home/private/wiki.git/hooks/post-update + # Uncomment the `rcs => "git"` line. + # Set the cgi_wrapper path to /home/htdocs/ikiwiki.cgi + # Set the git_wrapper path to /home/private/wiki.git/hooks/post-update # Configure the rest to your liking and save the file. ikiwiki-makerepo git . ../wiki.git ikiwiki -setup ikiwiki.setup diff --git a/doc/todo/Make_example_setup_file_consistent.mdwn b/doc/todo/Make_example_setup_file_consistent.mdwn index 1fdff7b0f..54cc34af6 100644 --- a/doc/todo/Make_example_setup_file_consistent.mdwn +++ b/doc/todo/Make_example_setup_file_consistent.mdwn @@ -1,4 +1,4 @@ -The current example [[ikiwiki.setup]] file has a number of options included, but commented out. This is standard. Unfortunately there are two standards for the settings of those commented out options: +The current example ikiwiki.setup file has a number of options included, but commented out. This is standard. Unfortunately there are two standards for the settings of those commented out options: - Have the commented out options showing the default setting, or - Have the commented out options showing the most common alternate setting. @@ -26,4 +26,8 @@ What do others think? > I may not work on it myself, since I have some > [[interesting_ideas|online_configuration]] that would let ikiwiki > generate a setup file for you, rather than having to keep maintain the -> current example. --[[Joey]] +> current example. +> +> And.. [[done]].. setup files are now generated with `--dumpsetup`, based on +> the built-in defaults, and commented options show an example +> setting, not a default. --[[Joey]] diff --git a/doc/todo/cas_authentication.mdwn b/doc/todo/cas_authentication.mdwn index a6b428207..c8ffe7005 100644 --- a/doc/todo/cas_authentication.mdwn +++ b/doc/todo/cas_authentication.mdwn @@ -163,7 +163,7 @@ follows) ? +`/etc/ssl/certs/ca-certificates.crt` is sufficient). > It would be good to add commented-out examples of these to -> [[ikiwiki.setup]] as well. +> ikiwiki.setup as well. +This plugin is not enabled by default. It can not be used with other +authentication plugin, such as [[passwordauth]] or [[openid]]. diff --git a/doc/todo/color_plugin.mdwn b/doc/todo/color_plugin.mdwn index 1e1fb174e..511851ba3 100644 --- a/doc/todo/color_plugin.mdwn +++ b/doc/todo/color_plugin.mdwn @@ -193,9 +193,6 @@ Of course, I'm open for discussion or exchange of ideas :) --[[Paweł|ptecza]] + \[[!color background=#ff0000 text="Default color text on red background"]] + +Foreground is missing, so the text has default color. - + - +This plugin is not enabled by default. You can do that in [[ikiwiki.setup]] - +file (hint: `add_plugins` variable). --- style.css-orig 2008-07-27 15:12:39.000000000 +0200 +++ style.css 2008-07-27 15:15:06.000000000 +0200 @@ -333,3 +333,7 @@ diff --git a/doc/todo/conditional_underlay_files.mdwn b/doc/todo/conditional_underlay_files.mdwn index 14ab4dac3..c578bceaf 100644 --- a/doc/todo/conditional_underlay_files.mdwn +++ b/doc/todo/conditional_underlay_files.mdwn @@ -12,7 +12,7 @@ I can see two good ways to implement this. Ideally, with [[conditional_text_based_on_ikiwiki_features]] available, ikiwiki could parse a page like conditionalpages.mdwn, which could contain a set of conditional-wrapped page names; that seems like the most elegant and -ikiwiki-like approach. Alternatively, [[/ikiwiki.setup]] could contain a +ikiwiki-like approach. Alternatively, ikiwiki.setup could contain a Perl-generated exclude option by default; that would work, but it seems hackish. diff --git a/doc/todo/online_configuration.mdwn b/doc/todo/online_configuration.mdwn index 94c4c66f8..2393b75af 100644 --- a/doc/todo/online_configuration.mdwn +++ b/doc/todo/online_configuration.mdwn @@ -11,56 +11,21 @@ Currently admin prefs are per-admin, and are stored in the userdb. That seems like a bad choice in the context of this idea. Instead, admin setup should be configured on a separate page than the regular user prefs page, and should be shared amoung all admins, and the ideal storage would be -another ikiwiki setup file, which could be loaded in, and written back out. +a ikiwiki setup file, which could be loaded in, and written back out. -If `ikiwiki-makerepo` were extended a little bit to generate the stub setup -file that's enough to get `ikiwiki.cgi` working, and that sets values for -all the dangerous options, leaving only safe ones 'undef', then users could -set up ikiwiki using it, and configure the rest with the web interface, -without ever needing to edit a setup file. +The underlying work has been done to privide metadata about all options via +getsetup hooks, so it's just a matter of writing a web interface plugin. -The setup page could `require` every available plugin, and then call a -`getsetup` function, which would look something like: +The plugin could have these config options: - sub getsetup () { - eval q{use Some::Thing}; - die $@ if $@; + # list of options to include in web setup (safe = all things with safe = 1) + websetup_include => [qw{safe}], + # list of options to exclude from web setup + websetup_exclude => [qw{option_baz}], - return option_foo => { - safe => 1, - rebuild => 1, - type => "boolean", - default => 0, - description => gettext("Enable foo."), - }, - option_bar => { - safe => 0, - rebuild => 0, - type => "password", - default => "", - description => gettext("Password for bar."), - }; - } - -The types would be: boolean, string, password, filename, other. -This would be the type of the leaf fields; if a value in `%config` is an -array or hash, the type specifies the type of values that go into it. - -From this info, a form can be built, that has core setup values at the -top, followed by each plugin whose `getsetup` succeeded, with a check box -to enable/disable that plugin, and all of its setup options listed after -it. - -The main setup file could control what options are read from the -online setup file: - - online_setup_include => 'safe', # all things with safe = 1 - online_setup_exclude => [qw{option_baz}], - -Note that posting the setup form would sometimes need to cause a rebuild -of the whole wiki. This could be done with output streamed to the admin in -the web browser. The `rebuild` fields would be set to 1 for values that -require a wiki rebuild when changed, and to 0 for values that only need the -wrappers to be refreshed. +Leaning toward just making it write out to the same setup file, rather than +writing to a subsidiary setup file. However, this would mean that any +comments in the file would be lost, and that it couldn't be used if the +setup file had weird stuff (perl code, etc). [[!tag wishlist]] diff --git a/doc/usage.mdwn b/doc/usage.mdwn index 2b104bcdb..511bb687a 100644 --- a/doc/usage.mdwn +++ b/doc/usage.mdwn @@ -55,13 +55,16 @@ These options control the mode that ikiwiki operates in. 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 diff --git a/doc/w3mmode/ikiwiki.setup b/doc/w3mmode/ikiwiki.setup index e08856158..5f5cbbff9 100644 --- a/doc/w3mmode/ikiwiki.setup +++ b/doc/w3mmode/ikiwiki.setup @@ -17,19 +17,13 @@ use IkiWiki::Setup::Standard { cgiurl => 'ikiwiki.cgi', rcs => "", - wrappers => [ - { - # The cgi wrapper. - cgi => 1, - # The wrapper must be put in ~/.ikiwiki/wrappers/, since - # ikiwiki-w3m.cgi only looks in this one location. - # The wrapper can be given any name as long as it's - # in that directory. - wrapper => "$ENV{HOME}/.ikiwiki/wrappers/ikiwiki.cgi", - wrappermode => "0755", - }, - ], - + # The wrapper must be put in ~/.ikiwiki/wrappers/, since + # ikiwiki-w3m.cgi only looks in this one location. + # The wrapper can be given any name as long as it's + # in that directory. + cgi_wrapper => "$ENV{HOME}/.ikiwiki/wrappers/ikiwiki.cgi", + cgi_wrappermode => "0755", + add_plugins => [qw{anonok}], rss => 1, atom => 1, |