| At line 1 added 110 lines |
| == List markup features == |
| Since listing all the possible markups seems to result in a kind of exponential explosion, with a lot of repeated pros and cons and not really clean view, here are the single "features" of a possible list markup discussed: |
|
| == Bullet character == |
| * Hyphen |
| * Asterisk |
| * Other |
|
| The hyphens and asterisks are by far the most popular characters for making lists. Unfortunately, they are also popular for other markup. |
|
| The use of asterisk can introduce conflicts with bold markup. |
|
| The use of hyphen introduces conflicts with various casual uses of hyphens, dashes, minus sign and horizontal line. |
|
| Use of different characters, like "+", "~", ".", "@" or "%" is usually totally new and counter-intuitive in wikis. It can also introduce problems with various [[Keyboards]] and non-latin scripts. |
|
| === Indentation === |
| * Mandatory |
| * Optional |
| * Forbidden |
|
| Some wikis //require// lists to be indented and can disambiguate them from other markup in this way, providing improved readability at the same time. These engines often also use indentation for denoting nesting level of lists, but that's discussed further. |
|
| Some wiki //forbid// indenting lists, as indented text is reserved for pre blocks in them. |
|
| Seems like the best bet is to //allow// indenting, but not require it -- this way Creole can be implemented in MixedMode in both families of wiki engines, and used comfortably by both groups of users. |
|
| === Space after bullet === |
| * Mandatory |
| * Optional |
| * Meaningful |
|
| An alternative method of disambiguation and providing visual clues is a space after the list bullet character(s). This has the benefits of indentation without the drawbacks of varying interpretation in different wiki engines. |
|
| Requiring the space //only// when there is an ambiguity is a loosening of this rule that gives up visual clarity on behalf of "user freedom". The ambiguity with second-level lists and bold remains, unless it is accounted for in a different way. |
|
| Not ignoring the space and treating it as a part of the list item text seems to have no benefits. |
|
| === Nesting indication === |
| * Repeated bullet |
| * Repeated bullet with spaces |
| * Indentation with spaces/tabs |
| * Indentation with other characters |
| * Changing bullet character |
|
| The simplest way to indicate a change in nesting level of list is to repeat the bullet character. This is both intuitive for a "list inside list" markup, and provides a visual clue in form of indentation of the nested lists. The drawback is that it conflicts with other markups that use repeated characters, like the bold text markup. |
|
| Another method that was observed in the wild but is not used in any wiki engine is to repeat the list characters but separate them with spaces. This provides stronger indentation and is also intuitive as "list in a list", but is much less traditional in context of wikis. It requires more typing but doesn't conflict with bold or similar markups. |
|
| Indentation is the most natural way of indicating nesting and it is used by some wikis. Creole rejects it because of invisible markup and the need to count the spaces at least in some cases. It also conflicts with wiki engines that forbid list indenting. |
|
| A variation on the indenting method is to use a visible character like ".", ":" or "~" to indent the list. The result is pretty ugly and not intuitive, but works. Possible conflicts if the character is used for other markup. |
|
| Finally, some wiki engines (and text documents foundi n the wild) use a technique of changing the list kind and/or bullet character to indicate another, nested list. This technique limits the maximum nesting level and can lead to use of very strange bullet characters. |
|
| == Beginning and end of the list == |
| * Explicit, parenthesis-like notation |
| * List must begin with first-level item |
| * List ends with non-list line |
| * List ends with un-indent |
| * List ends with empty line |
|
| Some very simple wikis, like WyPy, introduce parenthesis-like notation for lists that is translated more or less directly into HTML. This resolves all ambiguity and also provides means to mark nesting. Similar approach is used in LaTeX and other markup languages. Wikis usually don't adopt it, as it is too complicated and not humane. |
|
| Requiring that the list starts with a first-level item (and ignoring all other lists) is a technique for partial disambiguation of list from other markup. It requires context to understand the code and makes moving parts of lists harder. It doesn't resolve the ambiguity completely if the conflicting markup is also allowed inside lists. |
|
| Simple implementations of lists only allow single-line list items, and thus any line that doesn't start with a bullet signifies end of the list. |
|
| Introducing multi-line list items requires devising a different way to mark their end -- wikis that use indentation for list can treat the first not-indented line as the list's end. |
|
| When indentation is ruled out, the lists can be terminated in the same way that paragraphs are -- by leaving at least one empty line. |
|
| == List kind conflicts == |
| * Ignore conflicts |
| * Conflicts create new nesting level |
|
| It is possible to include several list items of different kinds on the same nesting level -- but this usually cannot be rendered (and even if it could, the semantics and aesthetics are disputable). Therefore the wiki needs to handle these conflicts. One way is to ignore the kind of any item that doesn't start a (sub)list -- this way a lone numbered list item in a bullet list would be considered a normal bullet list item. This is usually not what the user meant, though. |
|
| Another approach is to make the item into another sublist, so that it becomes nested in the list it didn't fit into. This makes simple character counting inappropriate for determining nesting level -- the markup becomes context dependent. |
|
| == Nesting conflicts == |
| * Don't treat as list item |
| * Only use the maximum number of list characters |
| * Use all list characters but limit the level |
| * Introduce empty lists |
| * Disregard ordering of nesting levels |
|
| It is possible to create list items with nesting level higher than is possible on their position -- for example, a third-level list item in a single-level list. The simplest method is to just don't treat it as a list item, and allow the user to notice the mistake and correct it. |
|
| Another way is to only consume as many list characters from the beginning as the maximum nesting level possible, and leave the others -- as indication of error or for conflicting non-list markup. |
|
| A variation on this is to consume all the list characters, but still make the sublist nested as far, as possible in current situation. |
|
| The most forgiving way is to introduce empty lists before the offending list element, so that required nesting level is possible. This can introduce a number of "dangling" bullets in HTML and is sure to be abused by the users to get "interesting patterns". |
|
| Yet another way is to treat the nesting level indicated in the list item as just an unique identifier for a sublist -- every new identifier creates a new nesting level, while items with existing nesting levels will be placed in corresponding sublists. This may lead to a situation where a "3-star" list item is in a sublist of a "4-star" list item. |
|
| == Escaping == |
| * Escape list markup |
| * Escape list characters |
| * Disappearing markup |
|
| One technique that makes it easier to live with ambiguity is escaping. One can use special markup to show that the construct is not supposed to be treated as list, but as the other, conflicting markup instead. This is a special case introduced specially to deal with the problem. |
|
| Another, less special approach is to introduce a generalized escape character for escaping single characters, not whole markups. The problem with it is that once you escape, for example, and asterisk, so that it doesn't become part of a list, you also prevent it from becoming part of bold markup -- thus escaping is only useful in cases where the conflict is with some common use of the character. |
|
| Finally one can introduce some markup that is not rendered to "break" the list markup -- something like C2:SixSingleQuotes or, in case of Creole, {{{{{{~}}}}}}. This disables list markup nicely but is counter-intuitive and ugly. |
|
| ---- |
| ---- |
.