← Back to branch summary

~ubuntu-branches/ubuntu/natty/moin/natty-updates

« back to all changes in this revision

Viewing changes to wiki/underlay/pages/HelpOnLinking/revisions/00000001

  • Committer: Bazaar Package Importer
  • Author(s): Jonas Smedegaard
  • Date: 2008-06-22 21:17:13 UTC
  • mfrom: (0.9.1 upstream)
  • Revision ID: james.westby@ubuntu.com-20080622211713-fpo2zrq3s5dfecxg
Tags: 1.7.0-3
Simplify /etc/moin/wikilist format: "USER URL" (drop unneeded middle
CONFIG_DIR that was wrongly advertised as DATA_DIR).  Make
moin-mass-migrate handle both formats and warn about deprecation of
the old one.

Show diffs side-by-side

added added

removed removed

Lines of Context:
wiki/underlay/pages/HelpOnLinking/revisions/00000001
1
 
## Please edit system and help pages ONLY in the moinmaster wiki! For more
2
 
## information, please see MoinMaster:MoinPagesEditorGroup.
 
1
## Please edit system and help pages ONLY in the master wiki!
 
2
## For more information, please see MoinMoin:MoinDev/Translation.
3
3
##master-page:Unknown-Page
4
4
##master-date:Unknown-Date
5
 
#acl MoinPagesEditorGroup:read,write,delete,revert All:read
 
5
#acl -All:write Default
6
6
#format wiki
7
7
#language en
 
8
 
 
9
= Linking Rules =
 
10
 * Targets can be:
 
11
  * Local Pages:
 
12
   * either absolute: '''`a page name`''' or '''`main page/sub page`'''
 
13
   * or relative: '''`/some sub page`''' or '''`../some sister page`'''
 
14
  * Interwiki Pages: '''`OtherWiki:a pagename there`'''
 
15
  * URLs: '''`http://server/path`'''
 
16
  * Pages and URLs may include an anchor ('''`...#anchorname`''').
 
17
 * Use '''`[[target]]`''' if you want to ''link'' to some target object.
 
18
 * Use '''`{{target}}`''' if you want to ''transclude'' (embed/include/show) some target object (often an image).
 
19
 * Use '''`target|text`''' instead of just '''`target`''' to make it use the given text (e.g. as link text for links or as alt text for images).
 
20
 * Use '''`target|text|params`''' instead of just '''`target`''' to give additional params.
 
21
 
 
22
 * Use '''`target|{{imagetarget}}`''' if you want to show an image instead of a text.
 
23
 
 
24
URLs, interwiki pages, email addresses and CamelCase pagenames are recognized as targets even without using brackets.
 
25
 
8
26
= Quick Reference =
9
 
||'''Hyperlink'''            ||'''Syntax'''                       ||'''Comment'''                   ||
10
 
||internal link              ||`WikiName`                         ||Camel``Case page name           ||
11
 
||internal free link         ||`["Page"]` or `["free link"]`      ||configurable function           ||
12
 
||internal link to sub page  ||`/SubPage` or `["/Sub page"]`      ||relative to upper page          ||
13
 
||external link              ||`http://example.net`               ||                                ||
14
 
||named internal link        ||`[:HelpContents:Contents of the Help]`||                             ||
15
 
||named external link        ||`[http://example.net example site]`||                                ||
16
 
||local graphics (attachment)||`attachment:graphics.png`          ||images will be displayed inline ||
17
 
||external graphics          ||`http://example.net/image.png`     ||shows target image              ||
18
 
||external and internal graphics || `[[ImageLink(image,target[,width=width[,height=height]][,alt=alttag])]]` ||makes a link that displays an image and links to either an URL or a wiki page. ||
19
 
||border of internal link    ||{{{WikiName``s}}}                  ||2 backticks                     ||
20
 
||avoid an internal link     ||`!WikiName`                        ||configurable function           ||
21
 
 
22
 
= Explanations and Examples =
23
 
== Arbitrary Page Names ==
24
 
If you enclose a sequence of characters in square brackets and double quotes {{{["like this"]}}}, that makes it a page name. That can be used for specific uses of MoinMoin (like organizing a list of items, e.g. your CD collection, by their "natural" name) or for having a wiki with non-western character sets.
25
 
 
26
 
== URLs and Inline Images ==
27
 
