NEWS/TextFormatting

Revision as of 20:01, 21 November 2007

What markup rules should the NEWS wiki system use? (note that this page is for the discussion of the markup, and the "decided to be correct" markup rules are in /Markup)

Nemo feels that the whole point of wiki markup rules is that the source material look as much as possible like a raw text document, and that the wikirules merely be a formalisation of existing pseudoformatting rules.

Or, as the BHL system describes it's intent: The purpose of this mode is to use the most invisible and convenient syntax. "Invisible syntax" means that the source file must be as readable as possible - like any TXT file must be. "Convenient syntax" means that it must fit the users' habits.

NEWS tries to follow these principles in it's design:

• Invisible - the raw "code" is understandable by a layman with minimal confusion
• Convenient, or PLS - Principle of Least Surprise. Always an important UI design consideration.
• Simple - aka KISS, aka 10/90 rule. The idea that 10% of the features can accomplish 90% of the work. (or, in the case of XHTML features that we want a subset of, I suspect that probably 5% (or less) of XHTML would satisfy 95% (or more) of users needs. (95% of needs, or 95% of users - your choice). The point is that the design should try and hit the sweet spot of getting maximum usage value out of your markup buck.

...So, none of this crap of '''bold''' for bold, and ''italic'' for italic!

• *bold* should be bold, /italic/ should be italic, _underline_ should be underline. It's not really that hard now, is it?

So, let's get to it, compile a full list of what is needed, and how to do it.

(btw: See also:

• http://meta.wikipedia.org/wiki/Wikitax as well - similar intent for a wiki
• http://www.nongnu.org/bhl/manuals/bhl-en.html - very emacsian, but also similar intent overall
• http://www.zope.org//Members/jim/StructuredTextWiki/StructuredTextNGRules - Zope ideas on a similar theme
• http://www-106.ibm.com/developerworks/library/x-matters24/ - reStructured Text - one of the official source formats for python documentation
• http://phpwiki.sourceforge.net/phpwiki/NewBlockMarkup - PHP wiki's new markup discussions
• http://c2.com/cgi/wiki?WikiPrinciples - Wiki Principles - on the original wiki.
• http://www.webdav.org/wiki/projects/SubWikiTODO - Sub wiki might make a VERY good basis for NEWS though... some good links on this page
• http://daringfireball.net/projects/markdown/syntax - Similar to NEWS in some respects, but not nearly enough.

NEWS-CL

NEWS Control Language: This is used to control aspects of the page, beyond traditional basic markup (though some NEWS-CL commands will affect the look/contents of the page in markup-ish ways.

All NEWS-CL directives are in the format of "#COMMAND# options". Any "#" lines which do not match "#COMMAND:" (case sensitive) are treated as regular text for NEWS-ML purposes)

You mean 'do not match "#COMMAND#"', right? -- st

Redirections

#REDIRECT# newpage

• Must be the first line of code or will be ignored, all further code on this page is ignored and the newpage is loaded.
• question: what to do if newpage does not exist? (answer: go to the edit for newpage)

Well, do the same thing that you do for any other link that doesn't exist. I think for most wikis that's a page that says 'The page Foo doesn't exist - would you like to create it?'. -- st

Inclusions

#INCLUDE# includepage

• Note that the entirety of the included page is inserted (probably formatted within a nested table or other obvious method).
• The included page only checks for NEWS-ML but not NEWS-CL (since that could lead to further inclusion!)
• If a inpage anchor reference is given "includedpage#subheader", then only that section of the page is included.
• The formatting for an included page should include a link to that page proper
• If an included page does not exist, give a format a friendly error to the page with a create-page link.

Table of Contents

#TOC#

• Generates a table of contents from analysis of Headers inside the page.
• Should this be a wiki variable, rather than NEWS-CL? (ie, see www.twiki.org stuff)

seso

• Generation of Tables of Contents (is this NEWS-MLish?)
• Generation of included boxes

NEWS-ML

NEWS Markup Language: This is the discussion of the syntax for marking up the text itself.

HEADINGS

- see NEWS/Markup

BOLD / ITALIC / UNDERLINE / STRIKETHROUGH / SUPERSCRIPT

- see NEWS/Markup

LISTS

- see NEWS/Markup

INDENTING

- see NEWS/Markup

HARDRULES

- see NEWS/Markup

PREFORMATED

- see NEWS/Markup

NOWIKI

- see NEWS/Markup

TABLES

Very usefull for showing data. Most wiki's seem to implement this with the pipe as the command character. Specific formatting for NEWS to be considered later.

• I have discovered that HTML can defines tables of astounding complexity and arbitary dimensions. Bonus points for figuring out a PLS grammar for that. :)
• <nemo> thanks for the words of encouragement. Note above about the 10/90 rule ;)

IMAGES

Image URL's should be autodetected, and auto-inlined. An image may have a comment, which can be seperated from the URL by a pipe, and wrap the whole lot up in doublesquare brackets, wiki-link style.

• How do you detect if an arbitary URL points at an image or not?
• The comment idea is taken from Brainstorm. They render the comment by the image. Do we want this, or should we treat the comment as ALT= text?
  • ALT text should be used in place of an image - that is, if the image is inline, the alt-text should make grammatical sense as part of the surrounding text. Perhaps you mean TITLE text.
  • <nemo> TITLE text?.
    • Read up on it. -- st
  • But your point is valid, aye.
