Help:Adding Content

From SwinBrain

This page illustrates how SwinBrain is structured, and provides links on how to work with the mediawiki software. Access to SwinBrain is controlled, so if you want to be able to provide content please contact the site administrator for an account.

This is a How To article designed to give step-by-step instructions. Search SwinBrain and the external links if you require more detailed information about this topic.

Contents

The Basics

The MediaWiki Wiki Software

As SwinBrain uses the mediawiki engine, knowledge of the wiki syntax is needed. Try some of the following external resources

The cheatsheets/reference cards are particularly useful.

Wiki Markup Examples

  • Level 2 Heading ==Heading==
  • Italic ''Emphasesed''
  • Bold '''Strong'''
  • bullet list start with *
  • numbered (ordered) list start with #
  • image [[Image:File.jpg|frame|Text]] or [[Image:File.jpg|thumb|Text]]
  • Used template {{new template name}} then click through to edit.
  • internal links are [[other page name]] or [[other page|link text to show]]
  • external links are [http://url.goes.here.com.au text to show]
  • redirect to another page #redirect [[Document Object Model]]
  • to a category page [[:Category:Category Name|Link text to show]]

How Swinbrain is Structured

Topic Brains

Add links to your new content to the topic brain page. At the moment there is only one page, but this may need to be split into multiple pages in future.

Content Categories

Used to grouped related work.

  • Category names are plural. ie. "Programming Languages".
  • Add categories to the end of content pages.
  • The syntax is [[Category:Programming Languages]].

Current list of categories Special:Categories

Tip: There is no need to add categories for the "introduction", "how to" or "quick guide" pages as the appropriate template already has this.

"Category Introduction" Pages

It is typical to use the [[:Category: Category Name]] page (a special page in the "category" namespace) to give a brief "introduction" to the topic, rather than a using separate "Introduction" page as well as a category page.

For example, see Category:Internet Protocols which contains some introduction text, and then the automatically generated list of pages that belong to the category. See the links section above on how to link to special Category pages.

"Introduction" Documents

Intended for pages that introduce concepts or topics, not for detailed content that might be daunting for someone new to the area. Be sure to include links to the more detailed information (internal or external), but this is also available from Category links that should be added as well.

  • Use the introduction template with {{Introduction}} somewhere near the beginning of the page.
  • Note: the category [[Category:Introductions]] is automatically included by the introduction template, but you should add other category links that are appropriate for the topic.
  • Example: Database Introduction
Introduction: The material in this page aims to introduce important concepts rather than provide a detailed examination of the topic.

"Quick Reference" Documents

Used as short, concise reference pages. Not intended for descriptions or excessive detail. Emphasis on "quick"!

  • Use an article title like "Topic Name Quick Guide".
  • Use the Quick Guide template {{Quick Guide}} somewhere near the start of the page.
  • The "Quick Guide" category is part of the "Quick Quide" template.
  • Example: SQL Quick Guide
This page is a quick reference for this topic. SwinBrain and external links may provide more in depth details.

"How To" Documents

How To documents are primarily "walk-through" articles that can help the reader perform a specific task in a step-by-step manner.

  • Use an article title such as "Topic Name, How To".
  • Use the template {{How To}} somewhere near the top of the document
  • The category [[Category:How To]] is included in the template, but you should add any other category tags that are appropriate for your How To document.
This is a How To article designed to give step-by-step instructions. Search SwinBrain and the external links if you require more detailed information about this topic.

Block Level CSS Classes

The following classes can be used with div elements. Note that there are template that may be better suited to common "Tip","Note" and "Warning" boxes.

This is a class="callout-box".
Makes an easy spot for side content. Use the {{clr}} if you need to clear a floated box.


bug or warning box
class="tip" box
class="note" box
class="wrong" box
class="side-note"
class="side-note-right"
(width 40%, float:right)
class="side-note-left"
(width 40%, float:left)


Inline Classes

Other classes for span application to text (inline)

  • span.highlightgreen
  • span.highlightred
  • span.highlightblue

Other templates

  • {{Todo}} to show an easy message (searchable) "More information is coming on this topic..."
  • {{BoxedFooter}} use to present a group of related topics.
    • eg. {{Sample Code Footer}}
    • eg. {{Platforms Footer}}
  • {{Hint}} (acain specalised hint reveal template)
  • {{Ed}}

{{Tip|the text information}}

Tip: the text information

{{Note|the text information}}

Note: the text information

{{Warning|the text information}}

Warning: the text information

{{About|the text information}}

About: the text information

Tables

There are two ways to create tables in this wiki; the wiki table syntax (not recommended) and normal HTML tables (strongly advised).

  • Start with <table class="..." summary="..">
    • Use the class value to control presentation.
    • Use summary for longer tables that need a brief summary (good for accessibility)
  • Use a <caption>...</caption> element for .. the table caption!
  • Each table row must have <tr>...</tr> with cells in the middle.
  • Cells can be either <th>heading cells</th> or <td>data cells</td>. Use them properly.
    • Cells can span rows (rowspan) and columns (colspan). However, if things get to clever - use a GUI editor! Better to get the markup valid then hours of pain and tears with a hand-crafted page.
  • End with a </table> closing tag.

There are also <thead>, <tbody> and <tfoot> sections that can be used to enhance the logical structure of your tabular data.

The CSS classes that are available (have a look yourself for the exact details) in the external style sheets are:

.standard-table

  • collapsed border, 1px solid black.
  • heading cells bold, left aligned, padded left/right 5px;
  • data cells left+top aligned

.reference-table

  • standard + heading cells center aligned.
  • standard + width 100%;

.fullwidth-table

  • standard + width 100%

There are also .features-table, .mainpage-table and .topicpage-table classes. See the stylesheets for details.

Tip: It is strongly suggested that HTML based table markup is used instead of wiki table syntax. Eventually, the wiki syntax just becomes messier than the HTML so it's not worth knowing yet-another syntax. Also, there are plenty of editors around to help with HTML markup. For complex tables, create the markup in another tool and then paste the code into your article.

Extensions

We have several mediawiki extensions used to help provide content on Swinbrain

<code> Code Syntax Highlighting - Wiki Syntax Help

The Swinbrain mediawiki installation include a special extension to support code syntax highlighting. You can read about

  • Basic syntax is <code>[php,N] echo "Hi There!"; </code>
echo "Hi There!";

<mm> Mind Maps and FreeMind .mm Files

Mind maps are a great way to represent a collection of concepts. We are using an extension by Dimitry Polivaev, that uses either flash (or an applet) to display .mm XML files, created by the tool FreeMind, in the wiki pages.

FreeMind .mm files are first uploaded, and then linked to with

  • Size and Title: <mm>[[Hello.mm|flash|150px]]</mm>
  • Link and open in new window <mm>[[:Hello.mm|Description]]</mm>

More information about our use of the FreeMind MediaWiki Extension here.

<abbr>+title Abbreviation Support

This is the Mozilla Developer Center extension to support the abbr element for abbreviated text. The full text is stored in the title attribute of the abbr start tag. The extension is available via CVS. For example <abbr title="Mozilla Developer Center">MDC</abbr> will give us MDC. Any other media wiki code will need to be outside the abbr tags. The id, class and lang attributes are also supported.

<title-override> Title Override

Another extension used by the Mozilla Developer Center wiki installation, and details are available there. At this stage, only affects the use of a title as part of the "bread crumb" extension, which isn't being used yet, so it's pointless at this stage.

<blockquote>+cite+citetext Blockquote Support

This SwinBrain extension supports the <blockquote>...</blockquote> element for a large block of quoted text and the supplied "cite" url value. See the Blockquote MediaWiki Extension page for usage and code details.

Blockquotes are a good structure for larger blocks of quoted text, especially when you have an accompanying URL that points to the source of the citation. The extension will display the cite attribute information in display.

  • <blockquote cite="URL of citation">...</blockquote>
  • The title, id, class attributes are also supported as well as cite.
  • There is a custom citetext attribute. If set, the extension will automatically include a link to the cite URL with the citetext set.

Example: <blockquote cite="http://somewhere.com" citetext="link text to show">Normal quoted text here.... stop.</blockquote>

Results in:

Normal quoted text here.... stop.

link text to show

<rss> Feed Extension

Another extension used by the Mozilla Developer Center wiki installation, using the MagpieRSS PHP classes and based on the Mafs/RSS MediaWiki extension. Details are available at the MDC and mediawiki.

  • Usage attributes: charset=, short/long, max=X, highlight= term1 term2, filter=term1 term2, reverse
  • Example: <rss>http://slashdot.org/slashdot.rss|charset=UTF-8|short|max=5</rss>
  • Example page: RSS mediawiki Extension