List Markup Alternatives

This is version 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 . It is not the current version, and thus it cannot be edited.
[Back to current version]   [Restore this version]

Suggestion: Give a brief overview plus the pros and cons and link to a more comprehensive external specification (if any).

Hyphen list proposal #

HyphenListMarkupProposal

Whitespace, single dash, single plus #

Gripes with current proposals:

• Current standard: having to escape the (quite common) "bold at the beginning of a line" is bad.
  • So: Should my proposal prove inadequate (or unpopular ;-) I'm very much in favor of this proposal. Still: Strange escaping rules should be avoided at all costs.
• Repeating the bullet character (vs. whitespace): I am not sure that we are not making common things (at most 2 indentation levels in lists) harder while making uncommon things (more than 2 nesting levels) easier.

I'm in favor of the following syntax (hear me out, I'll consider anti-whitespace arguments)

- one (ul)
  - one.one
  - one.two
- two (ul)
  + two.one (ol)

Advantages:

• Near WYSIWYG: Conforms to common plain text practices, looks a lot like the rendered output.
• Uniformity: ordered and unordered lists have similar "bullets".
• Compared to multiple dashes / no whitespace:
  • No clash with hr
  • No clash with signatures
• Compared to the current standard:
  • No clash with bold at the beginning of a line (which is not uncommon).
• Works quite well in Python and Haskell. This point is only partly humorous, as wiki markup is a semi-formal language and does have some rigid rules, so the same kind of usability rules apply here as they do to programming languages.

Potential disadvantages:

• User has to count spaces: I would count relative indentation (not the absolute amount of spaces), then this is only a problem if one wants to continue a second-level list (see below). But: users look for visual feedback after entering wiki text, anyway, and will be very obviously alerted to the problem then.

- first level
  - second level (counting is not a problem: we just have MORE spaces than the line above)
    - third level 1
    - third level 2 (counting is not a problem: it is the same as the line above)
  - second level continued (here we have to count...)

• Confusing tabs and spaces: disallow tabs.
• Clash with negative numbers: make space after hyphen mandatory. This is how humans disambiguate here, too:

-333
- An item (the above does not look like an item)

-- AxelRauschmayer, 2007-02-28

Repeated asterisk, with "smart" disambiguation #

A list is marked with a single asterisk * or hash # on the beginning of a line, followed with any other character and optionally preceded with any number of spaces or tabs. Subsequent list items are marked with any combination of asterisks and hashes on the beginning of a line, optionally preceded by any number of spaces or tabs. The last character of the combination denotes the kind of list: asterisk means bullet lists while hash means numbered list. The length of the combination defines the nesting level of particular list item -- the more characters, the more nested the list is. If the combination is too long for the number of lists already introduced, the maximum possible nesting level is assumed. If the type of list item (bullet/numbered) doesn't match the type of list on its level, a new nesting level is created for the item. The list ends as soon as there is a line that doesn't start with a combination of asterisks and hyphens.

Note: This is the markup used in Creole 0.5 and before.

Example #

Some text that is not a part of the list.
 *The first bullet list item,
     * The second bullet list item,
##The first numbered sublist item,
*#The second item of the numbered sublist,
 ****A first item of bullet subsublist
***Second item of the subsublist
 **# A firts item of a numbered subsubsubllist
#First item of a numbered sublist
#*A bullet subsublist
This is not a part of the list anymore.

Advantages #

• Uses the character that is most popular for lists in existing wiki engines
• Accepts arbitrary nesting and spacing, leaving to the users the decision about how to best format the list for readability
• At least the basic, first-level list will work in MixedMode in most wiki engines
• Even wikis that use indentation for marking list nesting can adapt this technique (in addition to their native markup)
• There is no such thing as "error" or "bad input" -- every input is rendered in some way
• Moving the list items around by copy-pasting (or cut-pasting) is pretty straightforward, even between different lists or pages -- except for the first list item, removal of which can cause the list to stop being parsed as list.

