• The semantics/linkage problem. Currently, there's no way for a contributor to mark 48004566 as a BugId. It could very well be an Oracle shared memory segment size or the output of the df command.

• The StarOffice problem. Firing up StarOffice every time the user wants to contribute a document with the *slightest* amount of formatting is a lot of overhead. 90+% of our contributors would prefer an all-in-one solution where the content and editing is kept in the browser.

SOLUTION

A simple text format that follows intuitive rules for formatting has been widely adopted in the open source and technical communities called WikiWikiWeb or just Wiki for short. See http://www.wikipedia.org/wiki/WikiWiki for background and the very first implementation, http://c2.com/cgi/wiki, for details, and http://twiki.org/ for one of the more full-featured wiki implementations available.

A short description of this proposed format follows. Also note that this document is also in Wiki format, and can be seen at http://www.wikipedia.org/wiki/User%3ADhagberg

• Paragraphs are separated by a blank line, just like this document. Simple end-of-line breaks are ignored. Multiple blank lines will be collapsed into a single paragraph break.

• Lines that start with spaces will be treated as literal text to allow for script, code, or output samples as shown below. Inside literal text, none of the formatting characters described below are significant.

    if [ -r /tmp/filename ]; then
        echo "FILE exists!"
        exit 1
    fi

• Emphasis is added by surrounding a word with 2 or more single-quote (apostrophe) characters like this for emphasis, this for strong emphasis, and this for very strong emphasis.

• Sections are started by beginning a line with == Section Name ==. Sub-sections are started by beginning a line with === Subsection Name === and Sub-sub-sections are started by beginning a line with ==== Sub-subsection Name ====.

• Bulleted lists, like this one, start with an asterisk (*) at the beginning of the line. For nesting, start the line with 2 or more asterisks. The list ends at the first blank line (so actually, in this document, each bulleted paragraph is its own list).

• Numbered lists start with a hash (#) at the beginning of the line. Again, for nesting, start the line with 2 or more hash signs. The list ends at the first blank line, so if this document used # instead of *, all the numbers would be 1.

• Definition lists start each term with a semicolon (;) at the start of the line, the term, a colon, and the definition body, with no spaces before the semicolon or between the term and the definition body (this lets people use semicolons normally in a sentence: like this). See the next paragraph for an example:

This term

This is the definition for the term and may span a paragraph break, so here's a little more text to fill it in.

• Links to CMS-specific items will be done like BugId:4700556[?], PatchId:110556-05[?], and Article:27005[?] but cannot be shown on Wikipedia since they do not know how to interpret these types of links.

• Image URLs, like will be shown as links unless they are in square brackets, in which case they will be shown inline. A similar treatment will be used for the Attachments functionality of the CMS.

• Tables will be handled slightly differently than implemented on the Wikipedia, namely that if the following section were not indented, it would be formatted as the table following the example:

    |Top Left | Top Right|
    |      Bot Ctr      ||

Top Left	Top Right
Bot ctr