| Emacs, this is -*- Text -*- for you. |
| |
| |
| JSPWiki documentation |
| ===================== |
| |
| $Revision: 1.17.2.1 $ |
| $Date: 2003-07-16 15:50:46 $ |
| $Author: jalkanen $ |
| |
| What is it? |
| ----------- |
| |
| JSPWiki is a simple WikiWiki clone. It keeps all of its |
| formatting in JSP files, and uses a custom Java class called |
| 'com.ecyrd.jspwiki.WikiEngine' to all interfacing with the Wiki |
| system. |
| |
| |
| Copyright (C) 2001-2003 Janne Jalkanen |
| |
| This program is free software; you can redistribute it and/or |
| modify it under the terms of the GNU Lesser General Public License |
| as published by the Free Software Foundation; either version 2.1 |
| of the License, or (at your option) any later version. |
| |
| This program is distributed in the hope that it will be useful, |
| but WITHOUT ANY WARRANTY; without even the implied warranty of |
| MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
| Lesser General Public License for more details. |
| |
| You should have received a copy of the GNU Lesser General Public |
| License along with this program; if not, write to the Free |
| Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA |
| 02111-1307 USA |
| |
| |
| The license file can be found in doc/LICENSE. |
| |
| (No, the LGPL does not mean that all the content in your new wiki will |
| be under the LGPL, anymore than any text you write using Emacs becomes |
| GPL.) |
| |
| One small request I have. If you really, really like this software, |
| donate a small amount of money to the World Wildlife Foundation |
| (WWF), Free Software Foundation (FSF), or Electronic Freedom |
| Foundation (EFF), or whichever charity is close to your heart. |
| |
| The world doesn't need to become a bad place. |
| |
| Oh yeah, and if you run a Wiki based on this software, let me know. |
| I'm always interested in hearing from my users =). |
| |
| |
| Pre-requirements |
| ---------------- |
| |
| Okay, so you wanna Wiki? You'll need the following things: |
| |
| REQUIRED: |
| |
| * A JSP engine. I recommend Tomcat from |
| http://jakarta.apache.org/tomcat for a really easy installation. |
| |
| * Some previous administration experience... If you've ever installed |
| Apache or any other web server, you should be pretty well off. |
| |
| * And of course, a server to run the JSP engine on. |
| |
| OPTIONAL: |
| |
| * JavaMail package from java.sun.com, if you want to use log4j mailing |
| capabilities. You'll also need the Java Activation Framework. |
| |
| * RCS versioning system installed and available in your PATH if you |
| want to use RCS versioning. It is also possible (and on Windows, it |
| is even recommended) to use the VersioningFileProvider, which does |
| not require RCS. |
| |
| |
| |
| Installation |
| ------------ |
| |
| First, install a JSP engine and a web server. You can download Tomcat |
| from http://jakarta.apache.org/tomcat/. This software was built |
| originally on top of Tomcat 3.2.2, but probably most other versions |
| work, too, and most other JSP containers. |
| |
| After you've installed the engine and checked that it works, you just |
| make a subdirectory under $TOMCAT_HOME/webapps/. For example, if you |
| want your application to be called 'MyWiki', just create a directory |
| called 'MyWiki', then extract all files from the war files into that |
| directory, preserving the directory structure. |
| |
| Edit the WEB-INF/jspwiki.properties file to your liking. The only |
| thing you need to set is the directory where you want your wiki pages |
| to be stored. I recommend a directory that is regularly backed up. |
| |
| Unzip the contents of jspwiki-samplepages.zip into your newly created |
| directory. You can find the rest of the documentation in there. |
| |
| (Re)start tomcat. |
| |
| Point your browser at http://<where your Tomcat is installed>/MyWiki/. |
| You should see the Main Wiki page. See the next section if you want |
| to edit the pages =). |
| |
| |
| Installation with Windows |
| ------------------------- |
| |
| If you are using a version of Microsoft Windows, you'll find that |
| getting RCS up and running may be a bit problematic, and thus we |
| recommend the VersioningFileProvider. |
| |
| There is some documentation within the samplepages archive, on page |
| "WindowsInstall". |
| |
| |
| |
| Upgrading from previous versions |
| -------------------------------- |
| |
| Please read ReleaseNotes. |
| |
| |
| Setting access controls |
| ----------------------- |
| |
| If you don't want everyone to have access to your Wiki, take a look a |
| the "web.xml" file. It contains sample configuration for someone who |
| wants a Wiki that's viewable by all, but editable only be few. By |
| default, this is disabled, so your new Wiki is a free-for-all. |
| |
| Remove the marked comments from web.xml. |
| |
| Add a user to the "user" role in $TOMCAT_HOME/conf/tomcat-users.xml. |
| For example: |
| <user name="wiki" password="wiki" roles="user" / |
| adds an user called "wiki" with a password "wiki". |
| |
| Restart Tomcat. |
| |
| |
| Configuring JSPWiki |
| ------------------- |
| |
| All configuration information is kept in WEB_INF/jspwiki.properties. |
| The file is pretty well documented, so I recommend you read it through |
| first. |
| |
| The other good document to read is doc/Templates.txt, which explains |
| how the JSPWiki templating system works. |
| |
| |
| Where to go next aka. where is the rest of the documentation? |
| ------------------------------------------------------------- |
| |
| With this information, you should've gotten the JSPWiki engine |
| running. I now suggest that you extract all of the files in |
| jspwiki_samplepages.zip into your page repository directory, and start |
| reading the documentation. Most of the documentation comes in the |
| form of Wiki pages, which you can obviously read with a text editor as |
| well. |
| |
| |
| Notes: |
| ~~~~~~ |
| |
| Feel free to edit the JSP pages anyway you like. Just don't touch any |
| of the Java code, unless you know what you're doing, because otherwise |
| the Wiki might stop to work. Most modern HTML editors are smart |
| enough not to mess with the JSP tags (all the stuff between <% and |
| %>). |
| |
| With JSPWiki v2, we have split the functionality from presentation. |
| Thus you can, and should edit only the pages under templates/. See |
| the page WikiTemplates for more information. |
| |
| While Tomcat is also a fully featured Web server, it is not |
| particularly fast. You might also have a web server already running. |
| Tomcat does integrate itself pretty well with existing web servers, |
| such as Apache, so you can just see the instructions at |
| http://jakarta.apache.org/ to see how to get Tomcat and Apache talking |
| to each other using mod_jk. (Don't use mod_jserv, it's outdated and |
| confusing.) |
| |
| RCS may be a bit troublesome to set up. I recommend you just run it |
| without RCS at first, then switch over when you understand how Wiki |
| works. |
| |
| |
| Files |
| ----- |
| |
| Files are kept in a subdirectory, which is defined in the |
| jspwiki.properties file. All files are in text format (usually in the |
| system's native format), with a file ending defined in |
| WikiEngine.java. This is ".txt" by default. |
| |
| There are some default files with the distribution archive. Feel free |
| to use them to bootstrap your own Wiki. |
| |
| |
| Internationalisation |
| -------------------- |
| |
| JSPWiki can also handle UTF-8. However, you need to switch this at |
| install-time, since the old method of handling ISO-8859-1 and the new |
| method of handling UTF-8 are not compatible, and I did not wish to |
| break previous installations that are already using the ISO-8859-1 |
| charset. |
| |
| If you're interested, the reason is as follows: W3C forgot to define |
| a standard how URLs that are not US-ASCII should be handled. The Web |
| de-facto standard is to use ISO-8859-1 (Latin1) and encode it with |
| (%xy), where xy is the hexadecimal representation. However, this |
| means that everyone else in the world can't use this. So, very |
| logically, you can also encode UTF-8 in this format. Unfortunately, |
| there is NO way to distinguish between these URLs that are really |
| UTF-8 and those URLs that are ISO-8859-1, since they look exactly the |
| same. This is why you must tell JSPWiki which character set to use |
| to start with. |
| |
| The FileSystemProvider and RCSFileProvider save the files on the disk |
| just as if they were URLs. This can get really messy with Japanese |
| language page names, for example. You can always check the URL to the |
| page, to find how they are named on the disk =). |
| |
| There are some known issues with UTF-8 support on some older browsers. |
| Please check |
| http://www.ecyrd.com/JSPWiki/Wiki.jsp?page=JSPWikiBrowserCompatibility |
| for more information. |
| |
| |
| Plugins |
| ------- |
| |
| Since v1.6.3 you can now define your own plugins. These are just |
| simply Java classes that implement the |
| 'com.ecyrd.jspwiki.plugin.WikiPlugin' interface and can be found from |
| somewhere in your class path. The plugins work so that when you write |
| a special code on the Wiki page, the plugins are invoked and their |
| output is inserted into the page, verbatim. |
| |
| The form is: |
| |
| [{INSERT <plugin class> WHERE <param1=value1>,<param2=value2>,...}] |
| |
| Check out the JSPWikiPlugins page from the JSPWiki distribution for |
| more information. |
| |
| |
| Attachments |
| ----------- |
| |
| Version 2 now brings new attachment functionality. I recommend |
| reading the WikiAttachments page. |
| |
| |
| |
| XML-RPC |
| ------- |
| |
| JSPWiki comes configured with two XML-RPC interfaces. The first |
| interface, which lives by default in <your-wiki-url>/RPC2, is a fully |
| XML-RPC spec compliant version, whereas the other one, which lives at |
| <your-wiki-url>/RPCU makes things easier by accepting UTF-8 -format |
| strings. |
| |
| You can configure the URLs and other things from the web.xml file. By |
| default, the XML-RPC interface is NOT enabled. |
| |
| For more information about the XML-RPC interface, see the |
| "WikiRPCInterface" page in the default JSPWiki distribution. |
| |
| |
| Acknowledgements |
| ---------------- |
| |
| This product includes software developed by the Apache Software Foundation |
| (http://www.apache.org/). See doc/LICENCE.Apache for more information. |
| |
| This product includes software developed by the OpenSymphony Group |
| (http://www.opensymphony.org/). See doc/LICENSE.OpenSymphony for more |
| information. |
| |
| There have been many contributors so far. Especially thanks go to |
| Erik Bunn, Niilo Neuvo, Alain Ravet, Kalle Kivimaa, Jeff Phillips, and |
| Mahlen Morris, Paul Downes, Michael Gentry, John Volkar, Torsten |
| Hildebrandt, and Foster Schucker who have given me quite a lot of |
| support and/or code. There are also a number of other people who have |
| generously given their time, and you can find hopefully all of their |
| names in the ChangeLog. |
| |
| |
| Contact |
| ------- |
| |
| JSPWiki was written by Janne Jalkanen. You may send email to me at |
| Janne.Jalkanen@nospam.ecyrd.com. (Remove the nospam from the |
| address). Feel free to send me patches, suggestions, whatever. |
| |
| JSPWiki is available at http://www.iki.fi/~jalkanen/JSPWiki/ |
| |
| My PGP key is below. |
| |
| -----BEGIN PGP PUBLIC KEY BLOCK----- |
| Version: PGP 5.0i |
| |
| mQENAzhx4k0AAAEIAJgD8PD7FAmrZuzJ5SXjDtD6fSPa5UCoxXVFSuS7G5mLwgGp |
| Di/iQtyt3Roxvu1f1G/DfG/DMHmQ/VLNK5svCKsg1RGUdDY40OWJAtYGtAXDKEBP |
| NrxHhnYqgnPCmrMNND7Gz7vbJFQGyTxNVKpof9vg+We7gZDo+7VGpHlGbuL0yeFD |
| ylOxZ8qZ+Dw5XiRBOvtOhoOPxbZuvq+pBUSZJPa3G4BQ53++qlhta7YiUUnUzXW7 |
| xHgv164BGUX3NKQaB0tb+gu3jkSOv4SBfEQ/Aej2yNPLSIZHLk1s2Ls6fpQzQo99 |
| P0sMW7uRG3CUOZ5Slsfb0XH67TibjBac+FSOr7MABRG0KEphbm5lIEphbGthbmVu |
| IDxKYW5uZS5KYWxrYW5lbkByZWdleC5maT6JARUDBRA4ceJNjBac+FSOr7MBATr9 |
| B/9nUAAZvhtLKv1jAFw9eQALWvkXEKRpWJK92/fT4fTkuSr9JTrM/VGPs7mz6tcp |
| 1SwFtfQHIc3qUbZv0j50HE8OF8ibGSaD0eitYuBcn302TbNDXYTs4aPJix5Tp7or |
| hapafBqy+1nda97mcDcgk9+riKx/awsMhyvyXi15qrv7/MMcsPSbZCsNwvkbENp6 |
| 5WTMy0PI6PBXTws/sSM5yMj9XN0cZkvC/EbtXdt/FJWJNEhd5kUBUUeHeCHPVGUS |
| LZ81OqnqFTncZiT3TxoQuf6Lj14lrV+m/pQte+KmCfdTLHEf/hslsctN66Lh0O1a |
| 83YAPm6qvUAxvS8ewJf5+WeHiQCVAwUQOHNMD+bGByqRaOUdAQGtogQAsjIqoj8K |
| blb54i8cbYb55R4KvqzY6aXyLj2JpUfG7oFjo+sailpqmRb6w6iai9+6lSdh5e2c |
| zo+E0vEErdJ/+jUGhG2cVf3ho4NYeE9C9Ac1TnMlTQntTdTlgOZY6l6C+l2suNfO |
| hKEeVUo5n1tIeIk1McE+Wae4wbcTCCObqke0Jkphbm5lIEphbGthbmVuIDxKYW5u |
| ZS5KYWxrYW5lbkBpa2kuZmk+iQEVAwUQOazF1owWnPhUjq+zAQH2bQf/SUxOks+7 |
| Cw2uNXWBjb3DkFLX3JEvhIO1jOft4jioBQpPA0l8hslP2o+i1nyfRg2TIK9shLyx |
| BwTHvVdqucrGH8v4Hzb3gDOPP6KMQgdMWvvwcgFCEhSZCORMaSrInRorcOTgagkf |
| 3h8AjG0grS3W0pFQlscL4mS9V3qAV3n7OBoPmustQJH8Ir28Enhto89bKU39PPQI |
| wcnlmpGcxk/Wk1+InJkov+A2TvXi/74dgPSfhSHMQM6pCBGtP8lrpYtBX6nYR+uG |
| rwPOs8ocYZrARBjaX1VuYJ941pZ6JwlRgpfv87jBFC7o5N7NE0+TZmOf5H1HhBXZ |
| g0ieP1dXfgH3ZrQsSmFubmUgSmFsa2FuZW4gPEphbm5lLkphbGthbmVuQHJlZ2V4 |
| LmNvbS5hdT6JARUDBRA52WB8jBac+FSOr7MBAdcKCACL4EqspqIG8xU5cpA3nULq |
| d/HVmg9+I1jfCceTLI5+PoQB5pRqdgKK3D+El+GNTFVDIGrS9X/gI4c+P/rVMGCF |
| 37SmuXzfB1vMsrK/WQqpKWQEqObV5qBjUg7vESx6QUoAaDRIO/7t250M+W5qGXq1 |
| 6G38qP+XFT7aEfc7MiYXyioB/oMK5XLtZufBLYa5rRZA6GIJ9dv6Cd9vLxkAtqqK |
| sWVGtvE0EWahEXGt+T2m60dgkiG3wMoPzvofb7UgHvltp1VSk5L7zds7pncIAP54 |
| dXcHfSHeYLN4thyTk3F0hV/jjBrrhzBOdvsguWMAE94Ec4ePzfP2oXhl0wA9GJxk |
| =Z2MZ |
| -----END PGP PUBLIC KEY BLOCK----- |