Copyright (C) 2007 Michael Leonhard This document contains the design of SeriousIT.com. Here is the outline: * Wiki pages * Database design * Other pages (sign-in, password recovery, submit reports, admin pages, etc.) * Installation tools * Maintenance tools * Upgrading = Wiki Pages = The wiki is the most important part of the site. So it's natural that the design begin with it. I really dislike modes in user interfaces. When an interface has a mode, the user must keep the current mode in her mind and issue the proper commands for that mode. Forgetting the current mode leads to errors. The purpose of an interface is to facilitate the work of the user in the most efficient way. An efficient interface prevents errors and therefore has few modes. Now that we've established the undesirability of modes, let's look at how they apply to wikis. Modes are seen in several places: * PageExistenceMode: A page can be "created" or "not found". The user must take action to convert the page to an editable mode. ("Click Here to Create This Page") * EditMode: When you view a page, text is displayed. To edit the text, one must enter "edit" mode. * PreviewMode: After editing a page, one can see a "preview" of what the page would look like if the changes were saved. * SessionMode: A wiki stores state in the browser. This is called a session. The result is that changes to wikitext can be lost if the user refreshes the page, leaves and returns, logs out and back in, etc. * RevisionsMode: To see changes that have been made to a page, one must enter "revisions view" mode. The information presented here is often quite complicated and difficult to skim. (Diffs) Now for the changes to standard wiki behavior addressing these modes: * PageExistenceMode: A "not found" page is simply blank. A user may begin editing the page immediately. There is no need to click on anything to 'create' the page. * EditMode: Here is a radical change. Pages are editable immediately by placing the cursor and typing. All wiki markup is displayed at all times. Some markup may be displayed with a light color and small text. Thus the wiki will combine viewing, text editing, and gui editing modes of traditional wikis. Traditional wiki markup may be inappropriate for this new style of wiki. It may take a long time to find an optimal markup and behavior. Tables will be challenging. * PreviewMode: The main purpose of 'preview' is to let the user review changes before committing them to the database. The user is in 'preview' mode which is usually like 'editing' mode, except there is a formatted rendering of the page. The 'save' button transitions from the 'preview' mode to the 'view' mode. This behavior is a relic of forms based browser-server interaction. Now we have AJAX and it's about time we rethink the interaction model. This wiki will not have a 'save' button. Every change is immediately uploaded to the server. * UndoFunction: An 'UNDO' button will reverse the user's last editing action. Pressing the page's UNDO button multiple times causes the most recent operations to be undone. Each undone operation goes into a "undone change list". * RedoFunction: A REDO button will re-apply any changes that have been undone. It takes operations from the undone change list and reapplies them to the text. Editing the text causes clearing of the undone change list. The undone changes list is stored across sessions. * InlineChanges: Additionally, a record of the user's changes will appear in the text. Additions are marked with a different color. Deleted text appears in small text and light color above the point of deletion, marked by a caret ^. Clicking on a change causes it to be undone. The undo operation is a change, so the changes appear in the text and may be clicked. This is a 'redo' function. * SessionMode: The wiki will remember the user's edits and undone change list. This means that the user can refresh the page, leave the wiki and return, log out & log in, and the page will behave as if none of those things had been done. Note that if the wiki detects the user is no longer actively editing the page, it will allow another user to do so. TODO: Discover the best behavior for handling simultaneous edits. * RevisionMode: Revisions will be presented inline, in the same way as current edits. Revision history contains a lot of information that would clutter the screen if displayed for normal viewers. Rather than introduce a 'revision mode' of the document, revision information will be elided. Simple on-screen commands will show and hide specific pieces of revision information. I don't know exactly how this might work. I expect it will be similar to Doug Englebart's HyperScope [http://hyperscope.org/]. I think that basic revision information, helpful to editors, will be available without changing modes. Detailed revision info, such as who changed what, may need to inhabit another mode. I think a mode is tolerated here because someone seeking detailed revision info is performing a different task from a content editor. == Markup == Headings: = First Level Heading = == Second Level Heading == === Third Level Heading === Line formatting: > quoted text (large blocks of quoted text may be elided with "show quoted text") String formatting: *emphasized text* (italics) **extra emphasized text** (bold) Start of paragraph. ```Text shown verbatim, without recognizing markup characters. [This is not a link]. This *is not bold* text.``` End of paragraph. The formatting continues until the next marker is found. So it is not possible to embed an extra-emphasized word into a block of emphasized text: *This **doesn't** work* That line is interpreted as *This* *doesn't* *work*, three separate emphasized strings. QUESTION: should we allow these formatting characters to appear in text if they are surrounded by whitespace? So I could write "Emacs > * "? This would cause confusion for users who accidentally put in a space and wonder why their formatting doesn't work. ```Preformatted text block. This text will have a different colored background or a border to set it apart. Tabs Work , too. The block end symbol may be embedded by escaping one of the backticks: \``` Lists: * Bulleted List Item * Another Item 1. Numbered List Item 2. Another Item Note that when editing numbered lists, the page will automatically re-number contiguous items. So if I were to place the cursor below the '2. Another Item' and type '5. ', the '5' would be automatically changed into '3'. It would also get a blue squiggly underline to remind me that it was auto-changed. Type a list item, press enter, and a blank line is added. If you type another list item heading to add another item. Begin typing something that is not a list item of the same type of list, and a paragraph break is automatically added. Links: [http://google.com/] is a simple link [Google Search Engine http://google.com/] The title is a link to the url. [A Wiki Page] appears underlined [?various seach terms] is a link to the wiki's built-in search engine [? other search terms -notthisterm "this phrase"] The brackets and '?' are dimmed and shrunk. URLs are also displayed with a slightly different color from titles. If the user forgets the 'http://' then the whole link becomes a link to a wiki page. Ex: [Google google.com] will appear with the whole thing underlined. It is a link to a page with the name "Google google.com". If an invalid symbol is entered in a link to a wiki page, the offending portion is highlighted in red. Wiki page names may contain a limited set of ASCII symbols and unicode code points. Since page names are referenced in the URL, it is important that we prevent abuse. For example, robots.txt is an invalid page name. Page names may not end with a URL, as it would be impossible to reference them with a normal wiki link. Page names containing URL characters such as '?', '#', and '/' will be escaped. What about unicode page names that are very similar? I would like to employ a tool to disambiguate wiki page names. See: http://cups.cs.cmu.edu/soups/2006/proceedings/p91_fu.pdf THE METHODOLOGY AND AN APPLICATION TO FIGHT AGAINST UNICODE ATTACKS Anthony Y. Fu, Xiaotie Deng, Wenyin Liu (City University of Hong Kong), and Greg Little (Massachusetts Institute of Technology) Attachments: Upload an image to the page and make it appear with this: [:Image Name.jpg] The extension may be left out, [:Image Name]. Images are normally floated to the right side of the paragraph, with text flowing around. To have the image appear centered, with no text on either side, add the 'c' option, [:c:Image Name]. FUTURE VERSION: The 't' option causes a thumbnail of the image to appear. Clicking on the thumbnail shows the full size image. Add the 'h' option to hide the image and provide only a link to it. 'h' cannot appear with 't' or 'c' options. Links to other kinds of attachments work the same way: [:The Procedure.doc] [:The Procedure] [:CSD-48 Manual.pdf] [:CSD-48 Manual] [:abcde.tar.gz] [:csd-48 manuals.zip] If the specified attachment doesn't exist, the link will appear red. FUTURE VERSION: Clicking on a red link yields an upload field. FUTURE VERSION: I would love to have an upload progress meter. If the name of the uploaded file is different from the one specified in the link, the software should allow you to choose. It should present both names, with "Use" buttons. The names should be editable fields, so you can fix the name really easily. FUTURE VERSION: If the name is updated and there are other links in the page going to the old name, the software presents a command to the user for updating the other names. This could be a command box appearing on the right side. Clicking on the box invokes a Replace Text command that jumps through the text, allowing the user to press Y or N to approve each change. FUTURE VERSION: Mathematics, possibly using jsMath (http://www.math.union.edu/~dpvc/jsmath/). FUTURE VERSION: Bibliography items, footnote items, and citations. [@google] appears as an underlined link to bibliography entry 'google' [@google Google Search Engine http://google.com/] is a bibliography entry 'google'. The title is a link. FUTURE VERSION: Transclusion and linking to paragraphs. This could use purple numbers, like purplewiki, or Kragen Sitaker's queer numbers. FUTURE VERSION: Categories. These should integrate into the search engine, too. FUTURE VERSION: Sequences. Put a page in a sequence, then add Table of Contents and links: Previous, Next, Home. The content of such links are generated automatically. Thus you can easily add, remove, or rearrange pages in a sequence, without needing to edit each page. = Editing Markup = The editor is implemented in JavaScript. The html file imports wiki.js and calls wikifyBlock(div_id). The parameter div_id must be the DOM id of a DIV element of class 'block'. The function creates a new DIV, of class 'wikiblock'. It recurses through the children of the block, copying text to new elements in the wikiblock. After this, it replaces the block with the wikiblock. This replacement behavior is important because it allows the wikitext to be read by search engines and browsers that lack JavaScript. == Replacement Rules == BR = a line break BR? = a line break is inserted if the previous element is not BR * Text and BR elements are copied as-is *
contents
---> BR?, contents, BR *

contents

---> BR?, contents, BR * contents ---> contents * The replacement is recursive, so the resulting wikiblock is flat. * HTML elements not mentioned here are ignored, not copied == Text Flow == Text layout is determined by the browser's HTML renderer. This allows sites to put the wikiblock inside complicated layouts. It also lets sites apply their own CSS to the wikiblock text, with some limitations FUTURE VERSION: use the CSS !important marker to preserve the text styles that are required for a usable wikiblock. == Cursor == * The wikiblock has a blinking vertical cursor. (done) * Cursor blinks at a constant rate, even if JavaScript on the page is processing * Repositioning the cursor causes it to be immediately displayed in the new position, restarting the cycle of blinking * The cursor may appear between characters, at the beginning of the text, or at the end of the text. (done) * The user may reposition the cursor by clicking the mouse. (done) * If the click occurs on the left half of a character, the cursor moves to the left of it. Similarly, a click on the right half moves the cursor to the right of that character. (done, but uses non-standard properties, offsetWidth and offsetLeft) * If a click occurs in the margin, the cursor must appear in the text in the nearest line, as close as possible to the horizontal position of the click. * left margin click * right margin click * top margin click * bottom margin click * The user may press the left and right arrows to move the cursor forward and backward in the text * Left-arrow while at the beginning of the text has no effect * Right-arrow while at the end of the text has no effect * The user may press the up and down arrows to position the cursor in the previous or next line. When navigating vertically over multiple lines, the cursor maintains its horizontal position in the text after passing over short lines. * When an up-arrow or down-arrow is pressed, the current horizontal position of the cursor is saved in a vmove_hpos variable, if the variable doesn't already exist * When moving the cursor to another line, it is placed as close as possible in the horizontal axis to vmove_hpos. * A mouse click or key press other than up/down arrow erases the vmove_xpos var == Editing == * Typed characters appear at the cursor position * A typed newline character, ENTER, inserts a line break element * DEL key causes the character after the cursor to disappear. * If the cursor is before a line break element, the element is removed, causing the cursor's line and the next line to be joined. * If text is selected, the DEL key causes only the selected text to disappear * BACKSPACE key causes the character before the cursor to disappear * If the cursor is before a line break element, the element is removed, causing the cursor's line and the previous line to be joined * If text is selected, the BACKSPACE key causes only the selected text to disappear == Selecting by Keyboard == ... == Selecting by Mouse = ... == Copying Text == http://www.javaworld.com/javaworld/jw-07-1996/jw-07-javascript.html?page=7 ... == Pasting Text == ... == Undo == ... == Autosave == ... == Future Enhancements == * Make Flash editor using ActionScript * Java applet editor * Sun's JavaFX and Microsoft Silverlight? * Plain edit form for people using very simple browsers