Wiki Usage Help

This is an installation of the wiki Dokuwiki, whose site you may visit for more information. A wiki is a web site that allows you to edit its web pages directly through your browser. In this particular installation, only logged in users may edit web pages. In fact, the site only looks like a wiki to people who are logged in.

• Editing Pages
• Adding Pages
• Deleting Pages
• Wiki Syntax
• Uploading Images and Files
• Editing the Sidebar
• Editing the Footer

LOGGING IN — Before you can edit an existing web page, you must first log in. To login, go to any page of the site and append the character sequence ”?do=login” to the URL, and hit enter. You may want to bookmark one such page for loggin in, such as the following URL:

http://www.austinbutterflies.org/home?do=login

EDITING A PAGE — To edit a web page, first navigate to that web page. Then click [Edit this page] to edit the entire page. The text of the web page will then be displayed in a form box for you to edit.

EDITING A SECTION — Alternatively, you may edit just a single section of a web page. A web page that contains two or more sections will provide edit buttons at the bottom right of each section. If you edit just one section rather than the entire page, you allow other people to simulatenously edit other parts of the same page. Also, if there is a lot of text on the page, sometimes it's easier to view just to edit one small section at a time.

PREVIEWING — When you are done editing a section or a page, you may hit either the [Save] or [Preview] buttons. Previewing allows you to see what the page will look like before making your changes public. If you preview and you want to keep the changes, you'll still need to remember to save the page.

SUMMARIZING EDITS — The edit form provides a box for entering a brief “edit summary.” Entering the summary is currently configured to be optional. If you enter a summary, then people who look at the “old revisions” of the web page will be able to see a summary of the changes that were made rather than just that changes were made (in addition to the actual changes). This helps multiple people coordinate managing a large site.

The “minor changes” checkbox is a way for you to indicate that the changes you made were minor. However, since entering an “edit summary” is currently optional, there is no need to check this box.

SAVING — When you're ready to publish your changes so that they are visible to the general public, press [Save].

CREATE A NEW LINK — To add a web page to the site, you first create a link to that page. For example, if you want to create a page called “photos,” you'll need to first create a link to that page somewhere. You can either edit the sidebar and add the page name to the list of page names, or you can insert a link into an existing page. In the latter case, you would insert the text ”[[photos]]” somewhere into the web site.

Pages are organized into namespaces the way files are organized into folders on a computer. By default, all new pages go in the topmost namespace, called the “root” namespace. We should probably limit pages in the root namespace to the main pages found on the sidebar. Other pages generally belong in some namespace, such as when you're creating a lot of related pages accessible via one of the pages named on the sidebar.

To put a page in a namespace, just precede the page name with a namespace name followed by a colon. For example, if you want to create one page for each species of butterfly in the Austin area, you might put them in a “species” namespace. To create a link to the first page in this namespace—say, a page on bordered patches—use the following link:

[[species:bordered patch]]

As with creating any other new page, you would then click on the link you created to get to a page that actually allows you to create the new page. (For example, see the Counts in the “counts” namespace.)

DISTINGUISH PAGE NAME FROM LINK LABEL — When you create a new page, you have to give the page a name, as we just saw. However, it may be that you want certain text to link to that page, where the linking text is different from the page name. For example, you might want the text “wonderful club photos” to link to the page called “photos” without titling the page “wonderful club photos.” You don't want such a long name because you'd have to type it every time you link to the page, and because perhaps you may later add photos that aren't so wonderful. It's better to call the page just “photos.”

So whenever you create a link, you have to distinguish the page name from the link label. In our example, the page name is “photos” and the link label is “wonderful club photos.” To do this you would use syntax of the form [[page|label]]. In our example, we have:

[[photos|wonderful club photos]]

CLICK ON THE RED LINK — Once you've added a link to the new page, the link will be shown red to indicate that it points to a page that doesn't exist. To create the page, click on the link and then click [Create this page]. You can now start typing your new page into the form box.

TITLE THE NEW PAGE — The first thing you should do on any new page is to put a title at the top of the page. A page title goes on its own line and has a string of six equals signs both preceding and following it. The easiest way to insert these equals signs is to type the title, highlight the title, and then press the H1 button on the editing toolbar. Here's an example of a line that titles a page “Club Photos”:

====== Club Photos ======

