Site Documentation

This site will started as a Django based site using Sphene Community Tools as the foundation. However, due to changes in technology, time, and hosting it was switched over to Drupal in September, 2010. Regardless of the site's foundation it is being engineered to provide a specific set of business and development behaviors. All code developed for this site is contributed back into the public domain via bug reports, direct module support, or at least emails to the authors for issues, enhancements, etc.

Business Behavior Key:

The basic behaviors required are:

  1. User System (UserSystem)
    • Optional captcha for registration
    • captcha configuration via the administration settings
    • login using user name (aka primary display name) or email address
    • email availability settings (Google like with a captch between initial display and full display of email names)
    • Auto assigning groups based of various criteria (number of posts, number of submissions to tags, weighted posting [replying with acknowledge helpful advice counts as more] and subscription levels)
    • Multiple Display names configurable for forums and book/wiki sections (for use in various areas TBD)
    • Multiple Signatures (for use in various areas TBD)
    • Graphical Signatures (based on authorization / user roles)
  2. Blog
    • Blog uses BBCode markup style
    • Blog posts have a WSIWG editor built that provides easy use of all allowed markup (including any allowed HTML)
    • Multiple Named Blogs supported displayed by list or locked down specified in an area
    • If authorized administrative ability to edit all blog articles
    • If authorized user ability to re-edit their own blog articles
    • If authorized administrative ability to edit all blog comment
    • If authorized user ability to re-edit their own blog comments
    • Comment time stamps are settable and editable with authorization
    • Blog article time stamps are settable and editable with authorization
    • Comments or blog articles with a future time stamp are not shown until the time set
    • Users with authorization may activate, deactivate and set a viewing time window to include future articles
  3. Tags
    • tag cloud spanning all site items (source, files, images, blogs, etc.)
    • auto-focus reduction tag-cloud (meaning as you drill in there will be the ability to have a focused tag-cloud for the subsection you are in)
  4. Wiki
    • Ability to break it down by areas
    • ability to grant users various rights within sections
    • Tied into the tags
    • On demand tables of content
    • ability to embed HTML if needed
    • Source code highlighting for all the languages I do (bash, Java, Jython, Python, HTML, CSS, XML, Javascript, C, etc.) See CodeHighlighting
  5. Subversion Repository Browsing
    • tied into license systems for bundled access based on roles
    • Source code highlighting for all the languages I do (bash, Java, Jython, Python, HTML, CSS, XML, Javascript, C, etc.) See CodeHighlighting
  6. Trouble Ticket System (TroubleTickets)
    • ability to grant users various rights within sections
    • If authorized ability to edit all parts of the ticket post
    • Source code highlighting for all the languages I do (bash, Java, Jython, Python, HTML, CSS, XML, Javascript, C, etc.) See CodeHighlighting
    • ability to link it one or more wiki pages, blogs, forum discussions and source code in the system
  7. Forums
    • ability to grant users various rights within sections
    • ability to move conversations to other forums
    • ability to hide / show forums based on permissions / roles / groups
    • ability to allow a forum posts to be re-edited by the poster (or an authorized admin) with full logging of the change (in a selectable change log forum and/or Wiki like using a DB table)
  8. Search
    • A complete context search engine across everything including the source code in the subversion sections
  9. Shopping Cart
    • Support for subscriptions (represented as Roles that are activated, renewed or deactivated automatically)
    • Support for bundled licenses (lifetime, time limited and limited number of accesses)
  10. News
    • Similar to blogs but represented more like snippets (show the headline and the intro, click on it to see the whole story.)
    • included on the pages in subsections of some number
    • named news feeds with identifying tags for CSS overriding
  11. Subprojects
    • A definable subsection of the site with one or more of the above elements all to itself.
  12. All the other bells and whistles (SiteTechNotes)
    • A WSIWG editor for anything that takes text
    • Award winning layout
    • Fast, fast, fast
    • fully automated
    • Backed up (with snapshots)
    • Repeatable, documented installation & recovery process

Code Highlighting


Code highlighting for a software providing/support/sales/discussion sight is mandatory. I have already started growing accustom to the BBCODE editing style for the posts and I also like the sparse nature of the Markdown formating for the Wiki. So what I need to do is very carefully integrate a plug in ability to have code highlighting on the fly as well as being able to designate and control which code highlighting syntax is used.

BBCODE already gives me the tie in by allowing the code tag to have a language specification. That should make it a lot easier. However, Markdown syntax does not have anything like that, unless I add something like a header marker for a code block. The indenting requirement of a code block in Markdown seems a little annoying. Maybe I'll come to like it.

