Simple Content Markup
ISSUE
For wide acceptance and delivery of Voyager, we need to have a simple, clean, consistent model for simple content contribution that allows for adding a minimal amount of content structure, formatting, and semantics. The current contribution/editing interface for simple documents is not sufficient for several reasons:
- The wrapping problem. Currently, to get documents to display exactly the same on-screen, in the Preview window and on SunSolve, the TEXTAREA forms are set to Hard-Wrap. This feature will auto-wrap the 1st time. But the when one attempts to edit the document, they will find that they need to manually re-wrap the entire paragraph they were working on.
- The table problem. Currently, if a user contributes an article with an ASCII table, that table *must* be narrower than 75 characters and, every time a longer word or a column needs to be added to the table, the user will need to manually re-wrap the entire table.
- The list problem. If the user wants to contribute an article with a numbered list, they would format it like this one (or similarly). If they go back and add an item to the middle of the list, they will need to re-number the entire list.
- The styling/formatting problem. Adding *emphasis* like this or /this/ is not the most effective means of communications with Sun's customer base, who expect professional-looking documentation of the same caliber they can get from docs.sun.com or the Microsoft Knowledge Base.
- 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 | |