There are several way to insert external references[[FootNote(The opposite of external references are the internal, automatic WikiName links.)]] into the text:
28
 
 * direct URL insertion; if the URL ends in an image extension ("{{{.gif}}}", "{{{.jpg}}}" or "{{{.png}}}"), the URL is converted to an image tag.
29
 
 * bracketed URLs.
30
 
 * InterWiki links.
31
 
 * email addresses.
32
 
 
 
27
||'''Hyperlink'''              ||'''Syntax'''                                ||'''Comment'''                 ||
 
28
||internal link                ||`WikiName`                                  ||Camel``Case page name         ||
 
29
||internal free link           ||`[[free link]]`                             ||any page name                 ||
 
30
||internal link to sub page    ||`/SubPage` or `[[/sub page]]`               ||                              ||
 
31
||internal link to sister page ||`../SisterPage` or `[[../sister|link text]]` ||                             ||
 
32
||internal link with linktext  ||`[[SomePage|some Page]]`                    ||                              ||
 
33
||link to attachment           ||`[[attachment:a image.png]]`                ||links to attachment image     ||
 
34
||interwiki link               ||`Otherwiki:somepage`                        ||requires uppercase wikiname   ||
 
35
||interwiki free link          ||`[[otherwiki:somepage]]`                    ||any wikiname in the map works ||
 
36
||external link                ||`http://example.net`                        ||                              ||
 
37
||external link with linktext  ||`[[http://example.net|example site]]`       ||                              ||
 
38
||border of internal link      ||{{{WikiName``s}}}                  ||2 backticks - for when a !WikiName ends in the middle of a word||
 
39
||avoid an internal link       ||`!WikiName`                                 ||configurable function         ||
 
40
 
 
41
||'''Transclusion/Embedding''' ||'''Syntax''' ||'''Comment''' ||
 
42
||embed an attached graphics ||`{{attachment:an image.png}}` ||show attached image file `an image.png` ||
 
43
||embed an attached graphics and give alt text ||`{{attachment:an image.png|alt text}}` ||show attached image file `an image.png` with alternative text saying `alt text` (recommended for accessibility) ||
 
44
||embed an attached graphics and define alignment ||`{{attachment:an image.png|alt text|align="position"}}` ||show attached image file `an image.png` with alternative text `alt text` and  aligned to ''position'', where ''position'' can be one of '''top''', '''middle''', '''bottom''', '''right''' or '''left''' (do not omit alt text) ||
 
45
||embed an attached graphics and resize it ||`{{attachment:an image.png|alt text|width=100}}` ||show attached image file `an image.png` with alternative text `alt text` and resize it to 100px width (do not omit alt text) ||
 
46
||embed an external graphics ||`{{http://example.net/image.png}}` ||show target image inline ||
 
47
||embed an external graphics and give alt text ||`{{http://example.net/image.png|alt text}}` ||show target image inline with alternative text saying `alt text` (recommended for accessibility) ||
 
48
||embed an external graphics and define alignment ||`{{http://example.net/image.png|alt text|align="position"}}` ||show target image inline with alternative text `alt text` and aligned to ''position'', where ''position'' can be one of '''top''', '''middle''', '''bottom''', '''right''', or '''left''' (do not omit alt text) ||
 
49
||embed an external graphics and resize it ||`{{http://example.net/image.png|alt text|width=100}}` ||show target image inline with alternative text `alt text` and resize it to 100px width (do not omit alt text) ||
 
50
 
 
51
= Explanations =
 
52
 
 
53
== URLs ==
33
54
If you enter URLs into normal text, there is the problem of detecting what belongs to the URL and what not. There are four ways to force the ending of an URL:
34
 
 * put a space after the URL.
35
 
 * use the Wiki:SixSingleQuotes escaping.
36
 
 * put the URL into double quotes.
37
 
 * use the bracketed URL syntax.
38
 
 
39
 
The supported URL schemes are: `http`, `https`, `ftp`, `nntp`, `news`, `mailto`, `telnet`, `irc` and `file`. The administrator of your wiki can extend the supported schemes by using the {{{url_schemas}}} variable (see HelpOnConfiguration).
40
 
 
41
 
In addition to the standard schemes, there are MoinMoin-specific ones: `wiki`, `attachment`, `inline`, and `drawing`. "`wiki`" indicates an InterWiki link, so `MoinMoin:FrontPage` and `wiki:MoinMoin:FrontPage` are equivalent; you will normally prefer the shorter form, the "`wiki`" scheme becomes important when you use bracketed links, since there you always need a scheme. The other three schemes are related to file attachments and are explained on HelpOnActions/AttachFile.
 
