User's Guide - miniWiki

Preamble

Advanced topics are marked with (A). Needs reorganization/rewrite.

README

At first read README file distributed with miniWiki packages.

Wiki is composed of pages which are written in special Wiki markup (rendered as HTML when viewed). These page may be interlinked. Each page consists of set of revisions, latest revision called HEAD. Page update adds new revision.

Interface

Interface is composed of header, body and footer. Header shows page name (possibly with current action description):

Editing User's Guide

There may also be some information text (like "Page updated", "Login invalid") below page name.

Footer looks like this:

Main Page | Logged as admin | Revision: HEAD (3) | View Source | 2005/04/16 13:20:40 | View | Edit | Rename | Delete | History

Main Page always points to the HEAD revision of Main Page
Logged as admin or Login executes login action (see below for more information)
Revision: HEAD (3) shows current page's revision (if applicable), if current revision is HEAD then real revision is also shown
View Source or View toggles between viewing rendered page (with current revision) and its source
2005/04/16 13:20:40 is modification time of current page (with current revision) or current time for special pages
View points to the HEAD revision of current page
Edit points to the editor of HEAD revision of current page
Rename renames current page (redirection from old page will be created)
Delete deletes current page and all its revisions (there is no undelete!)
History shows list of revisions of current page

Some actions may be disabled (not clickable) if current user does not have necessary rights. Some actions may be missing if they are not meaningful (like View Source on history page).

Viewing page which does not exist opens page editor.

Login Process

HTTP Basic Auth is used for login. When user is already logged in, it is possible to log out by cancelling login action (works only in browsers which throw credentials away if login process is cancelled).

User Rights

Everyone can view everything, only logged user can edit and delete pages and only administrator can create and delete users. Logged user can change its own password, admin can change passwords of all users.

By changing settings in userdefs.php anonymous users may be switched off and non-admins may not be allowed to edit pages.

Page Editing

