Home »

Notes for wiki page editors

Below are some notes and conventions to help make all the pages on this wiki reasonably consistent, i.e. easy to navigate.

FWIW, I reserve the right to rearrange information added by others, but will always do so with restraint and respect. -jcw

Redmini Wiki documentation

General editing notes

Wiki pages are not discussions. Apart from this page, where I added "-jcw" in the intro to make it clear who "I" is on this page, most pages should not refer to "I" or "me", since pages may have been edited by several persons. The "History" link at the top of the page can be used to find out who wrote what. If you want to discuss something, use the Forum instead (posts can link to wiki pages!).

Feel free to edit any page you see to correct typo's, to update obsolete info, and to include additional information. Don't delete substantial amounts of text unless the information is grossly outdated, confusing, or redundant. Try to use the same style, and try to leave the general page order intact - the original author probably had a reason to organize things in a certain way.

When editing a page, especially if you are not its original author, please add a short note in the "Comment" field before saving the changes, explaining the change. It's easy to forget at first, but it's a valuable habit to get into. These comments show up in the page history.

Page naming conventions

To create a page, you need to enter a link to it on an existing page. It will then show up as a red link (page non-existent). When you click on it and then save it, the new page will be created. Once pages exist, links to them will show up in blue, as usual.

Since all page names on this wiki have to be unique, some care is needed to pick a suitable name. Here's what I've been using so far:

  • Libraries have a page of their own with simply their name, e.g. "Ports"
  • External functions have a page with their own name and "()" appended, e.g. "rf12_initialize()"
  • Classes get a page with the word "class" prefixed, e.g. "class DeviceI2C"
  • The public members of a class have the class name as prefix and "()" appended, e.g. "DeviceI2C send()"
  • Example sketches have the word "sketch" appended, i.e. "blink_xmit sketch"

That way, class PortI2C and class DeviceI2C can both have a function "write()", each with their own page.

Inline images

To show an image inline, attach it as a file and refer to it as "![](640wide.png)" on the page:

Make images at most 640 pixels wide, so they won't interfere with the sidebar on smaller screens.

Problems and workarounds

Back-to-back page references

The "BlueFeather" code used by the Markdown extra formatter on this site has trouble with back-to-back page links, i.e. "[[...]][[...]]" - it generates some error messages at the start of the page. It's not enough to put white space between them or to put the two page references on separate lines, you have to insert some character between them to get rid of the error message.

Unicode special characters

Some Unicode characters outside the ASCII range get garbled. Unfortunately that includes symbols such as ? (ohm), which ends up as a question mark. It is not clear to me where it gets garbled, because the preview still seems to show them intact. It's probably an encoding setting, either during the Markdown translation phase (i.e. a 3rd part Redmine plugin), or an encoding issue between the web server and the web browser. Other characters, such as é ° µ don't seem to be affected. This issue has been flagged as #34, but it is not clear how to fix it.

Referring to file attachments

Unlike inline images, you can't refer directly on a wiki page to a file attached to that same wiki page using []'s and ()'s. But it you attach file "abc.def", then you can create a reference to it with the text "attachment:abc.def". Note that this does not need to be within []'s, the text is recognized everywhere, in the same way as #XXX and rXXX references are.

640wide.png (11.4 KB) jcw, 2010-09-11 11:50