Disadvantages #

• There are several cases when there is ambiguity between the list markup and the markup for bold text
• The research on WikiPedia indicates that in over 50% of cases users will not format the list for readability if only the rendering is correct -- thus the lists become unintelligible easily
• The markup is context-dependent -- user cannot tell if it's bold text or list by just looking at a single line
• Allowing line breaks in list items leads to some additional ambiguities and potential spots for user mistakes
• There are additional cases of ambiguity if the underlying engine uses on MixedMode the hash and asterisk characters for other markup -- like single asterisks for emphasizing single words
• In MixedMode, engines are very likely to have a much simpler algorithm for recognizing lists, that must be dropped in order to implement Creole

Repeated asterisk, simple #

Any line that starts with optional spaces or tabs followed by a combination of asterisks and hashes is considered a list item. The last character in the combination of the first item in given (sub)list denotes the kind of list. The number of characters in the combination denotes nesting -- if it's too high for existing lists, the maximum possible nesting is assumed.

Example #

Some text that is not a part of the list.
 **The first bullet list item,
     * The second bullet list item,
##The first numbered sublist item,
*#The second item of the numbered sublist,
 ****A first item of bullet subsublist
***Second item of the subsublist
 **# A third item of a bullet subsubllist
#Third item of the bullet list
#*A bullet sublist
This is not a part of the list anymore.

Advantages #

• Uses the character that is most popular for bullet lists among existing wiki engines
• Items can be freely moved around.
• The nesting rules are simple to explain and implement, as there is no creation of new nesting level when the list kinds don't match.
• Whitespace is not meaningful, which helps implementing MixedMode in wikis that use indentation
• No "wrong" or "erroneus" input
• Implementing multi-line list items doesn't introduce additional conflicts
• The basic, first-level lists work as intended in most wikis
• The markup is not context-dependent, every line stands on its own

Disadvantages #

• Conflicts with any markup that uses asterisks or hashes and can appear at the beginning of a line -- in particular, with Creole's bold markup
• To nest bullet list inside numbered list (or vice versa), you need to explicitly make one of them of higher nesting level
• Readability of the code is entirely up to the user, research shows that users don't make the code readable if they don't have to.
• Items with the same number of asterisks in front can end up in different levels of nesting.

Repeated asterisk, with space #

Any line that starts with optional spaces or tabs, followed by a combination of asterisks and hashes, followed by at least one space or tab is considered a list item. The kind of list is determined by the last character in the combination of the first item in the (sub)list. The nesting level is determined by the number of characters in the combination. If this number is too high for existing lists, the maximum nesting level possible is assumed.

Example #

Some text that is not a part of the list.
 ** The first bullet list item,
     * The second bullet list item,
## The first numbered sublist item,
*# The second item of the numbered sublist,
 **** A first item of bullet subsublist
*** Second item of the subsublist
 **# A third item of a bullet subsubllist
# Third item of the bullet list
#* A bullet sublist
This is not a part of the list anymore.

Advantages #

• Uses the character that is most popular for bullet lists among existing wiki engines
• Items can be freely moved around.
• The nesting rules are simple to explain and implement, as there is no creation of new nesting level when the list kinds don't match.
• Indenting is not meaningful, which helps implementing MixedMode in wikis that use indentation
• No "wrong" or "erroneus" input
• Implementing multi-line list items doesn't introduce additional conflicts
• The basic, first-level lists work as intended in most wikis, except for when the users didn't put a space
• The markup is not context-dependent, every line stands on its own
• There are no conflicts with markups using asterisks or hashes, except for some very rare corner cases

Disadvantages #

• To nest bullet list inside numbered list (or vice versa), you need to explicitly make one of them of higher nesting level
• Items with the same number of asterisks in front can end up in different levels of nesting.
• The indenting of list, which is arbitrary, may be misleading and impact readability
• Forces engines to use stricter rules for lists in their MixedMode