::artweb by Geir Isene

welcome

Feel free to use whatever you find herein - to whatever you like. Just give due credit to me as the originator.

notice

The Amar Non-Playing Character generation program is online again.

featured art

Watermirror

WOIM

Having worked extensively with flowcharts, relational charts, Venn diagrams, Warnier-Orr diagrams and other ways of representing processes, states, instructions, programs and data models, I knew there was something missing. It would be great to have a way of representing anything - any state or action - in a way that would be more conducive to collaboration.

You can dowmload this document as a PDF file.

Most people know about flowcharts. But there are other ways of representing data, states, actions or processes: UML, Sankey diagrams, decision trees, Petri Net, organizational charts, mind maps, Process Flow diagrams, Feynman diagrams, Data Flow diagrams, Concept Maps, OBASHI, Task Lists (or To-Do lists), Warnier/Orr diagrams and various other diagrams. More than we can list here. They have various uses, various strengths and shortcomings.

Most methodologies for representing states or flows were born out of specific needs and not to be used as generic methods for representing everything as simple as possible. What if there was a way to represent any state, set of things, actions, flows or transitions? What if the method was simple? What if it was also Turing complete?

Enter WOIM.

WOIM is the acronym for Warnier/Orr/Isene/Moeller.

It is a system for representing data. Any data. Static or dynamic. It can be used to describe any state; A thing or set of things, an area, a concept or collection of concepts etc. It can also be used to describe any action or plan, transformation or transition. In fact, it can describe anything - with one complete markup set. WOIM can be be used as an outliner on stereoids or a todo-list managing system with endless possibilities.

After searching for a complete markup methodology for both states or things and actions or transitions, I came across the Warnier/Orr diagrams. They seemed to be the best foundation for what I needed. The Warnier/Orr diagrams were expanded to be able to as easily as possible descibe anything. I removed the graphical parts of Warnier/Orr and expanded the methodology substantially. My collegue Egil Moeller helped in the refinements of WOIM.

The strengths of WOIM are many:

