diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/about_rcs_backends.mdwn | 36 | ||||
| -rw-r--r-- | doc/features.mdwn | 4 | ||||
| -rw-r--r-- | doc/index.mdwn | 2 | ||||
| -rw-r--r-- | doc/post-commit.mdwn | 29 | ||||
| -rw-r--r-- | doc/recentchanges.mdwn | 4 | ||||
| -rw-r--r-- | doc/setup.mdwn | 64 | ||||
| -rw-r--r-- | doc/subversion.mdwn | 9 | ||||
| -rw-r--r-- | doc/usage.mdwn | 15 | ||||
| -rw-r--r-- | doc/whyikiwiki.mdwn | 11 |
9 files changed, 86 insertions, 88 deletions
diff --git a/doc/about_rcs_backends.mdwn b/doc/about_rcs_backends.mdwn index 197f09394..1aafd4a8e 100644 --- a/doc/about_rcs_backends.mdwn +++ b/doc/about_rcs_backends.mdwn @@ -76,9 +76,9 @@ off from R1. (To be continued.) -## [[Git]] (not yet included) +## [[Git]] -A patch with full [Git](http://git.or.cz) support is at <http://people.debian.org/~roktas/patches/ikiwiki/git.patch>. Regarding the patch, Recai says: +Regarding the Git support, Recai says: I have been testing it for the past few days and it seems satisfactory. I haven't observed any race condition regarding the concurrent blog commits @@ -90,35 +90,3 @@ bugs. It also has some drawbacks (especially wrt merge which was the hard part). GIT doesn't have a similar functionality like 'svn merge -rOLD:NEW FILE' (please see the relevant comment in mergepast for more details), so I had to invent an ugly hack just for the purpose. - -Some other notes: - -- There are two separate helper packages in git.pm. To keep things self - confined, I haven't split it up. - -- I've used a (mini) Debug.pm during the tests and made it a separate file - for the convenience of others. It relies on the "constant folding" - feature of Perl, so there shouldn't be a runtime penalty (at least this - is what the 'perl -MO=Deparse shows', haven't made a real benchmark). - -- rcs_notify() has not been implemented yet (I have noticed it after I - finished the main work). - -- GIT backend uses the gitweb for repository browsing (the counterpart of - ViewCVS). - -- There might be some subs in GIT name space which you may prefer to move to - the main code. - -- Due to the reasons explained in the code, I've written an rcs_invoke() - wrapper. May be there should be a better approach to reach the same - goal. - -- There are some parts which I may change in future, like using a global - rcs_fatal_error and the ugly error reporting code in _rcs_commit. - -- Documentation is missing. - -It works for me, but of course in the end, the final decision is yours (due -to mostly GIT quirks, the implementation is not clean as SVN). Feel free -to fix/delete/add whatever you want. Hope it doesn't have any serious bug. diff --git a/doc/features.mdwn b/doc/features.mdwn index 30fe5987b..12e9d0528 100644 --- a/doc/features.mdwn +++ b/doc/features.mdwn @@ -3,7 +3,9 @@ Some of ikiwiki's features: * [[Subversion]] Rather than implement its own system for storing page histories etc, - ikiwiki simply uses subversion. (It's also possible to [[plugins/write]] support for other systems.) + ikiwiki simply uses subversion. (It's also possible to [[plugins/write]] + support for other systems, and ikiwiki also includes support for [[Git]] + now.) Instead of editing pages in a stupid web form, you can use vim and commit changes via svn. Or work disconnected using svk and push your changes out diff --git a/doc/index.mdwn b/doc/index.mdwn index 3d10751c6..5cb4ddee3 100644 --- a/doc/index.mdwn +++ b/doc/index.mdwn @@ -2,7 +2,7 @@ ikiwiki is a **wiki compiler**. It converts a directory full of wiki pages into html pages suitable for publishing on a website. Unlike a traditional wiki, ikiwiki does not have its own means of storing page history or its own -markup language. Instead it uses [[Subversion]] and [[MarkDown]]. +markup language. Instead it uses [[Subversion]] (or [[Git]]) and [[MarkDown]]. * [[News]] is a blog (built using ikiwiki) of news items about ikiwiki. It's the best way to find out when there's a new version to [[Download]]. diff --git a/doc/post-commit.mdwn b/doc/post-commit.mdwn index 93d851959..1ce271487 100644 --- a/doc/post-commit.mdwn +++ b/doc/post-commit.mdwn @@ -1,32 +1,19 @@ -A post-commit hook is run every time you commit a change to your subversion -repository. To make the wiki be updated each time a commit is made, it can -be run from (or as) a post-commit hook. +A post-commit hook is run every time you commit a change to your +[[subversion]] (or [[git]]) repository. To make the wiki be updated each +time a commit is made, it can be run from (or as) a post-commit hook. -The best way to run ikiwiki in a [[Subversion]] post-commit hook is using -a wrapper, which can be generated using `ikiwiki --wrapper`. - -First, set up the subversion checkout that ikiwiki will update and compile -into your wiki at each subversion commit. Run ikiwiki a few times by hand -to get a feel for it. Now, generate the wrapper by adding "--wrapper" -to whatever command line you've been using to run ikiwiki. For example: - - ~/wiki-checkout> ikiwiki . ~/public_html/wiki - ~/wiki-checkout> ikiwiki . ~/public_html/wiki --wrapper - successfully generated ikiwiki-wrap +The best way to run ikiwiki in a post-commit hook is using a wrapper, which +ikiwiki is usually configured to generate using a setup file. The generated wrapper is a C program that is designed to safely be made suid if necessary. It's hardcoded to run ikiwiki with the settings specified when you ran --wrapper, and can only be used to update and compile that one checkout into the specified html directory. -Now, put the wrapper somewhere convenient, and create a post-commit hook -script in your subversion repository for the wiki. All the post-commit -hook has to do is run the wrapper (with no parameters). - -Depending on your Subversion setup, the post-commit hook might end up -getting called by users who have write access to subversion, but not to +Depending on your setup, the post-commit hook might end up +getting called by users who have write access to the repository, but not to your wiki checkout and html directory. If so, you can safely make -ikiwiki-wrap suid to a user who can write there (*not* to root!). You might +the wrapper suid to a user who can write there (*not* to root!). You might want to read [[Security]] first. [[setup]] explains setting this up in more detail. diff --git a/doc/recentchanges.mdwn b/doc/recentchanges.mdwn index 56b68273a..a40f396b6 100644 --- a/doc/recentchanges.mdwn +++ b/doc/recentchanges.mdwn @@ -1 +1,3 @@ -ikiwiki generates the list of recent changes by examining the [[Subversion]] commit log. You have to have [[CGI]] set up for this feature to be enabled.
\ No newline at end of file +ikiwiki generates the list of recent changes by examining the +[[Subversion]] or [[Git]] commit log. You have to have [[CGI]] set up for +this feature to be enabled. diff --git a/doc/setup.mdwn b/doc/setup.mdwn index 7e4aaecf9..f93f71fe1 100644 --- a/doc/setup.mdwn +++ b/doc/setup.mdwn @@ -1,18 +1,28 @@ So you want to set up your own wiki using ikiwiki? This tutorial will walk -you through setting up a wiki that is stored in [[Subversion]] and that has -optional support for commits from the web. +you through setting up a wiki that is stored in [[Subversion]] or [[Git]], +and that has optional support for commits from the web. 1. [[Install]] ikiwiki. See [[download]] for where to get it. -2. Create the subversion repository for your wiki. +2. Create the master rcs repository for your wiki. + # Subversion svnadmin create /svn/wikirepo svn mkdir file:///svn/wikirepo/trunk -m create + # Git + mkdir /git/wikirepo + cd /git/wikirepo + git init-db + 3. Check out the repository to make the working copy that ikiwiki will use. + # Subversion svn co file:///svn/wikirepo/trunk ~/wikiwc + # Git + git clone /git/wikirepo ~/wikiwc + 4. Build your wiki for the first time. ikiwiki --verbose ~/wikiwc/ ~/public_html/wiki/ \ @@ -25,10 +35,18 @@ optional support for commits from the web. used if you don't have a custom version, so let's start by making a custom version of the wiki's index page: - cp /usr/share/ikiwiki/basewiki/index.mdwn ~/wikiwc - svn add ~/wikiwc/index.mdwn - $EDITOR ~/wikiwc/index.mdwn - svn commit ~/wikiwc/index.mdwn -m customised + cd ~/wikiwc + cp /usr/share/ikiwiki/basewiki/index.mdwn . + $EDITOR index.mdwn + + # Subversion + svn add index.mdwn + svn commit -m customised index.mdwn + + # Git + git add index.mdwn + git commit -m customised index.mdwn + git push origin You can also add any files you like from scratch of course. @@ -46,15 +64,15 @@ optional support for commits from the web. `doc/ikiwiki.setup` in the ikiwiki sources), and edit it. Most of the options, like `wikiname` in the setup file are the same as - ikiwiki's command line options (documented in [[usage]]. `srcdir` - and `destdir` are the two directories you specify when - running ikiwiki by hand. `svnrepo` is the path to your subversion - repository. Make sure that all of these are pointing to the right - directories, and read through and configure the rest of the file to your - liking. + ikiwiki's command line options (documented in [[usage]]. `srcdir` and + `destdir` are the two directories you specify when running ikiwiki by + hand. `rcsrepo` is the path to your master rcs repository. Make sure + that all of these are pointing to the right directories, and read + through and configure the rest of the file to your liking. - Note that the default file has a block to configure a svn wrapper. This - sets up a [[post-commit]] hook to update the wiki. + Note that the default file has a block to configure an Rcs wrapper to + update the wiki. You need to uncomment the related block for whatever + rcs you use and comment out the other rcs blocks. When you're satisfied, run `ikiwiki --setup ikiwiki.setup`, and it will set everything up and update your wiki. @@ -66,12 +84,20 @@ optional support for commits from the web. `ikiwiki --setup ikiwiki.setup`, and you're done! 9. Add [[PageHistory]] links to the top of pages. This requires you to have - setup [[ViewCVS]] or something similar to access your [[Subversion]] - repository. The `historyurl` setting makes ikiwiki add the links, and - in that url, "\[[file]]" is replaced with the name of the file to view. So - edit ikiwiki.setup and set `historyurl` to something like this: + setup a repository browser. For Subversion, you may use [[ViewCVS]] or + something similar to access your [[Subversion]] repository. For Git, + [[Gitweb]] can be used. + + The `historyurl` setting makes ikiwiki add the links, and in that url, + "\[[file]]" is replaced with the name of the file to view. So edit + ikiwiki.setup and set `historyurl` to something like this for + Subversion: `http://svn.host/trunk/\[[file]]?root=wiki` + + Or this for Git: + + `http://git.host/gitweb.cgi?p=wiki.git;a=history;f=[[file]]` Then run `ikiwiki --setup ikiwiki.setup` again. diff --git a/doc/subversion.mdwn b/doc/subversion.mdwn index 51fc5f485..47cdba450 100644 --- a/doc/subversion.mdwn +++ b/doc/subversion.mdwn @@ -1,4 +1,9 @@ Subversion is a revision control system. While ikiwiki is relatively -independant of the underlying revision control system, and can easily be used without one, using it with Subversion is recommended. +independant of the underlying revision control system, and can easily be +used without one, using it with Subversion is recommended since it's how +the author uses it. -Ikiwiki can run as a [[post-commit]] hook to update a wiki whenever commits come in. When running as a [[cgi]] with Subversion, ikiwiki automatically commits edited pages to the subversion repostory, and uses the Subversion log to generate the [[RecentChanges]] page. +Ikiwiki can run as a [[post-commit]] hook to update a wiki whenever commits +come in. When running as a [[cgi]] with Subversion, ikiwiki automatically +commits edited pages to the subversion repostory, and uses the Subversion +log to generate the [[RecentChanges]] page. diff --git a/doc/usage.mdwn b/doc/usage.mdwn index 011cf53a2..eec1856a7 100644 --- a/doc/usage.mdwn +++ b/doc/usage.mdwn @@ -46,7 +46,7 @@ These options control the mode that ikiwiki is operating in. directory. The filename to use for the wrapper is optional. The wrapper is designed to be safely made suid and be run by untrusted - users, as a [[Subversion]] [[post-commit]] hook, or as a [[CGI]]. + users, as a [[post-commit]] hook, or as a [[CGI]]. Note that the generated wrapper will ignore all command line parameters. @@ -88,14 +88,17 @@ These options configure the wiki. * --notify Enable email notification of commits. This should be used when running - ikiwiki as a [[Subversion]] [[post-commit]] hook. + ikiwiki as a [[post-commit]] hook. * --rcs=svn, --no-rcs Enable or disable use of a revision control system. - If you use svn ([[Subversion]]), the `source` directory is assumed to be - a working copy, and is automatically updated before building the wiki. + If you use svn, the `source` directory is assumed to be + a [[Subversion]] working copy. + + If you use git, the `source` directory is assumed to be a clone of the + [[git]] repository. In [[CGI]] mode, with a revision control system enabled pages edited via the web will be committed. Also, the [[RecentChanges]] link will be placed @@ -164,8 +167,8 @@ These options configure the wiki. * --plugin name - Enables the use of the specified plugin in the wiki. See [[plugins]] for - details. Note that plugin names are case sensative. + Enables the use of the specified [[plugin|plugins]] in the wiki. + Note that plugin names are case sensative. * --disable-plugin name diff --git a/doc/whyikiwiki.mdwn b/doc/whyikiwiki.mdwn index a2355d344..2bc1fe416 100644 --- a/doc/whyikiwiki.mdwn +++ b/doc/whyikiwiki.mdwn @@ -3,8 +3,13 @@ this a pretty Iky Wiki, since it's so different from other Wikis. Partly because "ikiwiki" is a nice palindrome. Partly because its design turns the usual design for a Wiki inside-out and backwards. -(BTW, I'm told that "iki" is Finnish for "forever" so ikiwiki is "forever wiki".) +(BTW, I'm told that "iki" is Finnish for "forever" so ikiwiki is "forever +wiki".) -Oh, maybe you wanted to know why you'd want to choose ikiwiki instead of all the other wikis out there? Unless your personal strangeness significantly aligns with [[Joey]]'s, so that keeping everything in subversion, compiling websites to static html, and like design [[features]] appeal to you, you probably won't. +Oh, maybe you wanted to know why you'd want to choose ikiwiki instead of +all the other wikis out there? Unless your personal strangeness +significantly aligns with [[Joey]]'s, so that keeping everything in +subversion, compiling websites to static html, and like design [[features]] +appeal to you, you probably won't. -Hmm, the above paragraph is less true today than it was when I wrote it.
\ No newline at end of file +Hmm, the above paragraph is less true today than it was when I wrote it. |