55
 * put a space after the URL,
 
56
 * use the Wiki:SixSingleQuotes escaping,
 
57
 * use the double bracketed URL syntax.
 
58
 
 
59
The supported URL schemes are: `http`, `https`, `ftp`, `file` and some others. The administrator of your wiki can extend the supported schemes by using the {{{url_schemas}}} variable (see HelpOnConfiguration).
 
60
 
 
61
In addition to the standard schemes, there are MoinMoin-specific ones: `attachment` and `drawing`, these are related to file attachments and are explained on HelpOnActions/AttachFile.
 
62
== Spaces ==
 
63
You can always use the double brackets (or double braces) syntax to use page or file names with spaces.
 
64
 
 
65
This will even work for interwiki links, if the target wiki understands standard url quoting (space will become %20).
 
66
 
 
67
== Anchors ==
 
68
To ''insert'' anchors into a page you need the ''Anchor'' macro (see HelpOnMacros): `<<Anchor(anchorname)>>`, where "anchorname" is the actual identifier of the anchor.
 
69
 
 
70
To link to an anchor on the same wiki page use `[[#anchorname]]` or `[[#anchorname|label text]]`.
 
71
 
 
72
To link to an anchor on another wiki page write `[[PageName#anchorname]]` or `[[PageName#anchorname|label text]]`, where "Page``Name" is the name of the other page and "anchorname" is the identifier of the anchor on that page.
 
73
 
 
74
/!\ On some Wikis, a link to the page RecentChanges might refer to the same page as this link: [[recentchanges]]. This is especially true for Windows and Mac OS X systems because they are not case-sensitive normally.
 
75
 
 
76
== Preventing Automatically Generated Links ==
 
77
 
 
78
To keep a word like Page``Name from automatically being turned into a link, use {{{Page``Name}}}.  (The problem with doing this is that it will prevent a simple search for the word "Wiki``Name" from matching {{{Wiki``Name}}} in a page, due to the inserted characters.)
 
79
 
 
80
You can also suppress WikiName linking by putting an exclamation mark (''bang'') before the WikiName, i.e. `!WikiName`. This is available by default, but can be disabled with the configuration option `bang_meta = False`.  Using this method will not interfere with most searches for the escaped `WikiName`, with the exception of certain quoted phrases and regular expressions.
 
81
 
 
82
To prevent automatic URL linking, use either {{{`http://...`}}} or `{{{http://...}}}`.
 
83
 
 
84
== Using link parameters ==
 
85
Sometimes you may want to give additional parameters for a link, influencing how it looks like, how it behaves and how exactly it links to the target - this is what the '''params''' part of `[[target|text|params]]` is for.
 
86
 
 
87
=== Setting attributes of the <a> tag ===
 
88
Available attributes: class, title, target, accesskey (see some html reference if you want to know what they mean).
 
89
 
 
90
Example: `[[http://moinmo.in/|MoinMoin Wiki|class=green dotted,accesskey=1]]`
 