• Is there a way to link to an image, without making it inline? Maybe this is what the comment text can be used for?
  • Uh.. make it an ordinary external URL link?
  • <nemo> That's the point. It's exactly the same as an ordinary external link, as far as markup goes. The only way the wiki knows it's an image (to answer your earlier question) is that the suffix is a known image type. ie, .{gif,png,jpg,jpeg} (non case sensitive there). So the problem remains.

IN-WIKI LINKS

There are a few ways of handling stock wikilinks.

• normal wiki CamelCase will link.
• Wikistyle [[doublesquare brackets]] will link.
  • Screwtape wants to know why not use single square brackets like E2. I need to know advantages and disadvantages of this before considering further.
    • Advantages: Fewer keystrokes. Single-square brackets are a typographical convention that people outside the computer industry may well have seen before.
    • Disadvantages: The parser might be confused by articles about the Apple ][.
    • <nemo> ...or other pasted code. Alot of code has singlesquare brackets around stuff. On the other hand, pasted code would likely be in a preformatted textblock - and if that is excluded from all other wiki markup, then this is a nonissue :)
• Masking of link is handled by a pipe - requires doublesquare bracket linking. If the mask is an image URL then that image is included inline and linked. (a second pipe then may include the comment for the image)

EX-WIKI LINK

There are a few ways of handling links to external/nonwiki pages.

• URL's alone are autodetected and autolinked.
• Masking is accomplished like inwiki masking. (including image-as-link handling)

IN-WIKI PAGE ANCHORS

This wouls be nice to have...

• Anchors are created for any header used within a wikipage. The anchor name being exactly the header name. (is this always desirable?).
• Links to the anchors are handled as part of normal in-wiki linking. eg, if "CamelCase" is a page, with "example" as an internal header, then "CamelCase#example" would be automatically wikilinked. (wikilink it as "CamelCase", or as "CamelCase#example" or "CamelCase (example)" or some other? Nemo prefers the last.
• To link to an anchor within the page current, you'd either have to give the full camelcase version, or doublesquarebrackets the anchorname alone. eg. [[#example]]
  • Should there be a variable (eg %topic%), which will always expand out to the current page? (This idea from Twiki). Thus %topic%#example would be expanded (when parsing) to CamelCase#example, and then linked as above.
• I'm running out of time, but consider this: If I have a heading called 'Troubleshooting Tips' (a situation that is not overly contrived, I feel), how would a Camel Case link work then?
• <nemo> well, the link would be, uh, "%topic%#Troubleshooting%20Tips". Of course, this makes the URL non-memorable. :/ Other idea (which can be implemented parallel) is that the headings which summarize down to an ordered list (and nestings thereof), mean headings withint he page have a section number. "Troubleshooting Tips" might just as easily be reffered to as "%topic%#2.1". (this is Moinmoin style?

NEWS does not dictate any limits on the depth of a tree. BY comparison, most wiki systems are flat tree, or limited to a single depth. So, with this in mind, how do we refer to pages well above or below the current page? By way of starting comparison, UseMod assumes any link is top-level, unless the linkname starts with a leading slash (/), in which case that link is a subpage to the current toplevel page. (ie, if /SubPage is linked from a toplevel page, then it refers to a descendant page (subpage) - but if that link exists on an existing subpage, then it in fact refers to a sibling... A link with a slash in the middle then splits the link to be 'Parent page / subpage' - thus allowing you to link to a subpages directly.

The following is proposed for NEWS:

• [WikiPage] - searches for a subpage first, then sibling page next, then aunts-uncles pages, and so on up the tree. Or, to put it another way, it searches for "WikiPage" amongst it's children, then amongst it's parents children, then amongst it's grandparents children - up to the top. It will not descent any trees however. If the page is not found, then the template page is assumed to be found as a sibling. (this on the assumption that the most likely use is to link between a mostly-flat top-level namespace).
• [/WikiPage] - a leading / looks for a subpage to the current page. No searching through the 'family tree' is performed.
• [//WikiPage] - a double leading / is an absolute path starting from the root.

examples:

• To get from a page "//Vehicles/Automobiles/Ford/Falcon/wheels" to "//Vehicles/Automobiles/Holden/Commodore/wheels", you could link to either "Holden/Commodore/wheels", or "//Vehicles/Automobiles/Holden/Commodore/wheels". A link to merely "Commodore/wheels" would likely fail, and ask you to create a page at "//Vehicles/Automobiles/Ford/Falcon/Commodore/wheels".

You only need to link to the trailing component of the path to the new page that is different from the trailing path of the current page.

• To get to the page "//wheels" from "//Vehicles/Automobiles/Ford/Falcon/", you would HAVE to link it as "//wheels", as a link to "wheels" would find the subpage from the previous example first...

additions, questions.

• When will nemo write up NEWS-CL?
• What about autogenerated table-of-contents from headers?
  • what about autonumbering this toc for additional purposes of page anchors?
• what about tables?
• other variables? (see Twiki. they use them alot!)