can represent any state or action with any amount of levels
Turing complete
text-based (which means it is wiki-able - i.e. it is easy to collaborate when creating WOIM lists)
not graphical (although it can easily be made graphical for ease of consumtion or for eye candy)
an easy syntax, humanly very readable
compact
can represent negatives (NOT, don't do the following actions)
can represent any number of choices in a decision (hard to do in a flow chart)
easy to do loop counts
easy to show attributes such as time or timing, location, responsibility etc.
potentially easy to map to other representation methods (graphical or not)

In its simplest form, a WOIM list is just a list of items - like your regular shopping list - but it can be so much more if you need it. A couple of examples will give you the basic idea.

An example of describing a state:

 Car (not complete example)
    Exterior
       Paint
       Chrome decor
       Windows
          Robber linings
       [4] Wheels
    Interior
       Seats
          [2] Front
          [3] Back
    Mechanics
       Motor
          [6] Cylinders
          [24] Valves
       Breaks

A transition example (task list):

 Walk the dog
    Check the weather
       [?rain] AND/OR:
          Get rain coat
          Get umbrella
       Dress for the temperature
    Get chain
    Call for the dog
    OR:
       Go through the woods
       Walk the usual track
    AND: (concurrency)
       Ensure the dog has done its "tasks"
       Ensure the dog is exercised
          [5+] throw the favorite stick
    Walk home

And this can all be done in collaboration on a wiki. States are described, processes are mapped, plans and todo-lists are forged. It's rather easy, and WOIM can accomodate for any level of complexity.

Let's go through the various parts of WOIM and all its possibilities.

A WOIM list

A WOIM list consist of one or more WOIM items.

A WOIM item

A WOIM item is a line in a WOIM list. It can have "children". Children are WOIM items indented to the right below the item.

A WOIM item consists of an optional "Starter", an optional "Type", "Content" and a "Separator" in that sequence. All the various parts of a WOIM item is described below and in the sequence they appear in an item.

Starter

A WOIM item may begin with a "Starter". A "Starter" can be either an "Identifier" or a "Multi-line Indicator".

An Identifier is a number that can be used in referring to that item. The numbering scheme is X.Y.Z. i.e. the first item in a WOIM list would be 1. (note the period after the number). The second item would be 2. etc. A child to the second item would be 2.1. and the second child of 2. would be identified as 2.2. whereas the cild of 2.2. would be 2.2.1.

An item that spans several lines must have a Starter. The second line of an item will be indented to the same level as the first with an added space in front

You don't have to use an Identifier just because an item spans several lines. You may use a "Multi-line Indicator" instead. Just prefix an item with an asterisk ("*"), and it shows that the item spans more than one line.

If you use a Starter on one item, then all the items in that same group of items on the same level/indent must also have a Starter.

Type

If it is not obvious or for clearity and strictness, prefix an item with "S:" if the item is a static or state-item (something which does not denote action). Use "T:" for a transition item (an item indicating action). The Type indicator comes after the optional starter.

Children of a certain type (state or transition) inherit their parents type unless otherwise specified.

Item content

A WOIM item must have some sort of Content. The Content can be an "Element" and/or and "Additive"

Elements

Elements are either an "Operator", a "Qualifier", a "Tag" or a "Description". Let's treat each one of these concepts.

Operator

An Operator is anything that operates on an item or a set of items. It can be any of the usual logical operators. It can also be other operators such as "EXAMPLE:", "EXAMPLES:", "CHOOSE:", "ONE OF THESE:", "IMPLIES:", "CONTINUOUS:" (makes an item or set of items run continuously), etc. An operator is written in capital letters and ends in a colon.

Qualifier

A Qualifier does as its name suggest, qualify an item. The format is "[count?condition]". The usage is best described by a few examples:

Do item 3 times = "[3]"
Do item if "the mail has arrived" = "[?the mail has arrived]"
Do item 2 times while "foo=true" = "[2?foo=true]"
Do item from 3 to 5 times while "bar=false" = "[3,5?bar=false]"
Do item 1 or more times = "[1+]"
Do item 1 or more times while "Bob is polite" = "[1+?Bob is polite]"
Do item up to 4 times only while "zoo=0" = "[<4?zoo=0]"

The question mark is read "if".

To indicate that an item is optional, use the short form "[?]".

Description

The Description is the main body, the "meat" of the item. Although an item may not have a Description, such as a line containing only the Operator "OR:", most items have a description. Many items have only a Description such as a simple todo-list.

Additives

Additives can be used alone or in combination with Elements.

An Addition can either be a "Reference", a "Comment", a "Quote" or a "Change Markup".

References

A "#" followed by the name of an item, list or anything else is a Reference. An example would be a Reference to a website such as "#http://www.isene.com/". A Reference with spaces must be enclosed in single quotation marks - "#'This is a reference'" as opposed to "#Reference".

There are three types of Reference:

A redirection or hard reference
A soft reference

An item consisting only of an Reference is a redirection. For a transition item this means one would jump to the reference and continue execution from there. If the redirect is to jump back after executing the Reference (and its children), then add another hash at the beginning such as "##ref". This makes it easy to create more compact WOIM Lists by adding a set of commonly used subroutines at the end of the list. For a state item, a Reference means one would include the referenced item (and its children) at the Reference point.

There are two special redirections for transition items:

An item consisting only of the key word "SKIP" ends the current WOIM level
An item consisting only of the key word "END" ends the whole WOIM list

If the Reference is only part of an Item, it is a "soft reference". It indicates that one would look for more information at the referred Item. An even softer reference would be to put the Reference in parenthesis such as "(#ref)", indicating only an apropos. Parenthesis is used for Comments and discussed later.

If you reference an item higher up in teh WOIM List, a simple reference to the item is all that is neede. One would refer to the Identifier or to the appropriate Content, usually the Description. It would make sense to use an Identifier for an Item if the Description is long if you would want to refer to that Item. If you refer to an Item further down the hierarchy, you would use a forward slash ("/") to separate each level (like the "path" used in a URL). If you want to refer to an item where you first need to "climb the tree" and then go down another "branch", you start the path with the highest common level and reference the path from there. An example of a reference with a path would be "#'Somewhere higher up/one level down/referred item'". You may use a unique concatenation of the path to shorten it, such as "#'Somewhere higher up/one lev.../ref...'". The three periods indicate concatenation.

Comments

Anything within parenthesis is a comment. Comments are are not executed as WOIM commands - i.e. they are not actions in a list of transition items.

Quotes

Anything in quotation marks is a quote. Like a Comment, a Quote is not executed as a WOIM command.

Change Markup

When working with WOIM Lists, especially on paper, there may come a need to mark deletion of items and to show where an item should be moved to. To accomodate for this need, Change Markup is introduced.

If "<<" is added at the end of an Item, it is slated for deletion.

To show that an Item should be moved, add ">>" at the end followed by a Reference showing to which Item it should moved below.

To indent an item to the left, add "<-". Indenting an item to the right is marked by "->". It is quite possible to combine moving and indenting an item such as moving an item and making it a child of another: ">>#ref->".

Separator

A Separator separates one Item from another. A line in a WOIM List is usually one Item, and Items are then usually separated by a "newline" (hitting the "Enter" on the keyboard). But it is possble to string several Items together on one line by separating them with semicolons.

By separating an Item by a newline and then indenting it to the right, you create a child Item. A child adds information to its parent.

If the parent Item contains a Description, a separator is read as "then". A newline and indent to the right (a children) reads "with" or "consists of". If the parent Item does not contain a Description, the separator is read as "applies to:". A couple of examples should suffice:

A kitchen
   Stove
   Table
      Plates
      Knives
      Forks

This would read: "A kitchen with stove and table with plates, knives and forks".

Time = 2010: 
   Olympic Games
   Soccer world championship

This would read: "Time = 2010: applies to: Olympic Games and Soccer world championship".

Walk the dog
   Check the weather
      [?rain] AND/OR:
         Get rain coat
         Get umbrella
      Dress for the temperature
   Get chain

And this would read: "Walk the dog consists of Check the weather consists of: If rain, AND/OR: apply to children: Get rain coat, Get umbrella, then Dress for the temperature, then Get chain". Or more humanly: "Walk the dog consists of check the weather which consists of either or get the rain coat and get umbrealla. Then dress for the temperature and then get the chain."

WOIM is self describing

Now that we have covered all the possibilities in a WOIM list, it should be obvious that WOIM could extend into a vast array of descriptions. It should even be possible to write a parser or compiler for WOIM and use it as a programming language.

Would it be possible to compact the descriptions above into a WOIM list? Yes indeed. The WOIM system is self-describing. The following list shows the legal structure and syntax of a WOIM list. It cover all you have read above:

WOIM list (2009-11-03)
   [1+] WOIM item
      [?] Starter; OR: 
         Identifier (use numbers, "X.Y.Z... ending in a period and a Space)
            [?Multi-line item] The Identifier serves as an "*"
               #1.
         Multi-line indicator = "*"
            1. Following lines are of same indent with a "space" before
             the text
            * If one item on a certain level/indent is multi-line, all items
             on the same level/indent must start with an "*" or #Identifier
      [?] Type
         OR:
            State = "S:"
            Transition = "T:"
         Children inherit Type from parent unless marked with different type
         Can be skipped when the item is obviously a state or transition
      Content; AND:
         [?] Element
            Operator
               Anything operating on an item or a set of items
               Can be any of the usual logical operators
               Is written in capitals ending in a colon
               EXAMPLES: "AND:", "OR:", "AND/OR:", "NOT:", "OPTIONS:", "IMPLIES:"
               To make the item run continuously, use "CONTINUOUS:" 
                  Item is done concurrent with remaining items
                  The operator can be combined with a time stamp tag
                     EXAMPLE: "CONTINUOUS: YYYY-MM-07:" = Do the item weekly
            Qualifier
               Format = "[Count?Condition]"; EXAMPLES:
                  Do item 3 times = "[3]"
                  Do item if "the mail has arrived" = "[?the mail has arrived]"
                  Do item 2 times while "foo=true" = "[2?foo=true]"
                  Do item from 3 to 5 times while "bar=false" = "[3,5?bar=false]"
                  Do item 1 or more times = "[1+]"
                  Do item 1 or more times while "Bob is polite" = "[1+?Bob is polite]"
                  Do item up to 4 times only while "zoo=0" = "[<4?zoo=0]"
               Optional item = "[?]"
            [1+] Tag
               Any attribute to the #Content, ending in a colon
                  Time stamp = "YYYY-MM-DD hhmmss:"
                     Shorten the format to the appropriate granularity
                  Time relations
                     Time relative to previous item = "+YYYY-MM-DD:"
                     Less than a certain time after previous item = "<+YYYY-MM-DD"
                     More than a certain time after previous item = ">+YYYY-MM-DD"
                     Time relative to next item = "-YYYY-MM-DD"
                     Less than a certain time before next item = "<-YYYY-MM-DD"
                     More than a certain time before next item = ">-YYYY-MM-DD"
                     Time relative to other item, example = "+YYYY-MM-DD#item:"
                     Other obvious time indicator may be used; EXAMPLES:
                        "+1 week:"
                        "-2 Marsian years:"
                     EXAMPLES:
                        Wait one month before doing the item = "+YYYY-01-DD:"
                        Do item less than 4 days before next item = "<-YYYY-MM-04:"
                        Wait one year and two days after item X = "+0001-00-02#X:"
                  Any other tag
                     EXAMPLES: "Location = Someplace:", "Responsible = Someone:"
            Description
               The main body of the WOIM item, the "meat" of the line
         [?] Additive
            Reference
               * A "#" followed by the name of an item, list or anything else
                EXAMPLE: Reference to a website = #http://www.isene.com/
               * A Reference with spaces is enclosed in single quotation marks
                (#'This is a reference' as opposed to #Reference)
               * There are two types of references; OR:
                  Redirection (hard Reference)
                     An item consisting only of an reference is a redirection
                        For a transition item = Jump to reference, continue execution
                           * If the redirect is to jump back after executing 
			    the reference (and its children), then add another 
			    hash at the beginning (##ref)
                              * EXAMPLE: Use this when creating subroutines at 
			       the end of the list
                        For a state item = Include the referenced item
                     An item consisting only of the key word "SKIP" 
		        ends the current WOIM level
                     An item consisting only of the key word "END" 
		        ends the whole WOIM list
                  Soft reference
                     Reference is part of an item
                        Look at referred item for info only
                     Even softer reference = have the reference in "()"
                        An apropos
               * A reference to any line upward in the WOIM list is simply a
                reference to the items #Content
               * A reference downward needs a "/" to separate each level (to
                make a "path" (like a URL) to the item
                  EXAMPLE: Reference from here to #Element/Starter/Identifier
               * For long items in a reference, concatenation can be used
                  The concatenation must be unique
                  EXAMPLE: Reference from here to #Comment/Anything...
            Comment
               Anything within parenthesis is a comment
               Is not executed as WOIM commands
            Quote
               Anything in quotation marks is a quote
               Is not executed as WOIM commands
            Change Markup; OR:
               Deletion
                  Remove the item by adding "<<" at the end of the item
               Motion; OPTIONS:
                  Move the item by adding ">>#Ref"
                     This moves the item just below the referenced item
                  Move the item one level in by adding "<-" at the end of the item
                  Move the item one level out by adding "->" at the end of the item
               EXAMPLE: Move an item as a child to Reference = ">>#Ref->"
      Separator 
         OR:
            Semicolon
               A semicolon is used to separate two WOIM items on the same line
            Newline
               Used to add another item on the same level
               Indent
                  Used to add a child
                     A child adds information to its parent:
                     A child is another regular #'WOIM item'
         Definition
            A separator and no indent reads "then:"
            [? parent contains #Description] 
	       The separator and right indent reads "consists of:"
            [? NOT: parent contains #Description] 
	       The separator and right indent reads "applies to:"

Read and re-read the WOIM list above, and you will be a WOIM master after a while. It's all there. The whole markup. You may download the WOIM definition above as a text file.

If you use VIM as an editor, you can use the vim plugin I made for creating and viewing WOIM lists. It highlights correct WOIM lists. TABs are used for indenting and SPACE folds/collapses or opens a branch/sublist. \0 collapses the whole list, \1 collapses to level 1, \2 collapses to level 2 etc. Normal collapse commands also work.

There will be more on the WOIM methodology in the book I'm writing. This book will cover many related subjects such as something I call Dynamic State Modelling (DSM - a way to apply transitions to states to arrive to new states). I will keep you posted on the progress of the book.