91
 
 
92
Renders as: [[http://moinmo.in/|MoinMoin Wiki|class=green dotted,accesskey=1]]
 
93
 
 
94
(!) Pressing the access key should jump to that link target (for Firefox 2.x and the example above it is Alt-Shift-1).
 
95
 
 
96
=== Creating a query string for the target URL ===
 
97
What is possible for this depends on the target site.
 
98
 
 
99
Example: `[[MoinMoin:MoinMoinWiki|MoinMoin Wiki|&action=diff,&rev1=1,&rev2=2]]`
 
100
 
 
101
Renders as: [[MoinMoin:MoinMoinWiki|MoinMoin Wiki|&action=diff,&rev1=1,&rev2=2]]
 
102
 
 
103
(!) Please remember:
 
104
 * If you want to give a key=value item for the query string, don't forget the ampersand (&).
 
105
 * Giving query string items does not work when you give a URL as target (but for links to pages or attachments).
 
106
 * If you give a URL as target, you can include a query string directly in that target, no need for params.
 
107
 * You don't need to encode and url_quote the query string stuff, moin does this automatically for you.
 
108
 
 
109
== Images ==
 
110
You may use
 
111
{{{
 
112
{{attachment:imagefile.png|text describing image|width=100}}
 
113
}}}
 
114
to have the attached file `imagefile.png` displayed with a width of 100px; the graphics' height will be reduced/ enlarged proportionally (e.g. if `imagefile.png` was actually 200px width and 400px heigh, height would be reduced in this example to 200px). You may also use
 
115
{{{
 
116
{{attachment:imagefile.png|text describing image|height=100}}
 
117
}}}
 
118
to have the attached file `imagefile.png` displayed with a height of 100px, and the graphics' width will be reduced/ enlarged proportionally. Use
 
119
{{{
 
120
{{attachment:imagefile.png|text describing image|width=100 height=150}}
 
121
}}}
 
122
to have the attached file `imagefile.png` displayed with a width of 100px and a height of 150px. Please do not omit the alternative text in neither case.
 
123
 
 
124
Note this does not alter the attached file itself, in only makes the browser scale the image down/ up to the value given while displaying it.
 
125
 
 
126
=== Thumbnails ===
 
127
You may combine the transclusion with the linking syntax, leading to an image displayed in reduced size that links to itself in actual size, e.g.
 
128
{{{
 
129
[[attachment:imagefile.png|{{attachment:imagefile.png|text describing image|width=100}}]]
 
130
}}}
 
131
 
 
132
== Other stuff ==
42
133
 
43
134
For more information on the possible markup, see HelpOnEditing. For details on how to link to subpages, see HelpOnEditing/SubPages.
44
135
 
45
 
To ''insert'' anchors into a page you need the [wiki:HelpOnMacros macro] ''Anchor'': `[[Anchor(anchorname)]]`, where "anchorname" is the actual identifier of the anchor. To reference an anchor on the same wiki page use `[#anchorname]` or `[#anchorname label text]`. To link to an anchor on another wiki page write `[:PageName#anchorname]` or `[:PageName#anchorname:label text]`, where "Page``Name" is the name of the other page and "anchorname" is the identifier of the anchor on that page.
46
 
 
47
 
It is often desirable to create a link to a Wiki page in the current Wiki, but have the link appear with a different text label. While you can use an InterWiki link with a Wiki name of Self, this results in an InterWiki icon prefix which might be misleading since you're not leaving the current Wiki at all. Use the syntax of `[:WikiPage:Label text]` to achieve a link to a current Wiki page without creating an InterWiki link.
48
 
 
49
 
/!\ On some Wikis, a link to the page RecentChanges might refer to the same page as this link: ["recentchanges"]. This is especially true for Windows and Mac OS X systems because they are not case-sensitive normally.
50
 
 
51
 
[[FootNote]]
52
 
 
53
 
=== Avoiding some stuff gets automatically linked ===
54
 
 
55
 
For avoiding that a word like Page``Name automatically gets linked, use {{{Page``Name}}}.
56
 
 
57
 
You can also suppress WikiName linking by putting an exclamation mark (''bang'') before the WikiName, i.e. `!WikiName`. This can be disabled with the configuration option `bang_meta = False`.
58
 
 
59
 
For avoiding that a URL gets automatically linked, use either {{{`http://...`}}} or `{{{http://...}}}`.
60
 
 
61
 
=== Example ===
 
136
<<FootNote>>
 
137
 
 
138
= Examples =
 
139
== Markup ==
62
140
{{{
63
 
 * http://moinmoin.wikiwikiweb.de/
64
 
 * [http://moinmoin.wikiwikiweb.de/]
65
 
 * [http://moinmoin.wikiwikiweb.de/ MoinMoin Homepage]
66
 
 * http://moinmoin.wikiwikiweb.de/wiki/common/moinmoin.png
67
 
 * [http://moinmoin.wikiwikiweb.de/wiki/common/moinmoin.png]
68
 
 * [http://moinmoin.wikiwikiweb.de/wiki/common/moinmoin.png  moinmoin.png]
69
 
 * [http:/wiki/common/moinmoin.png] partial URL
 
141
 * http://moinmo.in/
 
142
 * [[http://moinmo.in/]]
 
143
 * [[http://moinmo.in/|MoinMoin Homepage]]
70
144
 * InterWiki
71
145
  * Self:InterWiki
72
146
  * MeatBall:InterWiki
73
 
  * wiki:MeatBall/InterWiki
74
 
  * [wiki:MeatBall/InterWiki]
75
 
  * [wiki:MeatBall/InterWiki InterWiki page on MeatBall]
76
 
 * user@example.com
77
 
 * mailto:user@example.com?subject=test
78
 
 * [:InterWiki:InterWiki page in this wiki]
79
 
 * [#anchorname Link to anchor on this page]
80
 
 * [:OtherPage#anchorname:Link to anchor on other page in current wiki with label text]
 
147
  * [[MeatBall:InterWiki|InterWiki page on MeatBall]]
 
148
  * [[MoinMoin:page with spaces]] (doesn't exist)
 
149
 * email
 
150
  * user@example.com
 
151
  * mailto:user@example.com?subject=test
 
152
  * [[mailto:user@example.com?subject=test|Email me]]
 
153
 * [[InterWiki|InterWiki page in this wiki]]
 
154
 * [[#anchorname|Link to anchor on this page]]
 
155
 * [[OtherPage#anchorname|Link to anchor on other page in current wiki with label text]]
 
156
 * {{http://moinmo.in/moin_static/common/moinmoin.png}}
 
157
 * {{http://moinmo.in/moin_static/common/moinmoin.png|moinmoin logo}}
81
158
}}}
82
159
 
83
 
=== Display ===
84
 
 * http://moinmoin.wikiwikiweb.de/
85
 
 * [http://moinmoin.wikiwikiweb.de/]
86
 
 * [http://moinmoin.wikiwikiweb.de/ MoinMoin Homepage]
87
 
 * http://moinmoin.wikiwikiweb.de/wiki/common/moinmoin.png
88
 
 * [http://moinmoin.wikiwikiweb.de/wiki/common/moinmoin.png]
89
 
 * [http://moinmoin.wikiwikiweb.de/wiki/common/moinmoin.png  moinmoin.png]
90
 
 * [http:/wiki/common/moinmoin.png] partial URL
 
160
== Display ==
 
161
 * http://moinmo.in/
 
162
 * [[http://moinmo.in/]]
 
163
 * [[http://moinmo.in/|MoinMoin Homepage]]
91
164
 * InterWiki
92
165
  * Self:InterWiki
93
166
  * MeatBall:InterWiki
94
 
  * wiki:MeatBall/InterWiki
95
 
  * [wiki:MeatBall/InterWiki]
96
 
  * [wiki:MeatBall/InterWiki InterWiki page on MeatBall]
97
 
 * user@example.com
98
 
 * mailto:user@example.com?subject=test
99
 
 * [:InterWiki:InterWiki page in this wiki]
100
 
 * [#anchorname Link to anchor on this page]
101
 
 * [:OtherPage#anchorname:Link to anchor on other page in current wiki with label text]
 
167
  * [[MeatBall:InterWiki|InterWiki page on MeatBall]]
 
168
  * [[MoinMoin:page with spaces]] (doesn't exist)
 
169
 * email
 
170
  * user@example.com
 
171
  * mailto:user@example.com?subject=test
 
172
  * [[mailto:user@example.com?subject=test|Email me]]
 
173
 * [[InterWiki|InterWiki page in this wiki]]
 
174
 * [[#anchorname|Link to anchor on this page]]
 
175
 * [[OtherPage#anchorname|Link to anchor on other page in current wiki with label text]]
 
176
 * {{http://moinmo.in/moin_static/common/moinmoin.png}}
 
177
 * {{http://moinmo.in/moin_static/common/moinmoin.png|moinmoin logo}}
 
178
 
 
179
= If you used moin before... =
 
180
Don't worry, it is much easier and better predictable now:
 
181
 * It is always two brackets (for links) or two curly braces (for transclusion/embedding) now.
 
182
 * Because of that, macros use '''`<<MacroName(...)>>`''' syntax now.
 
183
 * Use brackets or braces syntax if some target has blanks chars (no _ and no %20 any more!).
 
184
 * Use the pipe char (|) to separate target and text (and params).
 
185
 * '''`wiki:`''' is gone, just use interwiki without it.
 
186
 * '''`inline:`''' is now '''`{{attachment:...}}`'''.
 
187
 * Interwiki links now only use `WikiName:PageName` (''not:'' `WikiName/PageName`)
 
188
 * It has less magic now (and will just do what you say!):
 
189
  * Underscore (_) is a normal character and different from blank.
 
190
  * If you want an underscore, use an underscore - if you want a blank, use a blank.
 
191
  * If you link to an image, it will just link to an image (not show/embed it!).
 
192
 * For early moin 1.6 users: no quoting with double-quotes any more, use outer double brackets/braces to quote.
 
193
 
 
194
(!) This markup is inspired by creole wiki markup standard (and is also quite similar to what mediawiki engine uses).