SAVE THE PAGE — As with editing, you may first preview the page. The page will not be saved and published until you press the [Save] button.

EDIT, CLEAR, & SAVE — To delete a page, first edit the page, then clear out all of the text of the page by emptying the form box, and then save the page. This operation cannot be undone. Deleting a page permanently makes all previous version of the page inaccessible. Be careful not to accidentally delete a page.

SPECIAL SYNTAX — There are two representations of every page. One representation is HTML. This is the version of the page that the general public sees. The other is the wiki syntax, which is pure text. This is the representation that you type into the form box when editing or adding a page. Dokuwiki translates this syntax into HTML.

SYNTAX CHEAT SHEET — Here is a cheat sheet describing the formatting syntax. A link to this syntax reference is also found at the top of the edit form you see when editing or adding pages.

EDIT TO SEE EXAMPLES — One way to figure out what syntax to use is to find a page that already does what you want and edit that page or section to see how it does it. Immitate the wiki syntax elsewhere where you need it.

TESTING AREA — There is also a PlayGround for experimenting with the wiki syntax before actually putting the syntax on your page.

LINKS — There are two main kinds of links: internal and external links. An internal link links to a page on this web site. The simplest internal link is just a bracketed page name, as in:

[[Calendar]]

This display a link labeled “Calendar” that, when clicked, retrieves the “calendar” page. Letter case does not matter. If you want to have a different label go to the same calendar page, you'd do this:

[[Calendar|events in 2008]]

You may also link to a particular heading on a page by following the page name with a '#' and then the heading name:

[[Calendar#May '08]]

If the page is in a namespace, you precede the page name with a namespace followed by a colon, as in this (with the label still being optional):

[[species:pipevine swallowtail]]

An external link goes to a page on another web site. It works the same way as an internal link, except that the page name is a full URL that includes the preceding ”http://”. For example:

[[http://texasento.net|Mike's web page]]

EMAIL ADDRESSES — To help protect spambots from scraping email addresses off of the web site, you can put the email address in brackets:

[[[email protected]]]

The address will look normal to the person browsing the web page (except that it will be a link), but the HTML will encode the address so that it's a bit harder to decode. Clever spambots can still get the address, but hopefully fewer will.

SUMMARIZING EDITS — Whenever you edit a page, you need to either enter a very brief description of the edit in the “Edit summary” field or simply click the “Minor Changes” button. Doing so allows us to quickly glance through the revision history to see what changes have been made. Basically, if the “Save” button has been disabled, it's because you haven't changed the page yet, or you need to either enter a summary or click the checkbox.

OPEN MEDIA FILES WINDOW — To upload images or files to the site, you first need to open the “Media Files” window. Whenever you edit a page, you see a toolbar above the form box that shows the page's text. One of the buttons on this toolbar looks a bit like a picture in a frame. Hovering the cursor over this button yields the tooltip “Add images and other files.” Clicking on this button opens the “Media Files” window. It does not matter which page you're editing when you click on the button. Any image or file you upload can be put on any page at any time.

CHOOSE A NAMESPACE — A “namespace” is basically a folder. Before you upload a file you have to decide which namespace the file belongs in. The left side of the “Media Files” window shows the current namespace heirarchy. By default you're in the “root” namespace. Putting files there just clutters things, so you'll want to put the file somewhere else. Click on the namespace where you want the file to go. The “eyecandy” namespace is intended for images that decorate the site but don't otherwise have a home. If you want to put the file in a namespace that doesn't exist yet, then instead choose the parent namespace for the new namespace you'll be creating (usually “root”).

SPECIFY THE FILE — Once you've chosen the file's namespace (or the parent namespace of the new namespace), select the file you want to upload. You can type the full filename into the provided box, but it's easier to press the [Browse] button and select the file that way. This specifies a file that is on your home computer. Notice that when you do this, the “Upload as” box automatically gets filled in with a filename. This is the name that the file will take on the server. You shouldn't need to rename it unless another file on the server already has that name, or unless you're trying to establish some consistent naming scheme for your uploaded images. Note that all names are converted to lowercase letters after uploading.

SPECIFY A NEW NAMESPACE — If you want to put the file in a new namespace, first make sure that you've both selected the parent namespace and a file to upload, as explained above. The parent namespace will be displayed at the top of the “Media Files” window (with a colon in front of it). To put this newly uploaded file in a new namespace under the parent namespace, prefix the “Upload as” name with the new namespace name and follow it with a colon. For example, if you're in the “root” namespace and you want to create a “trips” namespace for a file named “DanCatchesSkunkInNet.jpg” then you'd make “Upload as” read:

trips:DanCatchesSkunkInNet.jpg

CLICK UPLOAD — Once you've selected the namespace, selected the file to upload, and changed the “Upload as” name as desired, press the [Upload] button to upload the file into the namespace. If you prefixed the “Upload as” name with a new namespace, that namespace will be created. Your newly uploaded file should now be listed in the namespace. If there are name conflicts, you will be asked how to handle the conflict and given a chance to cancel. You may upload as many images or files as you like and need not put any on any pages.

WRITE A CAPTION — There are two ways to put a caption on an image. Both ways only show the caption when you hover the mouse over the image. One way is appropriate only when the caption pertains to the image independently of the page on which the image is included. The other way allows you to give the same image a different caption with each use and is described under “Put Image/File on Page.” To associate a caption with the image itself, click on the pencil icon that appears to the right of the image's filename in the “Media Files” window. A good policy is to put the author's name in parentheses in the caption. Don't forget to save your changes.

PUT IMAGE/FILE ON PAGE — To put an image or a link to a file on a web page, you must be editing that web page and have the “Media Files” window open. To insert the file, put the cursor on the web page (in the text) where you want the file to go, and then click on the image or filename within the “Media Files” window. For example, if you're in the “eyecandy” namespace and you click on the bandedhairstreak.jpg file, the following text will be inserted:

{{eyecandy:bandedhairstreak.jpg|}}

You can move this around to change the position of the image within the file. You could also type this by hand if you're especially fond of typing. Notice that trailing vertical bar. Any text you type after that vertical bar will appear as the caption of the image. If you want to use the caption that's attached to the image itself, you must delete this vertical bar, as the only caption you'll get is whatever you typed after the vertical bar.

By default the image is placed on the left side of the screen. If you want it on the right side, put a space in front of the image name. If you want to center it, but spaces before and after the name. For example:

{{ eyecandy:bandedhairstreak.jpg|Some caption}}
{{ eyecandy:bandedhairstreak.jpg |Some caption}}

If you put this image text in the middle of a paragraph, the text will be made to flow around the paragraph.

SIZING THE IMAGE — You can upload any size image to the “Media Files” page, and this full-sized image will be available to the user for viewing or download. However, you may also specify the size that the image should take on the particular page where you put the image. To do this, simply append a sizing syntax to the image's filename.

The following example proportionately resizes the image so that its width is 200 pixels:

{{eyecandy:bandedhairstreak.jpg?200}}

The following resizes the image to the exact pixel width and height you specify (in this case, 400 pixels wide by 300 pixels high), and if you don't keep them proportional, the resulting image will be distorted:

{{eyecandy:bandedhairstreak.jpg?400x300}}

Once an image is shown on a page, anyone can click on the image to get a page that displays information about the image. If you click on the image displayed on this second page then you get the image in its originally uploaded size.

DELETING IMAGES/FILES — To delete an image or a file, click on the very poor trashcan with lid icon next to the image or file name in the “Media Files” window. The web interface doesn't provide a way to delete namespaces once created, but I can do this for you if need be.

INSERTING MULTIPLE IMAGES/FILES — By default, when you click on an image or file name in the “Media Files” window, the “Media Files” window closes. It's a pain to have to reopen it for every image you want to insert. You can opt to keep it open by checking the “Keep window open on selection” box at the upper-left of the “Media Files” window.

When logged in, you'll see the button [Edit sidebar] in the sidebar. Clicking this button allows you to edit a page called “sidebar.” The sidebar page is nothing but a list of page names, one page name per line. Wiki syntax is not allowed on this page.

You may add or remove page names. If you add a new page name, when you publish the page the link to the page will appear red in the sidebar to indicate that the page doesn't exist. You can then click on the red link to create the new page.

Any changes you make to the sidebar page affect the sidebar shown on all pages of the web site.

When logged in, you'll see the button [Edit footer] at the bottom of the page. Clicking this button allows you to edit a page called “footer.” The footer page is pure HTML. Wiki syntax is not allowed on this page.

Any changes you make to the footer page changes the footer on every page of the web site.