Inline comment formatter

Last edited by JavaWoman:
Modified links pointing to docs server
Mon, 28 Jan 2008 00:11 UTC [diff]

See also: FormattingRules


I've modified formatters/wakka.php so as to recognize a new formatter for inline comments.
When adding inline comments, we used to adopt a combination of indents and note markup, which produces hardly readable discussions and frequent inconsistencies.

Syntax
The new InlineCommentFormatter introduces a simple syntax, similar to that of unordered lists.
To produce an inline comment use & preceded by one or more tabs (or ~).
To append a subcomment to an existing comment use the above syntax with an extra tab (or an extra ~) - much as you append a subitem to an existing list item.

~& Comment
~~& Subcomment
~~~& Subsubcomment

gives:



Example

Note:
To correctly display the following example you need to revert to the default wikka skin (TestSkin). Otherwise, you will just see an ordinary list.

Here's how it looks like:




Installation

This feature is part of WikkaWiki as of version 1.1.6.0. If you wish to apply it to an older version without upgrading to the latest version, follow these instructions:

1. Modify formatters/wakka.php

You first need to modify the wakka formatter in three different places.

A) original

        // indented text
        elseif (preg_match("/\n([\t,~]+)(-|([0-9,a-z,A-Z,ÄÖÜ,ßäöü]+)\))?(\n|$)/s", $thing, $matches))


A) modified
        // indented text
        elseif (preg_match("/\n([\t~]+)(-|&|([0-9a-zA-ZÄÖÜßäöü]+)\))?(\n|$)/s", $thing, $matches))


B) original
            elseif ($newIndentType == "-") { $opener = "<ul><li>"; $closer = "</li></ul>"; $li = 1; }
            else { $opener = "<ol type=\"". substr($newIndentType, 0, 1)."\"><li>"; $closer = "</li></ol>"; $li = 1; }



B) modified
            elseif ($newIndentType == "-") { $opener = "<ul><li>"; $closer = "</li></ul>"; $li = 1; }
            elseif ($newIndentType == "&") { $opener = "<ul class=\"thread\"><li>"; $closer = "</li></ul>"; $li = 1; } #inline comments
            else { $opener = "<ol type=\"". substr($newIndentType, 0, 1)."\"><li>"; $closer = "</li></ol>"; $li = 1; }



C) original

    "======|=====|====|===|==|".
    "\n([\t,~]+)(-|[0-9,a-z,A-Z]+\))?|".
    "\{\{.*?\}\}|".


C) modified

    "======|=====|====|===|==|".        # headings
    "\n([\t~]+)(-|&|[0-9a-zA-Z]+\))?|".         # indents and lists
    "\{\{.*?\}\}|".                             # actions



2 Add a new class to your stylesheet (default: css/wikka.css)

ul.thread {
    list-style-type: none;
    border-left: 2px #666 solid;
    padding-left: 10px;
    margin: 5px 0px;
}

ul.thread li {
    color: #333;
    font-size: 11px;
}


Suggestions for improving the inline comments style are welcome :)



Alternate styles

Here's a couple of ideas...

1. thin borders

ul.thread {
    list-style-type: none;
    border-left: 1px #666 solid;
    padding: 0px 5px;
    margin: 5px 0px;
}

ul.thread li {
    color: #333;
    font-size: 11px;
}


gives



2. graded thick borders

/* darker border for main comments */
ul.thread {
    list-style-type: none;
    border-left: 10px #BBB solid;
    padding: 0px 5px;
    margin: 5px 0px;
}

ul.thread li {
    color: #333;
    font-size: 11px;
}

/* lighter border for subcomments, subsubcomments etc. */
li ul.thread {
    border-left: 10px #DDD solid;
}


gives




3. layered sheets

ul.thread {
    list-style-type: none;
    border-left: 2px #666 solid;
    border-top: 2px #666 solid;
    padding: 0px 5px;
    margin: 5px 0px;
}

ul.thread li {
    color: #333;
    font-size: 11px;
}


gives



4. boxes

ul.thread {
    list-style-type: none;
    border: 2px #666 solid;
    padding: 0px 5px;
    margin: 5px 0px;
}

ul.thread li {
    color: #333;
    font-size: 11px;
}


gives




CategoryDevelopmentFormatters CategoryLayout
Comments
Comment by ChristianBarthelemy
2005-01-05 17:46:45
I like it - It becomes clearer for the reader - even better if you encapsulate the whole thread between << thread <<
Comment by DarTar
2005-01-05 17:54:34
In this case I'd suggest you customize your CSS and include the properties you like of the "floatl" class in the "thread" class.
And, of course, this proposal is not meant to replace the parallel development of a forum plugin and/or threaded comments.
Comment by GmBowen
2005-01-05 17:57:12
A nice contribution DarTar....provides some real flexibility and addresses one of the issues we've been talking about. Well done.
Comment by JavaWoman
2005-01-05 22:11:59
I like this very much! Dartar pointed me to a similar example on anotehr site a while ago and while I liked the idea I didn't like the implementation. This is the same idea, but implemented much better: markup is very easy and fits right in with already-known Wikka markup, and the formatting as a list makes much more sense (semantically, and structurally) than what the other site was doing: marking up as nested divs. Another good point is that the list markup makes sense (and is readable) even without any styling.

A very elegant solution!
Comment by JavaWoman
2005-01-06 10:34:56
For those who like to experiment: I've now updated my own stylesheet here (javawoman.css) with a set of rules for this. You could use it, or make a clone of it - see TestSkin.
Valid XHTML :: Valid CSS: :: Powered by WikkaWiki