In the mean time I have found the code highlighting engine I will graft into place:

Code Highlighter Requirements

The following features are required:

* a wide range of common languages and markup formats is supported, specifically:
* Linux/UNIX shell scripts (bash, csh, bsh, ksh, etc.)
* C/C++
* Dot-NET
* Java (of course)
* Python/Jython
* special attention to details that increase highlighting quality and performance
* support for new languages and formats are added easily; most languages use a simple regex-based lexing mechanism
* a number of output formats is available, among them HTML, RTF, LaTeX and ANSI sequences

Implementation Notes

Of course the first thing is to do is find one, get it, and then read all the docs. After that I can start putting into place a design for how to make it optionally available but automatically used if present.

Wiki Documentation

Usage of a Wiki is very straight forward.

1. Formatting

You can see complete demonstration of Wiki Syntax to format and structure your input text.

Two styles of markup are available: MediaWiki and Markdown.

The markup style is an extended form of Markdown Syntax. However the markup strives to be 100% Markdown compliant.

2. Additional Features

The markdown module being developed for Drupal as a filter module moves beyond the basic markdown syntax by adding the following functionality:

Wiki Links

To link to other wiki pages you can use one of two linking techniques:

  • CamelCase - simply write two ore more uppercase letters in a word and it will transform into a link. - If you don't want that to happen you can escape it with .. like: \CamelCase (the will of course not appear in the output: CamelCase)
  • enclose any word in [ ] brackets. e.g.: \[Wiki] and it will transform into a link - like this: [Wiki]. Again this is escaped by placing a backslash in front of the first square bracket.


Macros are an extension to the Markdown language. The basic syntax is:

{macroname parameter=value}

There is currently no public interface to add 3rd party macros. However, we are planning on adding it at some point.

The available macros are:

News Macro

The news macro allows you to display threads of a given board category. A simple usage looks like this:

{news category=7 baseURL=/board limit=5}

This would display the latest 5 threads in the board category of the id '7'.


The news macro supports the following parameters: Template

The News Macro requires a simple template (given by the parameter 'templateName' which is by default wiki/news.html)

An example template might look like this:

{% load sph_extras %}

<ul class="news">
  {% for thread in threads %}
      <div class="subject">{{ thread.postdate|sph_date }}: {{ thread.subject }}</div>
      <div class="body">{{ thread.body_escaped }}</div>
      {% if baseURL %}
        <div class="comments"><a href="{{ baseURL }}/thread/{{ }}/">{{ thread.replyCount }} Comments</a></div>
      {% endif %}
  {% endfor %}

2.2.2. News RSS Macro

This template renders an RSS link (including RSS icon) to the board rss feed displaying the latest threads in the given category.

{newsrss category=1} Parameters

2.2.3. Include Macro

Allows the inclusion of an external URL into a wiki snip. The file included is also rendered using Markdown !

Example Usage:

{include url= start=Directories end=Examples}

The example would include content from the file from the given url starting with a line containing 'Directories' until a line containing the content 'Examples'. Parameters

2.2.4. Include Template Macro

Allows a user to include arbitrary HTML by including a template from djang's templating system. (Ie. only an admin can create HTML content. - or anyone who has access to the template directories, or whereever the templates are stored.)

Example Usage:

{includetemplate templateName=mydir/sometemplate.html} Parameters

All additional parameters will be put into the context of the template as 'params'.

2.2.5. Image Macro

Administrators can add attachments to wiki snips. The Image macro allows to add such attachments as images into the wiki snip.

Example Usage:

{img id=123}

The example would include the image with the attachment Id 123. (The attachment Id is displayed in the list of attachments) Parameters

2.2.6. Attachment List Macro

Creates a list of all attachments of the current wiki snip.

Example Usage:

{attachmentlist} Parameters Template Variables

attachmentlist uses the generic view function object_list but without pagination.

2.2.7. Attachment Macro

Displays a single attachment which is referenced by it's id.

Example Usage:

{attachment id=5} Parameters

2.2.8. Redirect Macro

Redirects from one snip to another. This is useful to create aliases for wiki snips.

Example Usage:

{redirect snip=AnotherSnip}

This does not create an HTTP redirect, but simply loads the other snip. You can also create a chain of redirects (Like RedirectSnip1 redirects to RedirectSnip2 which redirects to RedirectSnip3 .. No idea why this would be of any use.. but it is allowed anyway) - If a loop is detected it breaks the loop at displays the snip the user has requested. Parameters Template Variables