ruwiki 0.9.0
Sign up to get free protection for your applications and to get access to all the features.
- data/Readme.rubygems +86 -0
- data/Readme.tarfile +65 -0
- data/bin/ruwiki +58 -0
- data/bin/ruwiki.cgi +87 -0
- data/bin/ruwiki_convert +56 -0
- data/bin/ruwiki_service.rb +82 -0
- data/bin/ruwiki_servlet +53 -0
- data/contrib/enscript-token.rb +55 -0
- data/contrib/rublog_integrator.rb +68 -0
- data/data/Default/ProjectIndex.ruwiki +49 -0
- data/data/Ruwiki/Antispam.ruwiki +65 -0
- data/data/Ruwiki/BugTracking.ruwiki +33 -0
- data/data/Ruwiki/ChangeLog.ruwiki +102 -0
- data/data/Ruwiki/Configuring_Ruwiki.ruwiki +151 -0
- data/data/Ruwiki/Extending_Ruwiki.ruwiki +317 -0
- data/data/Ruwiki/LicenseAndAuthorInfo.ruwiki +30 -0
- data/data/Ruwiki/ProjectIndex.ruwiki +84 -0
- data/data/Ruwiki/Roadmap.ruwiki +225 -0
- data/data/Ruwiki/RuwikiTemplatingLibrary.ruwiki +156 -0
- data/data/Ruwiki/RuwikiUtilities.ruwiki +157 -0
- data/data/Ruwiki/SandBox.ruwiki +9 -0
- data/data/Ruwiki/To_Do.ruwiki +51 -0
- data/data/Ruwiki/TroubleShooting.ruwiki +33 -0
- data/data/Ruwiki/WikiFeatures.ruwiki +17 -0
- data/data/Ruwiki/WikiMarkup.ruwiki +261 -0
- data/data/Tutorial/AddingPages.ruwiki +16 -0
- data/data/Tutorial/AddingProjects.ruwiki +16 -0
- data/data/Tutorial/ProjectIndex.ruwiki +11 -0
- data/data/Tutorial/SandBox.ruwiki +9 -0
- data/data/agents.banned +60 -0
- data/data/agents.readonly +321 -0
- data/data/hostip.banned +30 -0
- data/data/hostip.readonly +28 -0
- data/lib/ruwiki.rb +622 -0
- data/lib/ruwiki/auth.rb +56 -0
- data/lib/ruwiki/auth/gforge.rb +73 -0
- data/lib/ruwiki/backend.rb +318 -0
- data/lib/ruwiki/backend/flatfiles.rb +217 -0
- data/lib/ruwiki/config.rb +244 -0
- data/lib/ruwiki/exportable.rb +192 -0
- data/lib/ruwiki/handler.rb +342 -0
- data/lib/ruwiki/lang/de.rb +339 -0
- data/lib/ruwiki/lang/en.rb +334 -0
- data/lib/ruwiki/lang/es.rb +339 -0
- data/lib/ruwiki/page.rb +262 -0
- data/lib/ruwiki/servlet.rb +38 -0
- data/lib/ruwiki/template.rb +553 -0
- data/lib/ruwiki/utils.rb +24 -0
- data/lib/ruwiki/utils/command.rb +102 -0
- data/lib/ruwiki/utils/converter.rb +297 -0
- data/lib/ruwiki/utils/manager.rb +639 -0
- data/lib/ruwiki/utils/servletrunner.rb +295 -0
- data/lib/ruwiki/wiki.rb +147 -0
- data/lib/ruwiki/wiki/tokens.rb +136 -0
- data/lib/ruwiki/wiki/tokens/00default.rb +211 -0
- data/lib/ruwiki/wiki/tokens/01wikilinks.rb +166 -0
- data/lib/ruwiki/wiki/tokens/02actions.rb +63 -0
- data/lib/ruwiki/wiki/tokens/abbreviations.rb +40 -0
- data/lib/ruwiki/wiki/tokens/calendar.rb +147 -0
- data/lib/ruwiki/wiki/tokens/headings.rb +43 -0
- data/lib/ruwiki/wiki/tokens/lists.rb +112 -0
- data/lib/ruwiki/wiki/tokens/rubylists.rb +48 -0
- data/ruwiki.conf +22 -0
- data/ruwiki.pkg +0 -0
- data/templates/default/body.tmpl +19 -0
- data/templates/default/content.tmpl +7 -0
- data/templates/default/controls.tmpl +23 -0
- data/templates/default/edit.tmpl +27 -0
- data/templates/default/error.tmpl +14 -0
- data/templates/default/footer.tmpl +23 -0
- data/templates/default/ruwiki.css +297 -0
- data/templates/default/save.tmpl +8 -0
- data/templates/sidebar/body.tmpl +19 -0
- data/templates/sidebar/content.tmpl +8 -0
- data/templates/sidebar/controls.tmpl +8 -0
- data/templates/sidebar/edit.tmpl +27 -0
- data/templates/sidebar/error.tmpl +13 -0
- data/templates/sidebar/footer.tmpl +22 -0
- data/templates/sidebar/ruwiki.css +347 -0
- data/templates/sidebar/save.tmpl +10 -0
- data/templates/simple/body.tmpl +13 -0
- data/templates/simple/content.tmpl +7 -0
- data/templates/simple/controls.tmpl +8 -0
- data/templates/simple/edit.tmpl +25 -0
- data/templates/simple/error.tmpl +10 -0
- data/templates/simple/footer.tmpl +10 -0
- data/templates/simple/ruwiki.css +192 -0
- data/templates/simple/save.tmpl +8 -0
- data/tests/harness.rb +52 -0
- data/tests/tc_backend_flatfile.rb +103 -0
- data/tests/tc_bugs.rb +74 -0
- data/tests/tc_exportable.rb +64 -0
- data/tests/tc_template.rb +145 -0
- data/tests/tc_tokens.rb +335 -0
- data/tests/testall.rb +20 -0
- metadata +182 -0
@@ -0,0 +1,156 @@
|
|
1
|
+
page!content: = Ruwiki 0.9.0 Templating
|
2
|
+
Ruwiki uses a heavily modified version of the \RDoc
|
3
|
+
“cheap-n-cheerful” HTML page template system. This a
|
4
|
+
line-oriented, text-based templating system.
|
5
|
+
|
6
|
+
== Templates
|
7
|
+
Templates in the templating system are essentially plain strings with
|
8
|
+
particular references to templating keys or an include directive.
|
9
|
+
|
10
|
+
The template interacts with value and message hashes provided by
|
11
|
+
Ruwiki. The keys known to the templates expected by Ruwiki are
|
12
|
+
detailed in Extending_Ruwiki. Nested key references are found from the
|
13
|
+
inside-out. That is, the closest resolving key to the current level is
|
14
|
+
found, not the furthest resolving key.
|
15
|
+
|
16
|
+
=== Including Other Templates
|
17
|
+
Templates may include other templates to any arbitrary level by using
|
18
|
+
the <tt>!INCLUDE!</tt> directive. When the \TemplatePage is created,
|
19
|
+
an array of template strings are provided; these will be used to
|
20
|
+
satisfy <tt>!INCLUDE!</tt> directives. If there are not enough
|
21
|
+
template strings provided, <tt>!INCLUDE!</tt> won’t be
|
22
|
+
translated.
|
23
|
+
|
24
|
+
: This may change before Ruwiki reaches 1.0, so that templates are
|
25
|
+
: named instead of iterated.
|
26
|
+
|
27
|
+
=== Simple Template Keys
|
28
|
+
Strings of the format <tt>%<em>key</em>%</tt> or
|
29
|
+
<tt>%?<em>key</em>%</tt> are simple template keys. <em>key</em> is
|
30
|
+
looked up in the provided value hash and is presented as the string
|
31
|
+
value of the result. <tt>%key%</tt> template keys are mandatory; if
|
32
|
+
the key is not found in the value hash, an exception will be raised.
|
33
|
+
<tt>%?key%</tt> template keys are optional; if they key is not found
|
34
|
+
in the value hash, an empty string (“”) will be used.
|
35
|
+
|
36
|
+
=== Labels
|
37
|
+
Strings of the format <tt>#<em>key</em>#</tt> or
|
38
|
+
<tt>#?<em>key</em>#</tt> are labels. <em>key</em> is looked up in the
|
39
|
+
provided message hash as a Symbol (e.g.,
|
40
|
+
<tt><em>key</em>.intern</tt>). As with simple template keys,
|
41
|
+
<tt>#key#</tt> labels are mandatory and <tt>#?key#</tt> labels are
|
42
|
+
optional.
|
43
|
+
|
44
|
+
=== Links
|
45
|
+
Strings of the format <tt>HREF:\ref:name</tt> will become HTML links.
|
46
|
+
Both <em>ref</em> and <em>name</em> are keys to be looked up.
|
47
|
+
<em>name</em> is mandatory; an exception will be raised if it is not
|
48
|
+
found.
|
49
|
+
|
50
|
+
=== Control Structures
|
51
|
+
The templating library supports both looping and conditional control
|
52
|
+
structures in both single-line and multi-line forms. Single-line
|
53
|
+
control structures <strong>may not</strong> be nested; multi-line
|
54
|
+
control structures <strong>may</strong> be nested arbitrarily deeply.
|
55
|
+
|
56
|
+
==== Looping Control Structures
|
57
|
+
There are two forms of looping control structures.
|
58
|
+
|
59
|
+
[:key|stuff:]
|
60
|
+
|
61
|
+
START:key
|
62
|
+
... stuff ...
|
63
|
+
END:key
|
64
|
+
|
65
|
+
===== Single-Line Looping
|
66
|
+
[:key|stuff:]
|
67
|
+
|
68
|
+
The value of <em>key</em> may be <tt>nil</tt>, an integer value, a
|
69
|
+
range, or an array. When <em>key</em> represents:
|
70
|
+
# <tt>nil</tt>, the looping structure will be replaced with an empty string.
|
71
|
+
# An integer, <em>stuff</em> will be repeated <em>key</em> times. Values from 1 to <em>key</em> will be provided to the text of <em>stuff</em> to be substituted as a simple template key of the form <tt>%key%</tt>.
|
72
|
+
# A range, <em>stuff</em> will be repeated once for each successive value in the range of <em>key</em>. Each value will be provided to the text of <em>stuff</em> to be substituted as a simple template key of the form <tt>%key%</tt>.
|
73
|
+
# An array, the behaviour will differ depending on the contents of the array.
|
74
|
+
## If the array contains hashes, the behaviour is the same as a multi-line looping construct. See below for details.
|
75
|
+
## Otherwise, the template iterates through the array, providing each value to the text of <em>stuff</em> to be substituted as a simple template key of the form <tt>%key%</tt>.
|
76
|
+
|
77
|
+
As an example, if we have:
|
78
|
+
|
79
|
+
"[:b|%b% ]"
|
80
|
+
|
81
|
+
# <tt>val["b"] = 3 -> "1 2 3 "</tt>
|
82
|
+
# <tt>val["b"] = (0..2) -> "0 2 3 "</tt>
|
83
|
+
# <tt>val["b"] = ["a", "B"] -> "a B "</tt>
|
84
|
+
|
85
|
+
==== Multi-Line Looping
|
86
|
+
START:key
|
87
|
+
... stuff ....
|
88
|
+
END:key
|
89
|
+
|
90
|
+
The value of <tt>key</tt> must be an array of hashes. <tt>... stuff
|
91
|
+
...</tt> will be repeated once for each entry in the array. The hashes
|
92
|
+
will be passed as nested value hashes.
|
93
|
+
|
94
|
+
%a% [:b|%a% ]%a%
|
95
|
+
|
96
|
+
When the above template string is run with the following hash:
|
97
|
+
|
98
|
+
val["a"] = 1
|
99
|
+
val["b"] = [ { "a" => 2 }, { "a" => 3 } ]
|
100
|
+
|
101
|
+
The result is:
|
102
|
+
|
103
|
+
1 2 3 1
|
104
|
+
|
105
|
+
The behaviour is the same for multi-line blocks.
|
106
|
+
|
107
|
+
==== Conditional Block Keys
|
108
|
+
IF:key
|
109
|
+
... stuff ...
|
110
|
+
ENDIF:key
|
111
|
+
|
112
|
+
The block between <tt>\IF:key</tt> and <tt>\ENDIF:key</tt> will be included in
|
113
|
+
the output only if the corresponding key is set in the value hash.
|
114
|
+
|
115
|
+
== Example
|
116
|
+
Given the set of templates T1, T2, and T3 (shown below), here’s how we would
|
117
|
+
use the templating system.
|
118
|
+
|
119
|
+
values = { "name" => "Dave", "state" => "TX" }
|
120
|
+
t = TemplatePage.new(T1, T2, T3)
|
121
|
+
File.open(name, w) { |f| t.process(f, values) }
|
122
|
+
|
123
|
+
or:
|
124
|
+
|
125
|
+
<!-- Source -->
|
126
|
+
val1 = { "name" => "Dave", "state" => "TX" }
|
127
|
+
val2 = { "name" => "Dave" }
|
128
|
+
msgs = { }
|
129
|
+
res = ""
|
130
|
+
t.process(res, values, msgs)
|
131
|
+
|
132
|
+
<!-- T1 -->
|
133
|
+
Templates can subsitute a wide variety of values.
|
134
|
+
!INCLUDE!
|
135
|
+
|
136
|
+
<!-- T2 -->
|
137
|
+
Name: %name% !INCLUDE!
|
138
|
+
|
139
|
+
<!-- T3 -->
|
140
|
+
IF:state
|
141
|
+
State: %state%
|
142
|
+
ENDIF:state
|
143
|
+
|
144
|
+
The result will be:
|
145
|
+
|
146
|
+
Name: Dave
|
147
|
+
State: TX
|
148
|
+
|
149
|
+
Name: Dave
|
150
|
+
properties!project: Ruwiki
|
151
|
+
properties!title: RuwikiTemplatingLibrary
|
152
|
+
properties!topic: RuwikiTemplatingLibrary
|
153
|
+
properties!version: 1
|
154
|
+
ruwiki!content-version: 2
|
155
|
+
ruwiki!version: 0.9.0
|
156
|
+
properties!editable: false
|
@@ -0,0 +1,157 @@
|
|
1
|
+
page!content: = Ruwiki 0.9.0 Utilities
|
2
|
+
Ruwiki 0.9.0 provides two utilities and three sample programs for
|
3
|
+
deployment.
|
4
|
+
|
5
|
+
== Managing Ruwiki Deployments
|
6
|
+
A major change to the way that Ruwiki 0.9.0 works as compared to
|
7
|
+
versions of Ruwiki 0.8.0 or earlier is that Ruwiki 0.9.0 supports being
|
8
|
+
installed in a central location by one of the two major packaging
|
9
|
+
systems available for Ruby (\RubyGems and RPA). Managing these
|
10
|
+
deployments is accomplished with the utility appropriately enough named
|
11
|
+
<tt>ruwiki</tt>, stored in the directory of the distribution.
|
12
|
+
|
13
|
+
This utility has little value for users of the standalone release
|
14
|
+
(either of the versions packaged in tarfiles or zipfiles), but is
|
15
|
+
developed because packaging systems present a particular challenge to
|
16
|
+
Ruwiki, as simply running “ruwiki_servlet” with no
|
17
|
+
arguments will look for the data files and the template files relative
|
18
|
+
to the current directory. With \RubyGems, though, this would require
|
19
|
+
that the user specify something like:
|
20
|
+
|
21
|
+
ruwiki_servlet \
|
22
|
+
--template-path /usr/local/lib/ruby/gems/1.8/ruwiki-0.9.0/templates \
|
23
|
+
--flatfiles-data-path /usr/local/lib/ruby/gems/1.8/ruwiki-0.9.0/data
|
24
|
+
|
25
|
+
This is not the preferred option because Wiki installations may be
|
26
|
+
private and the /usr/local directory is a system-wide shared
|
27
|
+
directory. Additionally, since Ruwiki works as a CGI, the system
|
28
|
+
shared data and template paths will not be generally accessible (and
|
29
|
+
should not be world-writeable!) to CGI executables.
|
30
|
+
|
31
|
+
This utility also encapsulates Win32 service management through
|
32
|
+
Win32::Service for the \WEBrick servlet runner.
|
33
|
+
|
34
|
+
=== <tt>ruwiki <command> [<em>parameters</em>]</tt>
|
35
|
+
The <tt>ruwiki</tt> utility will recognise four different commands on
|
36
|
+
all platforms and a fourth command on Windows. These commands are:
|
37
|
+
|
38
|
+
; help : Displays general help or command-specific help.
|
39
|
+
; install : Installs the default deployment package.
|
40
|
+
; package : Packages a Ruwiki installation.
|
41
|
+
; unpackage : Unpackages a Ruwiki installation.
|
42
|
+
; service : Manages a Win32::Service for Ruwiki.
|
43
|
+
|
44
|
+
==== <tt>ruwiki help commands</tt>
|
45
|
+
The list of known commands can be displayed by providing this command.
|
46
|
+
|
47
|
+
% ruwiki help commands
|
48
|
+
==== <tt>ruwiki help <command></tt>
|
49
|
+
The help for the named command (one of install, package, unpackage, or
|
50
|
+
service) will be displayed upon providing this command to the ruwiki
|
51
|
+
utility.
|
52
|
+
|
53
|
+
% ruwiki help install
|
54
|
+
==== <tt>ruwiki install [<em>OPTIONS</em>] [<em>--to DEST</em>]
|
55
|
+
Creates a new Ruwiki instance in the current directory or the directory
|
56
|
+
specified by the <tt>--to</tt> option. By default, the data, template,
|
57
|
+
and a default configuration file are installed to the destination
|
58
|
+
directory. OPTIONS may be one of the following:
|
59
|
+
|
60
|
+
; servlet : Installs the Ruwiki WEBrick servlet stub.
|
61
|
+
; service : Installs the Ruwiki Win32::Service stub.
|
62
|
+
; cgi : Installs the Ruwiki CGI script model.
|
63
|
+
; data : Default; installs the Ruwiki default data, templates, and configuraiton file.
|
64
|
+
|
65
|
+
Installation option names can be disabled with a dash (‘-’)
|
66
|
+
or the word ‘no’, making ‘-data’ and
|
67
|
+
‘nodata’ functionally equivalent.
|
68
|
+
|
69
|
+
% ruwiki install cgi data
|
70
|
+
==== <tt>ruwiki package [<em>SOURCE</em>] [<em>--output PACKAGE</em>|<em>-o PACKAGE</em>] [<em>--replace</em>]</tt>
|
71
|
+
Packages the Ruwiki files (data, templates, and executables) from the
|
72
|
+
specified source or the current directory into the specified output
|
73
|
+
package (or “./ruwiki.pkg”). If the SOURCE is a ruwiki
|
74
|
+
configuration file (e.g., “ruwiki.conf”), then that will be
|
75
|
+
used to determine the location and name of the data and template
|
76
|
+
directories.
|
77
|
+
|
78
|
+
Specify <tt>--replace</tt> to replace the existing output package. If
|
79
|
+
an output package is specified that already exists, then <tt>ruwiki
|
80
|
+
package</tt> will refuse to output to the file unless
|
81
|
+
<tt>--replace</tt> is specified. If an output package is not specified
|
82
|
+
and <tt>--replace</tt> is not specified, then an incremental package
|
83
|
+
will be generated (e.g., “./ruwiki-1.pkg”).
|
84
|
+
|
85
|
+
: NOTE: The packaging process will normalize the data and templates
|
86
|
+
: directory names to be relative to the unpacking directory. They will
|
87
|
+
: NEVER be absolute paths.
|
88
|
+
|
89
|
+
% ruwiki package
|
90
|
+
==== <tt>ruwiki unpackage [<em>SOURCE</em>] [<em>--output DIRECTORY</em>|<em>-o DIRECTORY</em>]</tt>
|
91
|
+
Unpackages the provided Ruwiki package (default "./%1$s") into the
|
92
|
+
specified directory (default ".").
|
93
|
+
|
94
|
+
% ruwiki unpackage
|
95
|
+
==== <tt>ruwiki service <command> <NAME> [<em>command-options</em>]</tt>
|
96
|
+
Manages a Ruwiki WEBrick servlet as a Win32 service (with the
|
97
|
+
assistance of
|
98
|
+
[http://raa.ruby-lang.org/list.rhtml?name=win32-service win32-service]).
|
99
|
+
This works in ways similar to a daemon on Unix. The sub-commands
|
100
|
+
available to <tt>ruwiki service</tt> are:
|
101
|
+
===== <tt>ruwiki service install NAME [DESCRIPTION] [options]</tt>
|
102
|
+
Installs the Ruwiki WEBrick servlet as the named Win32 service.
|
103
|
+
<tt>install</tt> accepts an optional description (all non-options will
|
104
|
+
be included in the description). The options for <tt>install</tt> are:
|
105
|
+
; --rubybin RUBYPATH : The path to the Ruby binary.
|
106
|
+
; --exec SERVICEPATH : The path to the service executable.
|
107
|
+
; --home PATHTOHOME : The path to the home directory.
|
108
|
+
===== <tt>ruwiki service start NAME</tt>
|
109
|
+
Starts the named Ruwiki service.
|
110
|
+
===== <tt>ruwiki service stop NAME</tt>
|
111
|
+
Stops the named Ruwiki service.
|
112
|
+
===== <tt>ruwiki service delete NAME</tt>
|
113
|
+
Deletes the named Ruwiki service.
|
114
|
+
|
115
|
+
: NOTE: This command can probably be used to manage other Win32
|
116
|
+
: services that respond to the appropriate commands.
|
117
|
+
|
118
|
+
== Upgrading and Converting: ruwiki_convert
|
119
|
+
: This section was formerly a separate entry in the Wiki entitled
|
120
|
+
: “Upgrading and Converting”.
|
121
|
+
|
122
|
+
The flatfile backend format in Ruwiki 0.9.0 is not compatible with that
|
123
|
+
of versions of Ruwiki earlier than 0.8.0. There are a number of
|
124
|
+
reasons for this, but because of this and that there are now three
|
125
|
+
different backend formats, Ruwiki now has a converter utility between
|
126
|
+
backends.
|
127
|
+
|
128
|
+
There are two other incompatibilities of note:
|
129
|
+
# Ruwiki now defaults to “ruwiki” as an extension (e.g., \ProjectIndex.ruwiki) to the storage files. This is, of course, is something that can be modified with a configuration option, but you may find it desirable to rename your files to match this naming convention.
|
130
|
+
# The rdiff format is incompatible. It is recommended that you remove all .rdiff files from your data directory before using Ruwiki.
|
131
|
+
|
132
|
+
=== ruwiki_convert [options] <directory>+
|
133
|
+
The converter utility will work on all files in a directory and its
|
134
|
+
subdirectories.
|
135
|
+
|
136
|
+
When a file is encountered, it will be examined to be a known form of a
|
137
|
+
Ruwiki backend (marshal, yaml, flatfiles, or "old" flatfiles). If the
|
138
|
+
file is not one of these forms, then the file is skipped. Otherwise, it
|
139
|
+
is converted to the specified format. By default, the converted files
|
140
|
+
will be backed up.
|
141
|
+
|
142
|
+
==== ruwiki_convert Options
|
143
|
+
; --format=FORMAT : Converts encountered files (regardless of the current format), to the specified format. Default is yaml. Allowed formats are: yaml marshal flatfiles
|
144
|
+
; --[no-]backup : Create backups of upgraded files. Default is --backup.
|
145
|
+
; --backup-extension=EXTENSION : Specify the backup extension. Default is "~", which is appended to the data filename.
|
146
|
+
; --extension=EXTENSION : Specifies the extension of Ruwiki data files. The default is .ruwiki
|
147
|
+
; --no-extension : Indicates that the Ruwiki data files have no extension.
|
148
|
+
; --quiet : Runs quietly. Default is to run with normal messages.
|
149
|
+
; --verbose : Runs with full messages. Default is to run with normal messages.
|
150
|
+
; --help : Shows this text.
|
151
|
+
properties!project: Ruwiki
|
152
|
+
properties!title: RuwikiUtilities
|
153
|
+
properties!topic: RuwikiUtilities
|
154
|
+
properties!version: 1
|
155
|
+
ruwiki!content-version: 2
|
156
|
+
ruwiki!version: 0.9.0
|
157
|
+
properties!editable: false
|
@@ -0,0 +1,9 @@
|
|
1
|
+
page!content: This page is intended for users to play with freely to practice
|
2
|
+
their \WikiFormatting.
|
3
|
+
properties!project: Ruwiki
|
4
|
+
properties!title: SandBox
|
5
|
+
properties!topic: SandBox
|
6
|
+
properties!version: 1
|
7
|
+
ruwiki!content-version: 2
|
8
|
+
ruwiki!version: 0.9.0
|
9
|
+
properties!editable: false
|
@@ -0,0 +1,51 @@
|
|
1
|
+
page!content: = Ruwiki 0.9.0 To Do Tracking
|
2
|
+
Completed to-do items can be found in the ChangeLog. Bugs in Ruwiki
|
3
|
+
are tracked in BugTracking.
|
4
|
+
|
5
|
+
== Well-Defined To Do Items
|
6
|
+
=== Ruwiki 0.10.0
|
7
|
+
; Versioning : complete the change history interface. Change history is currently stored in a file <em>topic[.extension]</em>.rdiff. There is no way to display the change history at this point.
|
8
|
+
; Action objects : Actions will be generalised to pull the processing out of the main ruwiki.rb inasmuch as is possible.
|
9
|
+
; Function tokens : generalize the %<function-name>[(<args>)] calling method so that function tokens can be created without having to create a custom regular expression.
|
10
|
+
; Search work : There is further search work required. The current mechanism is effective, but inefficient, as it must load and convert each file in a project to a page and then search selectively within that page. The search mechanism must be improved.
|
11
|
+
; Frozen content : make it so that frozen content can be provided on a per-page or Wiki basis. Will provide both headers and footers. <strong>Note:</strong> Ruwiki 0.9.0 will only provide the ability to present the information, not create or modify it.
|
12
|
+
; Blacklisting : Allow the specification of an allow/deny list for \IPs or hostnames, aimed at blocking known spammers. Entries in this list can be permanent or temporary (e.g., “* DENY”, “spammer.com DENY UNTIL 20040723”, “139.244.33.25 ALLOW”).
|
13
|
+
; External URL redirection : Add whitelisting of known good external URIs.
|
14
|
+
; \GlobalRecentChanges : Recent changes for all projects.
|
15
|
+
;
|
16
|
+
=== Ruwiki 0.11.0
|
17
|
+
; Authentication : complete authentication to provide for a standard Ruwiki authentication mechanism, not just an external API. This may require changes to the existing external API. Allows for user creation and authentication. Authenticate users bypass blacklist checking; thus, if “msn.com” is blocked, joe.blog@msn.com could still authenticate with Ruwiki and edit the pages.
|
18
|
+
; Topic renaming : add the ability to rename a topic within a project. Topic change history should be maintained.
|
19
|
+
; Topic moving : add the ability to move and/or rename a topic between projects. Topic change history should be maintained.
|
20
|
+
; Complete documentation : Complete the documentation of Ruwiki.
|
21
|
+
; Antispam : Allow the on-line editing of antispam lists to authenticated and authorised users.
|
22
|
+
=== Ruwiki 1.0.0
|
23
|
+
; RSS Feed : Ruwiki must be able to offer \RecentChanges and \GlobalRecentChanges as RSS feeds. This may not be ideal with the current \RecentChanges format. It may be easier to move to a two-stage \RecentChanges format.
|
24
|
+
; Static content : Allow the creation and editing of static content.
|
25
|
+
; Frozen pages : provide the ability to freeze content in place; the page is no longer “wiki” editable and is effectively a plain HTML page.
|
26
|
+
; Page properties : provide the ability to generally edit the properties of a given page.
|
27
|
+
|
28
|
+
== General Future To Do Items
|
29
|
+
; E-mail gateway : accept topic appends via e-mail.
|
30
|
+
; alternative backends : access other wiki data storage, or other formats, e.g. e-mail boxes in mh or mbox formats
|
31
|
+
; bug tracker backend : with alternate markup
|
32
|
+
; add setup and user config methods : for backend plugin classes, then we can use them with an interactive or gui tool frontend to setup data storage backends. The user might have to run as root or other user with database create permissions.
|
33
|
+
; add id="" to various markup elements (make id specific to topic) : Later we can allow users to tweak a page using uploaded css fragments which might get appended onto the standard css contents.
|
34
|
+
; ruby action : upload a ruby code fragment to add a smart “action” to that wiki page. Need some sort of security + approval system to handle this safely.
|
35
|
+
; Preview button : add a preview button to the save page.
|
36
|
+
; Alternative templating systems : not as high priority now that there’s a real templating system in place.
|
37
|
+
; Alternative markup systems : potentially allow \RedCloth (Textile) and/or \BlueCloth (Markdown) to be processed for a page. This could be implemented as a %function.
|
38
|
+
; Project/topic security : allow certain projects to be restricted/authenticated for read/write based on user.
|
39
|
+
; Track last <em>n</em> links/topics : ?
|
40
|
+
; Write a markup debugger : ?
|
41
|
+
; Validate topic formatting from cgi : ?
|
42
|
+
; Validate project from cgi : ?
|
43
|
+
; Project-based backend : Allow different projects to have different backends.
|
44
|
+
; Arbitrary-depth project namespace support : Foo::Bar::\BazPage.
|
45
|
+
properties!project: Ruwiki
|
46
|
+
properties!title: To_Do
|
47
|
+
properties!topic: To_Do
|
48
|
+
properties!version: 1
|
49
|
+
ruwiki!content-version: 2
|
50
|
+
ruwiki!version: 0.9.0
|
51
|
+
properties!editable: false
|
@@ -0,0 +1,33 @@
|
|
1
|
+
page!content: = Ruwiki 0.9.0
|
2
|
+
= Ruwiki 0.9.0 Troubleshooting Tips
|
3
|
+
Following are some tips contributed by users of Ruwiki. Remember:
|
4
|
+
Ruwiki currently requires Ruby version 1.8; the YAML backend requires
|
5
|
+
Ruby version 1.8.2 or the latest CVS of Ruby 1.9.
|
6
|
+
|
7
|
+
== No such file or directory
|
8
|
+
(Unix systems only.) If you get something like:
|
9
|
+
|
10
|
+
% ./ruwiki_servlet
|
11
|
+
: no such file or directory
|
12
|
+
|
13
|
+
run the following in the Ruwiki directory:
|
14
|
+
|
15
|
+
% find . | xargs dos2unix
|
16
|
+
|
17
|
+
The developers of Ruwiki do what they can to ensure that Ruwiki is
|
18
|
+
distributed in a way that works well for both Unix and Windows
|
19
|
+
systems, but this will occasionally cause problems.
|
20
|
+
|
21
|
+
== undefined method
|
22
|
+
% ./ruwiki_servlet
|
23
|
+
./ruwiki_servlet:64: undefined method `[]=' for nil (NameError)
|
24
|
+
|
25
|
+
This may appear if you are running Ruby 1.6. Ruwiki requires Ruby 1.8
|
26
|
+
or higher; certain features require Ruby 1.8.2 preview 3 or better.
|
27
|
+
properties!project: Ruwiki
|
28
|
+
properties!title: ProjectIndex
|
29
|
+
properties!topic: ProjectIndex
|
30
|
+
properties!version: 1
|
31
|
+
ruwiki!content-version: 2
|
32
|
+
ruwiki!version: 0.9.0
|
33
|
+
properties!editable: false
|
@@ -0,0 +1,17 @@
|
|
1
|
+
page!content: Ruwiki is a [http://www.ruby-lang.org Ruby]-based wiki. It is
|
2
|
+
ideal for personal or small team use.
|
3
|
+
|
4
|
+
Ruwiki:
|
5
|
+
* Uses the [http://www.ruby-lang.org Ruby] language.
|
6
|
+
* Runs quickly and easily as a CGI or \WEBrick servlet.
|
7
|
+
* Uses a simple templating system and CSS for presentation.
|
8
|
+
* Has flatfile storage with simple versioning.
|
9
|
+
* Offers project namespaces. Different projects can have the same topic names and not collide. Thus, \Default::ReadMe and \Project::ReadMe are two different pages.
|
10
|
+
* Offers a calendar for date-based collaborative editing.
|
11
|
+
properties!project: Ruwiki
|
12
|
+
properties!title: WikiFeatures
|
13
|
+
properties!topic: WikiFeatures
|
14
|
+
properties!version: 1
|
15
|
+
ruwiki!content-version: 2
|
16
|
+
ruwiki!version: 0.9.0
|
17
|
+
properties!editable: false
|
@@ -0,0 +1,261 @@
|
|
1
|
+
page!content: = Ruwiki Markup
|
2
|
+
A [http://c2.com/cgi/wiki Wiki] obeys certain formatting rules to make
|
3
|
+
it easy to format text without needing to know HTML. This Wiki obeys
|
4
|
+
the following rules by default. Because Ruwiki is extensible, there may
|
5
|
+
be additional formatting rules. These rules are those rules that apply
|
6
|
+
as of Ruwiki 0.9.0.
|
7
|
+
|
8
|
+
== \WikiWords, \WikiProjects, Calendars, and External Resources
|
9
|
+
While reading stuff on this Wiki, you will see some words mashed
|
10
|
+
together with capitalisation (like \WikiWords). While this may seem odd
|
11
|
+
at first, this feature allows internal links to be created across the
|
12
|
+
Wiki.
|
13
|
+
|
14
|
+
There are several allowable forms for \WikiWords.
|
15
|
+
# Two or more words concatenated directly. Each word must begin with a capital letter and be followed by zero or more lowercase letters. Thus, \FooBar, \CPlusPlus, and \AbC are all valid \WikiWords, but ABC is not.
|
16
|
+
# Two or more words concatenated with underscores. The first word must begin with a capital letter. This makes \Foo_Bar, \C_Plus_Plus, and \A_b_C valid \WikiWords. These \WikiWords will be displayed with spaces instead of underscores. \C_Plus_Plus will be displayed as “C Plus Plus”.
|
17
|
+
# One or more words contained in double square brackets. This the form supported by [http://wikipedia.com/ Wikipedia], and looks like \[[A Wiki Phrase]]. These links will be displayed exactly as entered between the brackets.
|
18
|
+
# One or more words contained in double square brackets with display text separated by a vertical bar. These \WikiWords look like \[[A Wiki Phrase|but show this text]]. The link will be to the page “A Wiki Phrase” and “but show this text” will be the hyperlink.
|
19
|
+
|
20
|
+
If a \WikiWord is found that does not have a page defining the
|
21
|
+
\WikiWord, then the word will be shown with a hyperlink question mark
|
22
|
+
following it, allowing the \WikiWord to be created.
|
23
|
+
|
24
|
+
=== \WikiProjects
|
25
|
+
This Wiki supports “projects.” Within each project, a given
|
26
|
+
\WikiWord is unique. Thus, if you have a Default project and a Ruwiki
|
27
|
+
project, you can have two pages called \ReadMe. Any given \WikiWord
|
28
|
+
refers only to topics within its project. That is, if I have \WikiWord
|
29
|
+
in the \ReadMe topic of the Default project, it will refer to the
|
30
|
+
\WikiWord topic of the Default project. (Another term for this
|
31
|
+
capability is “namespaces.”)
|
32
|
+
|
33
|
+
A cross-project link is composed of the project’s name, two colons
|
34
|
+
(::), and the \WikiWord desired. Thus, from \Default::ReadMe, I can
|
35
|
+
have \Ruwiki::ReadMe as a link. The project index can be referred to
|
36
|
+
with \::Project. This is the same as doing \Project::ProjectIndex.
|
37
|
+
Thus, \::Ruwiki becomes ::Ruwiki, which is the same as
|
38
|
+
\Ruwiki::ProjectIndex (Ruwiki::ProjectIndex).
|
39
|
+
|
40
|
+
=== Project Lists and Topic Lists
|
41
|
+
The list of known projects may be listed with the %projects() token;
|
42
|
+
the list of known topics for the current project may be listed with the
|
43
|
+
%topics() link. An arbitrary project may be provided to the %topics()
|
44
|
+
token, as in %topics(Default).
|
45
|
+
|
46
|
+
%topics(Default)
|
47
|
+
|
48
|
+
%projects()
|
49
|
+
|
50
|
+
=== Calendars
|
51
|
+
Ruwiki supports a miniature calendar. Future versions of Ruwiki will
|
52
|
+
allow for calendar aggregation. Using the %calendar function, a
|
53
|
+
calendar section will be generated:
|
54
|
+
|
55
|
+
%calendar(<year>, <month>[, <project>])
|
56
|
+
%calendar(today[, <project>])
|
57
|
+
|
58
|
+
%calendar accepts either the English word “today” (displaying the
|
59
|
+
calendar for the current month and year) or a specific month and year
|
60
|
+
for display. A calendar for the specified month will be generated
|
61
|
+
where each date in the month is treated as a \WikiWord (as are the
|
62
|
+
links to the current month, the previous month, and the next month)
|
63
|
+
ready for display or editing. As with all other \WikiWord links in
|
64
|
+
Ruwiki, a project may be specified in %calendar, making
|
65
|
+
“%calendar(today, Ruwiki)” different from “%calendar(today, Default)”.
|
66
|
+
|
67
|
+
%calendar(today)
|
68
|
+
%calendar(1999, 08, Default)
|
69
|
+
|
70
|
+
=== External Resources
|
71
|
+
Ruwiki behaves intelligently about resources external to the Wiki
|
72
|
+
itself.
|
73
|
+
|
74
|
+
==== External Links
|
75
|
+
\URLs to external resources are automatically detected for web
|
76
|
+
addresses, FTP addresses, newsgroups, and email links. They are
|
77
|
+
automatically converted to clickable \URLs. Be aware that some things
|
78
|
+
that look like URL schemas may be make clickable but are not really
|
79
|
+
\URLs.
|
80
|
+
|
81
|
+
* \http://www.ruby-lang.org becomes http://www.ruby-lang.org
|
82
|
+
|
83
|
+
\URLs may be named with the [url name] syntax. If the name is omitted,
|
84
|
+
the URL will be numbered. Numbering is contained to within the page.
|
85
|
+
|
86
|
+
* \[http://www.rubygarden.org RubyGarden] becomes [http://www.rubygarden.org RubyGarden].
|
87
|
+
* \[http://www.halostatue.ca] and \[http://www.halostatue.ca/ruby] become [http://www.halostatue.ca] and [http://www.halostatue.ca/ruby].
|
88
|
+
|
89
|
+
==== Images
|
90
|
+
: <strong>Changed in Ruwiki 0.8.0!</strong>
|
91
|
+
|
92
|
+
In preparation for the anti-wiki-spam features of Ruwiki 0.9.0, it has
|
93
|
+
been necessary to remove the ability for \URLs to be converted into
|
94
|
+
inline images automatically. Inline images are now created with the
|
95
|
+
image markup format, generally of the format \[image:URI options]. The
|
96
|
+
<em>options</em> format is generally the same format as an HTML
|
97
|
+
attribute (<em>name="value"</em>; the quotes are optional for
|
98
|
+
single-word option values) and any valid HTML attribute is also a
|
99
|
+
valid <em>option</em>. There is one special <em>option</em>,
|
100
|
+
<tt>numbered</tt>. This value, if set to any other value than “false”,
|
101
|
+
will set the <tt>title</tt> of the image to a numbered link.
|
102
|
+
|
103
|
+
If the <tt>title</tt> attribute is not specified, it will be set from
|
104
|
+
the <tt>alt</tt> attribute (if specified) or the image’s URL. If the
|
105
|
+
<tt>alt</tt> attribute is not specified, it will be set from the
|
106
|
+
<tt>title</tt> attribute.
|
107
|
+
|
108
|
+
* \[image:http://www.halostatue.ca/graphics/maple_leaf.gif] [image:http://www.halostatue.ca/graphics/maple_leaf.gif]
|
109
|
+
* \[image:http://www.halostatue.ca/graphics/maple_leaf.gif title="Maple Leaf"] [image:http://www.halostatue.ca/graphics/maple_leaf.gif title="Maple Leaf"]
|
110
|
+
* \[image:http://www.halostatue.ca/graphics/maple_leaf.gif numbered=true] [image:http://www.halostatue.ca/graphics/maple_leaf.gif numbered=true]
|
111
|
+
* \[image:http://www.halostatue.ca/graphics/maple_leaf.gif style="border: 1px solid black;"] [image:http://www.halostatue.ca/graphics/maple_leaf.gif style="border: 1px solid black;"]
|
112
|
+
|
113
|
+
==== Ruby Mailing Lists
|
114
|
+
If a Ruby mailing list message tag is provided, it will be converted appropriately.
|
115
|
+
|
116
|
+
* \[ruby-talk:12345] will become [ruby-talk:12345]
|
117
|
+
* \[ruby-core:12345] will become [ruby-core:12345]
|
118
|
+
* \[ruby-doc:12345] will become [ruby-doc:12345]
|
119
|
+
|
120
|
+
== Headings and Lists
|
121
|
+
=== Headings
|
122
|
+
Use equals signs (=) for headings. Up to six equals signs can be used
|
123
|
+
for HTML headings 1 - 6.
|
124
|
+
|
125
|
+
\===== Heading five<br />
|
126
|
+
\====== Heading six
|
127
|
+
===== Heading five
|
128
|
+
====== Heading six
|
129
|
+
|
130
|
+
=== Lists
|
131
|
+
==== Bulleted Lists
|
132
|
+
Use asterisks (*) to create bulleted lists. More asterisks means more
|
133
|
+
levels.
|
134
|
+
|
135
|
+
\* level 1<br />
|
136
|
+
\** level 2<br />
|
137
|
+
\*** level 3
|
138
|
+
|
139
|
+
* level 1
|
140
|
+
** level 2
|
141
|
+
*** level 3
|
142
|
+
|
143
|
+
==== Numbered Lists
|
144
|
+
Use hash marks (#) for numbered lists. More hash marks means deeper
|
145
|
+
levels.
|
146
|
+
|
147
|
+
\# level 1<br />
|
148
|
+
\## level 2<br />
|
149
|
+
\### level 3<br />
|
150
|
+
\### level 3.2<br />
|
151
|
+
\## level 2.2<br />
|
152
|
+
\# level 1.2
|
153
|
+
|
154
|
+
# level 1
|
155
|
+
## level 2
|
156
|
+
### level 3
|
157
|
+
### level 3.2
|
158
|
+
## level 2.2
|
159
|
+
# level 1.2
|
160
|
+
|
161
|
+
==== Definition Lists
|
162
|
+
Definitions can be created similar to other lists. Unlike “standard”
|
163
|
+
lists, though, definition lists have both the term and the definition.
|
164
|
+
They are specified like so. As with other lists, repeating the first
|
165
|
+
item (;) will increase the indentation level. The browser may not
|
166
|
+
respect this.
|
167
|
+
|
168
|
+
\; term : definition<br />
|
169
|
+
\;; term2 : definition<br />
|
170
|
+
\;;; term3 : definition
|
171
|
+
|
172
|
+
; term : definition
|
173
|
+
;; term2 : definition
|
174
|
+
;;; term3 : definition
|
175
|
+
== Paragraph Formatting
|
176
|
+
=== Rules
|
177
|
+
Four or more dashes ("----") on a line by itself makes a horizontal
|
178
|
+
rule, like so:
|
179
|
+
|
180
|
+
\----
|
181
|
+
----
|
182
|
+
=== Paragraphs
|
183
|
+
A blank line (it may have whitespace on it) marks a new paragraph. All
|
184
|
+
other lines are joined together (excepting headers, lists, and rules).
|
185
|
+
|
186
|
+
This line is a new paragraph.
|
187
|
+
|
188
|
+
=== Block Indent Paragraphs
|
189
|
+
Paragraphs can be indented by beginning the paragraph with one or more
|
190
|
+
colons (:).
|
191
|
+
|
192
|
+
\: Indent Level 1<br />
|
193
|
+
\:: Indent Level 2<br />
|
194
|
+
\::: Indent Level 3
|
195
|
+
|
196
|
+
: Indent Level 1
|
197
|
+
:: Indent Level 2
|
198
|
+
::: Indent Level 3
|
199
|
+
|
200
|
+
Paragraphs may be indented as “cites” by using one or more
|
201
|
+
greater-than signs (>) at the beginning of the line.
|
202
|
+
|
203
|
+
\> Indent Level 1<br />
|
204
|
+
\>> Indent Level 2<br />
|
205
|
+
\>>> Indent Level 3
|
206
|
+
|
207
|
+
> Indent Level 1
|
208
|
+
>> Indent Level 2
|
209
|
+
>>> Indent Level 3
|
210
|
+
|
211
|
+
=== Code
|
212
|
+
Text that is indented will be presented as formatted in a monospaced
|
213
|
+
font. The only change is to escape HTML entities < (&lt;), >
|
214
|
+
(&gt;), and & (&amp;).
|
215
|
+
|
216
|
+
def replace
|
217
|
+
content = @match[1]
|
218
|
+
%Q{<pre>#{content}</pre>}
|
219
|
+
end
|
220
|
+
|
221
|
+
== Miscellaneous Formatting
|
222
|
+
=== HTML
|
223
|
+
The Ruwiki engine currently passes through HTML without changes. Thus,
|
224
|
+
<strong>strong</strong> would be shown as
|
225
|
+
<strong>strong</strong>. <strong><em>Note:</em></strong> This
|
226
|
+
capability could be very dangerous as it could expose the Wiki to
|
227
|
+
cross-site scripting (XSS) vulnerabilities. This will be remedied
|
228
|
+
prior to the 1.0 release of Ruwiki.
|
229
|
+
|
230
|
+
=== Abbreviations
|
231
|
+
Certain abbreviations may be known to the Wiki. While there is not yet
|
232
|
+
any way for a user to query what abbreviations are known, if the
|
233
|
+
abbreviations are told to the users, they may be used. Abbreviations
|
234
|
+
are presented with @{key}, where <em>key</em> is the abbreviation
|
235
|
+
desired. This Wiki, for example, knows that \@{matz} means “@{matz}”.
|
236
|
+
The special form \@{} will produce the current list of known
|
237
|
+
abbreviations. Unknown abbreviations will simply be put back into the
|
238
|
+
data stream unchanged. Thus, \@{unknownkey} results in @{unknownkey}.
|
239
|
+
|
240
|
+
==== Known Abbreviations
|
241
|
+
@{}
|
242
|
+
|
243
|
+
=== Preventing Formatting
|
244
|
+
If you wish to prevent a word or sequence from being interpreted, put
|
245
|
+
a backslash (\) in front of it. This works on all formatting options
|
246
|
+
except paragraph positioning. Thus, if I want to prevent a \WikiWord
|
247
|
+
from being turned into a hyperlink, I need to backslash it:
|
248
|
+
\\WikiWord.
|
249
|
+
|
250
|
+
=== Other Possible Considerations
|
251
|
+
I’m looking at adding styles similar to what is shown on the Wiki
|
252
|
+
below.
|
253
|
+
|
254
|
+
* http://www.pmichaud.com/wiki/PmWiki/WikiStyles
|
255
|
+
properties!project: Ruwiki
|
256
|
+
properties!title: WikiMarkup
|
257
|
+
properties!topic: WikiMarkup
|
258
|
+
properties!version: 1
|
259
|
+
ruwiki!content-version: 2
|
260
|
+
ruwiki!version: 0.9.0
|
261
|
+
properties!editable: false
|