Page names are case sensitive (even names of special and user pages). Range of characters permitted in page name depends on storage, generally space, alphabetical characters, digits, comma (","), apostrophe ("'") and quotation marks (""") are allowed. Note that even though page names are treated as case sensitive by generic code, storage may treat them as case insensitive, so having two pages differing in name case may result in strange behaviour.

Namespaces

Pages are organized in hierarchical namespaces. Namespaces are delimited by slash ("/"), namespace MW (case-insensitive) is reserved for internal usage and pages within it may be edited only by administrator. It is permitted to have page with the same name as some namespace.

There are special namespaces Special, Upload, Data and Image which are not listed alongside the ordinary namespaces. They are more of a prefix than namespace.

Wiki Markup

Wiki source is divided into blocks separated by blank lines. Block can be: normal, heading, list or horizontal rule. In addition text surrounded by <pre>, </pre> (each starts on its own line) is not rendered as Wiki markup and is shown as-is inside HTML <pre>...</pre> with escaped HTML-problematic characters.

Normal Block

Normal blocks are rendered as paragraph (<p>...</p>). Block content is inline processed.

Inline processing replaces strong text, emphasized text, Main Page (internal link), internal link with overridden title, link to heading block in current page, link to heading block in specific page, link to specific version, http://php.net (external link), external link with overridden title and line
break.

Source:

Inline processing replaces '''strong text''', ''emphasized text'', [[Main Page]] (internal link),
[[Main Page|internal link with overridden title]],
[[#List_Block|link to heading block in current page]],
[[User's Guide#List_Block|link to heading block in specific page]],
[[User's Guide$1|link to specific version]],
[http://php.net] (external link),
[http://php.net external link with overridden title] and line<br>break.

Boxes

Boxes are rendered as <div>...</div>.

<box class1>This box will be <div class="class1">.</box>

<box #id1>This box will be <div id="id1">.</box>

This box will be <div class="class1">.

This box will be <div id="id1">.

Heading Block

Heading block is heading title surrounded with series of "=" which indicates heading level and is rendered as <h?>...</h?>. Heading title is inline processed. Heading level 1 should not be used, because it is used for page name in header.

Heading example:

Heading level 5

Source:

===== Heading level 5 =====

List Block

List block consists of list items. Each list item starts with series of "*" and ends before another list item or with end of block. Items may span multiple lines and are inline processed. Number of "*" indicates list item level. List block is rendered as <ul>...</ul>, list item as <li>...</li>. Nested lists are possible (list items may have arbitrary level).

List block example:

item 1
item 1
- item 2 continues on next line
  - item 3
- item 2
item 1

Source:

* item 1
* item 1
** item 2
continues on next line
*** item 3
** item 2
* item 1

Horizontal Rule Block

Horizontal rule block must consist of exactly three dashes:

---

And is rendered as:

Directives

Directives start on new line and look like:

#NAME PARAMETER...

There is no space between number sign and name. If there is space, whole line is considered comment and is left out from output.

Unless stated otherwise variable expansion (using $variable syntax) does not work for directives.

#TITLE

Directive #TITLE changes title of current page:

 #TITLE New Title

Changing title in included page does not affect original page.

#NOTOC

Directive #NOTOC disables TOC generation.

#REDIRECT

Directive #REDIRECT allows to redirect from one page to another.

 #REDIRECT [[Some Page]]

Included pages are not redirected (this may change in the future).

Flow Control (A)

 #IF value
   processed if value is not empty
 #ENDIF

 #IFEMPTY value
   processed if value is empty (= there is no value)
 #ENDIF

 #FOREACH array_variable_name index_variable_name
   processed for each value from array variable with index variable set to it
 #ENDFOR

Values in #IF and #IFEMPTY have variables expanded.

Layout Rendering Support (A)

 #PAGE
   HTML page start
 #HEADER
   start of HTML <head> section
 #META name value
   set meta value
 #ENDHEADER
  end of HTML <head> section
 #ENDPAGE
   HTML page end

Value in #META have variables expanded.

Available #META names:

title: value of HTML <title>
stylesheet: stylesheet link
javascript: javascript link

Page Attributes (A)

Directive #ATTR will set page attribute which can be later read with wiki function page_attr.

 #ATTR name value

Directives #TITLE and #REDIRECT are also projected as page attributes title and redirect.

Setting page attribute in included page does not affect original page.

Simple Forms Support (A)

Syntax is simple:

  <form METHOD URL>
    <form-field NAME TYPE PARAMETER>
    ...
  </form>

METHOD is either get or post
URL is action URL
NAME is either form field name or # for empty name
TYPE is one of text (text input line), option (selection), submit (submit button) or hidden (hidden text field)
PARAMETER for types other than option it is the value of the field, for option it is a series of values delimited by '|' - value may contain visible text delimited from real value by ':', value prefixed with '~' is selected by default

Forms are processed as inline markup.

Example with search on freshmeat.net:

  <form get http://freshmeat.net/search/>
    <form-field q text>
    <form-field # submit Freshmeat Search>
  </form>

Shows like this:

Page Inclusion (A)

Page inclusion is supported with this syntax:

{{PAGE|VARIABLE|VALUE|...}}

Example of Main Page inclusion (horizontal rules were added by this page, not by inclusion mechanism):

Welcome to miniWiki version 0.3.1, simple Wiki written in PHP which uses MySQL as its storage. It is intended for single user or small group of users (without anonymous editors) on a site with low or medium traffic.

The current version is 0.3.1 (What's new, Download).

For more information on miniWiki see User's Guide. For more information on miniWiki development see Developer's Guide.

Project is maintained by Štěpán Roh. Send your questions, requests, bugs or patches to the miniwiki-general mailing list.

This project is listed on freshmeat.net and WikiMatrix.

Special pages

Variable expansion ($variable syntax) works for all parts (including page name). If some variables are set in inclusion call, they are valid only during inclusion, not afterwards.

Wiki Functions (A)

So-called Wiki functions may be called with:

{{&FUNCTION|PARAMETER|...}}

Variable expansion ($variable syntax) works for all parts (excluding function name).

Standard set of functions:

echo: returns its concatenared arguments
set: sets variable specified by first argument to value specified by second argument, multiple variables may be specified
call: sets variable specified by first argument to result of function specified in the rest of the arguments
include: implements page inclusion
push_vars: push new empty variables on the variables stack
pop_vars: pops newest variables from the variables stack (will reset all changes done to variables since last push_vars)
action_link: returns URL to action specified in first argument, second argument may specify revision (pass head for HEAD revision), third argument may specify page name - revision and page variables are used if respective arguments are not specified
req_param: returns request parameter specified in first argument or default specified in second argument
is_eq: returns true if arguments are equal, nothing otherwise
has_action: returns whether action_link with same arguments would be sensible
is_action_permitted: returns whether action_link with same arguments would be permitted for current user
exists: returns whether page specified by first argument exists
process_time: returns number of seconds since start of current request processing
layout: same as include, but for layout pages (automatically uses proper MW/Layout namespace)
layout_data: returns page name for data layout page with given name (automatically uses proper MW/Layout namespace)
noredir_link: returns URL to view action for given page without any possible redirection
item: returns item of array variable specified by first argument with name specified by second argument
set_item: sets item of array variable specified by first argument with name specified by second argument to value specified by third argument
import: imports variables from array specified by first argument into current variables (item names are taken as variable names)
list_pages: returns array of page names from namespace specified by first argument
special_pages: returns array of all special page names
list_users: returns array of all user names
list_uploads: returns array of uploads from namespace specified by first argument
is_special: returns true if given page is special page, nothing otherwise
upload_name: returns file name of upload associated with given page name (being it data or upload page name)
list_page_namespaces: returns array of page namespaces with given namespace (if specified) as parent
list_upload_namespaces: returns array of upload namespaces with given namespace (if specified) as parent
page_attr: returns page attribute of page specified by first argument with name specified by second argument
list_extensions: returns array of enabled extensions (with items formatted as sections)
mw_version: returns miniWiki version
php_version returns PHP version

Wiki functions are inline processed.

Wiki Variables (A)

Variables are printed with:

{{$VARIABLE}}

Pre-defined variables:

user: name of current user:
main_page: name of main page: Main Page
req_action: name of current action: view
page: name of requested page: User's Guide
curpage: name of current (included) page: User's Guide
revision: revision of requested page: HEAD
storage_revision: real revision of requested page: 25
last_modified: requested page's last modification time: 2007/02/13 11:12:27
has_content: true if requested page has content, nothing otherwise: true
content_length: length of requested page's content: 19110
revision_message: requested page's revision message:
revision_author: requested page's revision author: admin
wiki_name: Wiki name set in userdefs.php: miniWiki

Wiki variables are inline processed.

Actions (A)

Available actions:

view
view_source
edit
rename
delete
history
login

On top of each page, table of contents is generated from all headings (unless switched off with directive #NOTOC).

Editor

Editor consists of toolbar on top, textarea with page source in the middle and edit message text field and "Preview" and "Update Page" buttons at the bottom.

No changes are done unless "Update Page" button is activated. Edit message is not mandatory.

Toolbar works only if JavaScript is enabled. When toolbar button is activated, some text is added at current cursor position and cursor is placed to edit spot. Buttons from left to right (refer to Wiki Markup chapter for more information):

strong text (access key "b")
emphasized text (access key "i")
heading level 1 (access key "h")
heading level 2
heading level 3
heading level 4
heading level 5
heading level 6
internal link (access key "w")
external link (access key "e")
list item (access key "l")
preformatted block (access key "p")

What access key really means depends on web browser (e.g. Mozilla Firefox exposes it as shortcut Alt-key).

Special Pages

There are several special pages (from namespace "Special") which are dynamically created and so called user pages (with prefix "User") which have mixed content.

Special/SpecialPages

Special/SpecialPages provides list of all available special pages.

Special/Pages

Special/Pages provides list of all stored pages (including user pages with content).

Special/Users

Special/Users provides list of all users where each name leads to associated user page.

If current user has enough privileges it can create new users and delete existing ones. Deleting user does not delete its user page.

Created user has disabled login until its password is changed from its user page.

User Page

User page (like User/admin) is editable page with user information. It always exists, but may have no content. Associated user may not exist.

If current user has enough privileges it can change associated user's password.

Special/Uploads

Special/Uploads provides list of all uploaded files and also a mean to upload new ones. Name of uploaded files lead to associated upload page.

Unlike other Wikis, miniWiki stores uploaded files in a same storage as normal pages.

Upload Page

Upload page (with prefix "Upload:") represents one uploaded file. Edit link allows to upload new version of a file.

Upload Data Page

Upload data page (from namespace "data") is not a real page, it returns raw content of an uploaded file.

Upload Image Page

Upload image page (with prefix "Image:") is not a real page, when linked uploaded file is shown inlined as an image.

Special/Info

Information on miniWiki and all enabled extensions (both core and non-core).

Secrets of MW Namespace (A)

MW/Layout/LAYOUT_NAME namespace must contain Header and Footer pages with UI layout for header and footer (layout name is configurable in userdefs.php)
MW/Special namespace contains special pages available through Special namespace which can be created by using miniWiki's markup as well as other special pages (e.g. for rename action, user page etc.)