TextFormattingRules

Simple editing is one of the major benefits of using a wiki. Users can edit pages without knowing HTML, and still use many formatting features of HTML. Most wikis define a set of formatting rules to convert plain text into HTML. Some wikis (like this one) also allow some HTML “tags”, like <b>, <i>, and <pre> within a page. (Some wikis use raw HTML instead of special formatting rules.)

On this wiki

So, what are the markup rules for this wiki, now? Since Oddmuse has configurable rules, they have changed over the years. This section tries to give an overview.

The Oddmuse Text Formatting Rules:

Bullet lists:

* an asterisk is a list item
** more asterisks make nested list items 

Many ways to write links:

WikiWord
[[WikiWord|display text]]

[[Page name]]
[[Page name|display text]]

http://example.org/
[http://example.org/ display text]

Look like references:

[[[Page name]]]
[http://example.org/]

Images:

http://example.org/image.jpg
[[image:Page name]]

Oddmuse Markup Extension:

*bold words*
**bold words (including punctuation)**
/italic words/
//italic words (including punctuation)//
_underline words_
__italic words (including punctuation)__
##code##
%%escaped%%
{{{code}}}

Tables:

<table a,b,c,d>
a: blah blah
b: blah
c: bleh
d: blooh
a: blah blah
b: blah
c: bleh
d: blooh
a: blah blah
b: blah
c: bleh
d: blooh
----

Which generates:

blah blahblahblehblooh
blah blahblahblehblooh
blah blahblahblehblooh

CAREFUL! Tables columns can’t have anything other than letters in their names..!

Gemini headings are like markdown headings except there are only three levels. As is usually the case, in terms of style it would be better to reserve the level 1 heading to the page title and thus to only use level 2 and 3 headings when writing a page.

# Heading 1 (should not be used)
## Heading 2
### Heading 3

Gemini also has RocketLink​s:

=> http://example.org/
=> http://example.org/ display text
=> TextFormattingRules
=> TextFormattingRules display text
=> Alex_Schroeder
=> Alex_Schroeder display text

Gemini markup is line oriented. In order to not confuse regular wiki authors as much, any paragraph that starts with “>” is treated as a quote, where as Gemini would require us to consider every line on its own.

> quotes

Gemini code fences are like Markdown code fences. In the example below, I’ve used Unicode character ZERO WIDTH SPACE to “escape” the code fences.

​```
​code
​```

There’s more if you follow the links to the documentation on the installed modules.

CategoryThisWiki

Discussion

new: before 2020-12-23 01:14 UTCTimurIsmagilov: Are these simple rules really simple? Being a co-founder and co-admin of http://klavarog.tk, I have found people to have difficulties with the concept of markup, even an elegant one such as MycoMarkup.

new: 2020-12-23 01:14 UTCAlex Schroeder: I agree. Basically people know about some sort of emphasis using asterisks, rarely also underlines or slashes; people know about list items but use asterisks or minus at random; empty lines for paragraphs, depending on context, as often they feel a simple newlines should result in a line break.

  • TimurIsmagilov: I’m starting to think that a simple newline (\n) should really result in a line break (br) in the resulting paragraph.

Headings, numbered lists? Very rare. Anything else? Practically never. I am reminded of something I recently wrote on my blog regarding Computer Competency with special regard to the summary of the OECD report:

It’s devastating, and raises the question of what “smart users” might actually mean. The Nielsen Norman Group has a great summary. They count four levels of proficiency, if you know how to use a computer. This is important, because a full 26% of the adult population was unable to use a computer. A quarter! 14% are “below level 1”. They can perform a simple, straight forward tasks like “delete this email message.” That’s 40% of the adult population. 29% of the population are at level 1. They can use a widely used tool like email software or a web browser. They can perform straight forward tasks like “find all emails from John Smith.” That’s 69% of the adult population. Another 26% of the population are at level 2. They can perform multi-step tasks like “find a sustainability-related document that was sent to you by John Smith in October last year.” That’s 95% of the population. Only the remaining 5% can solve problems that involve setting sub-goals and assessing progress, evaluating relevance, reliability and so on. The example task provided is to determine “what percentage of the emails sent by John Smith last month were about sustainability.”

  • TI: cool article, I remember it.

new: 2020-12-23 01:14 UTCAlex Schroeder: When LionKimbro recently asked what this wiki is using, I said we were using Markdown. But now that I’ve checked, I see that it isn’t true. It’s a mix of a variety markup rules and goes to show that the actual subset of markup people use is minimal.

We could simplify the current setup significantly!

new: 2020-12-25 01:53 UTCLionKimbro: Well – …

I remember using a TON of markup on this wiki, – but now that most of it’s disabled – I can’t even figure out how to make italic text, right now. So, that’s why I’m using less, immediately?

I’d love for us to figure out what we’re doing here. If we’re using MarkDown, or Markdown, or whatever, let’s do that. It’s thoroughly confusing at the moment.

And I agree, we don’t need numbered lists.

new: 2020-12-25 01:53 UTCLionKimbro:

On the other topic – I love wiki markup (vs. WYSIWYG). This isn’t a fetish, this is for a purpose. It’s for two reasons:

The first point is easy to understand: Wiki Markup is entered into HTML text areas, which makes it simple enough to implement in contemporary software. More sophisticated means of entry requires a lot of code and customization on the part of the WikiEngine writer, and the more complex it gets, the harder it is to change or add new things to it.

That’s the easy one. The second one is harder to understand, but I think is even more important.

Wiki Markup establishes a lucid boundary between “this is what we type in,” and “this is what we get in the presentation.” The problem with saying WhatYouSeeIsWhatYouGet is that you have now restricted what can be presented, to what your complex user-interactivity code can represent. Any feature that tabulates or transforms user input is now either (A) forbidden, or (B) surprising to the user, who is expecting (or demanding) that: “What I See is What I Get.” It implies a contract between the user and the wiki engine: “It is your obligation to make this easy for me, and it is your obligation to not surprise me.” And as long as that contract is implied, then the development of the wiki engine to support features that are not easily incorporated into the InteractivitySystem, is cut off in an early stage of thinking: “Well, how would we integrate that into the WYSIWYG?

For example, consider LocalNames. Now the interactivity system needs to be updated to know about and respond to any local names that the user might type in. If post-processing on the text after submission should turn up a local name, and the output now shows a link where there wasn’t one before, the user now asks, “Hunh – well, why did that happen? I thought this was WYSIWYG. But I see a hyperlinked text now. How do I make it so that that doesn’t show up?” Now the interactive “WYSIWYG” system needs to support a feature that says, “Make sure that this text doesn’t link.” How does that should up, in the WYSIWYG editing system? Does it highlight in yellow? (A yellow highlight that doesn’t actually appear on the page?)

This is just one example. I think I could think of 50 more, and for any feature that we typically implement in the software system, we’d basically have to revamp and extend the interactivity system to support, and make immediately visible to the user.

Now we are far, far off the track of SimpleSystems, which is one of the key attractions to wiki and community-owned / community-developed technological infrastructure.

Honestly, for me, I would rather sacrifice people’s comfort around “Well, TextFormattingRules look weird and make me uncomfortable,” than the capacity of the community to process text and adapt it to their various needs. I don’t want unskilled people’s illiteracy to get in the way of skilled people. If people don’t want to use markup, just let them not use markup – other people can format their text for them.

new: 2020-12-25 01:53 UTCLionKimbro:

I am thoroughly confused, now, and believe that we need to have written at the top of this page, some of the simplest elements of how to do the following on CommunityWiki, now:

  • italicize text
  • bold text
  • make headers (I think it’s a series of “#”’s now.)
  • pre-formatted text blocks
  • hyperlinks
    • to other pages by name
    • to other pages by masked name
    • to external URLs

new: 2020-12-23 01:14 UTCAlex Schroeder: I hadn’t thought about the WYSIWYG counterpoint you made above and like it very much!

I tried to document the current set of features above, at least the important ones. 😅

new: 2020-12-25 01:53 UTCLionKimbro:

Whoah, thank you so much, Alex, for writing all that up, at the top!

I was getting really, really lost, in terms of formatting.

new: before 2020-12-23 01:14 UTCTimurIsmagilov:

  • How do I insert an image?
  • I’ve seen multi-lingual pages. How do I that?

new: 2020-12-23 01:14 UTCAlex Schroeder: Oddmuse allows a page to be either text, or a file (usually images). So any time you edit a page you can switch from text to file and back (losing what you had, of course). Thus, if you edit Alex Schroeder Portrait the edit page will be different – no text area and a file picker instead. Use the “green button” link at the bottom of the edit page to switch: “Replace this file with text” or “Replace this text with a file”. If you follow a link [[image:Foo]] you end up on an edit page that’s already in “file upload mode”. Sadly, there is current a small bug in that these [[image:Foo]] links to non-existing images aren’t automatically updated to show the image once you upload it, because they are in the HTML cache (unlike ordinary links). I often go back and make a minor edit on the page with the link once I upload the image, or I don’t save the page when I add a link to an image and just use Preview, follow the link, upload the image, then go back and save the page with the link to the image (and now the HTML cache is correct).

new: 2020-12-25 01:53 UTCLionKimbro: Quick note – meeting in 1 minute – can we have a link to this page in the “Empty lines separate paragraphs. Paragraphs may span several lines. …” text at the bottom of the page? Hard to find this page. I looked at WikiSyntax, CommunityWikiSyntax?, WikiMarkup, etc., didn’t find this except exhaustively.

new: 2020-12-23 01:14 UTCAlex Schroeder: Done! 😀

(CommunityWikiFooter)

Define external redirect: CommunityWikiSyntax

EditNearLinks: WhatYouSeeIsWhatYouGet WikiEngine WikiMarkup MarkDown

Languages:

The same page elsewhere:
MeatBall:TextFormattingRulesWiki:TextFormattingRules