Firefox PHP

Quoting style, and Markdown and Real Name modules

Posted by iamback 
Quoting style, and Markdown and Real Name modules
March 18, 2007 05:23AM
Since I'm already using (extended) PHP Markdown in my Travel Blog, I was very pleased to see that Phorum comes with PHP markdown bundled. In my opinion, it provides more powerful formatting than BBcode, while avoiding any danger of invalid code being generated.

So, I turned on Markdown (and not BBcode). But after some testing I found that when quoting the default style produced by Phorum isn't quit appropriate for Markdown: it handles the code, but the "underline" causes the author's name being turned into a (big) heading. Unlike BBcode, markdown only formats the the text it's fed, so it needs to be fed something that will turn into more usable code - and a heading for an author's name within a blockquote isn't really appropriate markup.

To support this, I made a little change to /include/posting/request_first.php, as follows:

1. Old code request_first.php (version 5.1.20), lines 66-79:
    // Add a quoted version of the body for quoted reply messages.
    if ($mode == "quote")
    {
        $quoted = phorum_hook("quote", array($dbmessage["author"], $dbmessage["body"]));

        if (empty($quoted) || is_array($quoted))
        {
            $quoted = phorum_strip_body($dbmessage["body"]);
            $quoted = str_replace("\n", "\n> ", $quoted);
            $quoted = wordwrap(trim($quoted), 50, "\n> ", true);
            $quoted = "{$dbmessage["author"]} " .
                      "{$PHORUM["DATA"]["LANG"]["Wrote"]}:\n" .
                      str_repeat("-", 55) . "\n> $quoted\n\n\n";
        }

        $message["body"] = $quoted;
    }

2. My adapted code for this section:
    // Add a quoted version of the body for quoted reply messages.
    # modified MK 2007-03-18 - to make usable for formatting by Markdown
    if ($mode == "quote")
    {
        // hook for custom quoting style (used by bbcode and real_name)
        $quoted = phorum_hook("quote", array($dbmessage["author"], $dbmessage["body"]));

        if (empty($quoted) || is_array($quoted))
        {
            // MK 2007-03-18 if Markdown module is active, use approppriate quoting style
            if ($PHORUM['mods']['markdown'] == "1")     // Markdown module enabled
            {
                $author = "\n> **".$dbmessage['author'] . ' ' . $PHORUM['DATA']['LANG']['Wrote'] . ':**';
                $quote  = phorum_strip_body($dbmessage['body']);
                $quote  = str_replace("\n", "\n> ", $quote);
                $quote  = wordwrap(trim($quote), 50, "\n> ", true);
                $quoted = $author . "\n> \n> " . $quote;
            }
            // else use Phorum default quoting style
            else
            {
                $quoted = phorum_strip_body($dbmessage["body"]);
                $quoted = str_replace("\n", "\n> ", $quoted);
                $quoted = wordwrap(trim($quoted), 50, "\n> ", true);
                $quoted = "{$dbmessage["author"]} " .
                          "{$PHORUM["DATA"]["LANG"]["Wrote"]}:\n" .
                          str_repeat("-", 55) . "\n> $quoted\n\n\n";
            }
        }

        $message["body"] = $quoted;
    }

Now, apart from using Markdown, I've also installed Maurice's Real Name module which similarly seems to be "ignorant" of the existence of Markdown. ;) To keep my write-up in one place I'm going to show what I did to that module here, and then attach my change to the Real Name thread. (I bit clumsy, but I coudln't see how else to combine discussing changes for one module in both release code and another module...)

So, first of all, Real Name needs to know about a "Markup quoting style" in the settings. That's simple enough:

1. Real Name settings.php
//...
    $quotespec = array(
        "disabled" => "Disable the quote feature",
        "built-in" => "Enable default Phorum style quoting",
        "bbcode"   => "Enable BBcode style quoting",
        "markdown" => "Enable Markdown style quoting",		# added MK 2007-03-15
    );
//...

Next, since the Real Name module "pre-empts" creating the quote from request_first.php (like BBcode does), it needs a corresponding change as that in request_first.php. All we need to do for that is add a little extension to the mod_real_name_quote() function, as follows:

2. Real Name real_name.php, mod_real_name_quote() function:
function mod_real_name_quote($array)
{
    $PHORUM = $GLOBALS["PHORUM"];

    // No quote function configured.
    if (! isset($PHORUM["mod_real_name"]["quote_type"])) return $array;

    $username = $array[0];
    $message  = $array[1];

    // Handle BBcode style quoting.
    if ($PHORUM["mod_real_name"]["quote_type"] == "bbcode") {
        //... as before
    }

    // Handle default Phorum style quoting.
    elseif ($PHORUM["mod_real_name"]["quote_type"] == "built-in") {
        //... as before
    }

    # added MK 2007-03-15
    // Handle Markdown style quoting.
    elseif ($PHORUM["mod_real_name"]["quote_type"] == "markdown") {
        $displayname = mod_real_name_rewrite("username2displayname", $username);
        $author = "\n> **" . $displayname . ' ' . $PHORUM['DATA']['LANG']['Wrote'] . ':**';
        $quote  = phorum_strip_body($message);
        $quote  = str_replace("\n", "\n> ", $quote);
        $quote  = wordwrap(trim($quote), 50, "\n> ", true);
        $quoted = $author . "\n> \n> " . $quote;
        return $quoted;
    }
    # end added

    return $array;
}

So now Phorum handles quoting with Markdown just nicely, with or without the Real Name module.

-- Marjolein Katsma * Marjolein's Travel blog * Marjolein's Travel Forum
The first condition of understanding a foreign country is to smell it.
-- Rudyard Kipling
Re: Quoting style, and Markdown and Real Name modules
March 18, 2007 08:02AM
Fixing things for modules in the core is wrong. If markdown needs a different quoting method, then the markdown module has to be extended with a quote hook. The real name module would have to be patched to override the quote hook for the markdown module in that case.

Conclusion: We won't add this patch to the core code.


Maurice Makaay
Phorum Development Team
my blog linkedin profile secret sauce
Re: Quoting style, and Markdown and Real Name modules
March 18, 2007 05:25PM
Quote
mmakaay
Fixing things for modules in the core is wrong. If markdown needs a different quoting method, then the markdown module has to be extended with a quote hook.
Well, it seems you somewhat misunderstand the nature of the Markdown module. All it does is interpret source in its own syntax and produce valid XHTML from that. That's what it was designed to do. It's not designed to generate markup, and I'm pretty sure it never will. Read the docs. :)

If Phorum comes with the Markdown module then it should work with the Markdown module. It's a completely different thing from BBcode; I understand not many people actually use Markdown - but it doesn't generate quoting, and the quoting style Phorum generates results in unsemantic markup. (So why is it included at all when Phorum doesn't work properly with it? Are others just patching without posting here? I'm simply sharing my solutions...)

You could of course request Michel Fortin to extend Markdown to generate a quoting style - but since it's basically a port of John Gruber's Perl module, I doubt he'd be eager to do that.

The alternative would be for the Phorum authors to extend the Markdown module to produce a quote, like the BBcode module is doing.

Quote

Conclusion: We won't add this patch to the core code.
So, will you extend Markdown with a quote hook? Or ask Michel Fortin to do so?

To cut a long discussion short - for those who are just interested in using Markdown, my solution works and they can get it from here. But I agree it's "wrong" to patch the core (except when it needs to be patched, of course ;)), so a "better" solution is certainly welcome - and my solution might give a start. The fact remains that currently there's a mismatch and it needs to be fixed to be able to properly use Markdown.
Re: Quoting style, and Markdown and Real Name modules
March 18, 2007 06:38PM
Quote

Well, it seems you somewhat misunderstand the nature of the Markdown module. All it does is interpret source in its own syntax and produce valid XHTML from that. That's what it was designed to do. It's not designed to generate markup, and I'm pretty sure it never will. Read the docs. :)

I don't misunderstand anything here. I know what markdown was designed for. But the module *is* not markdown, it *implements* markdown. That is a different thing. Because it's a Phorum module implementation, it should also take care of fixing things that go wrong. But you already have seen that light in your posting :)

Please put up a trouble ticket for this, requesting to implement a quote hook for the markdown module.


Maurice Makaay
Phorum Development Team
my blog linkedin profile secret sauce
Re: Quoting style, and Markdown and Real Name modules
March 18, 2007 09:33PM
Quote
mmakaay
Please put up a trouble ticket for this, requesting to implement a quote hook for the markdown module.

Done: [www2.phorum.org] - with reference to this thread

BTW, there is no "version 5.1.20" defined yet - update your Trac! ;-)
Re: Quoting style, and Markdown and Real Name modules
March 18, 2007 11:50PM
See changeset 1649. Sorry, there are some ending newline strips in that change too.

Brian - Cowboy Ninja Coder - Personal Blog - Twitter
Re: Quoting style, and Markdown and Real Name modules
March 19, 2007 05:09AM
Brian:
Looks good - added a comment to the ticket. Thanks!

What's the convention here - do I close it or do you?

Somewhat off topic:
BTW, I also have another little extension to markdown so forum descriptions can be formatted; interested? This does require extra code hooks. (Even though it looks like "index" can be used, I got interference because we can't determine in what order module's hook functions are executed - so I ended up with an extra hook and a small change to the listmoderators module. There's another hook needed in common: "post_user" isn't logical when you're working on a forum description though it might work.) Works nicely, though, and you can for instance use a link in a forum description this way; I think that would work with BBcode as well...
Re: Quoting style, and Markdown and Real Name modules
March 19, 2007 05:58AM
The general policy on the forum descriptions is that the admin which sets up the forums, uses HTML code directly to format the code. So a link would go in there as a standard <a href="">...</a>. Feel free to release a separate module that formats the forum descriptions using markdown.

An extra hook is not an option. The "index" hook is the one that is intended for doing things like this. Module ordering is a problem. 5.2 will be much better in this field. There you can specify module priorities, which can be used to reorder the way in which the hooks are run. For 5.1, you can only use some hackery to get the ordering right. If you want an example of how to modify module ordering, check out this thread where I provided some code to always push bbcode to the end of the module list.


Maurice Makaay
Phorum Development Team
my blog linkedin profile secret sauce
Re: Quoting style, and Markdown and Real Name modules
March 19, 2007 07:10AM
Quote
mmakaay
The general policy on the forum descriptions is that the admin which sets up the forums, uses HTML code directly to format the code. So a link would go in there as a standard <a href="">...</a>. Feel free to release a separate module that formats the forum descriptions using markdown.
Sure I know that's possible, but I like to use consistent formatting - besides Markdown is more compact and readable than HTML.

Quote
mmakaay
An extra hook is not an option. The "index" hook is the one that is intended for doing things like this. Module ordering is a problem. 5.2 will be much better in this field.
I know I should use the index hook - but I've tried endless variations but could not get both listmoderators and Markdown to play together nicely. (listmoderators needs to be tweaked a little anyway because it's now injecting unstructured HTML).

Quote
mmakaay
There you can specify module priorities, which can be used to reorder the way in which the hooks are run.
I can't wait :) I know setting priorities is in the works - it's badly needed.

Quote
mmakaay
For 5.1, you can only use some hackery to get the ordering right. If you want an example of how to modify module ordering, check out this thread where I provided some code to always push bbcode to the end of the module list.
I'll investigate - what can be done for BBcode may be possible for Markdown as well. I'll also see if the "post_user" hook in common.php can be leveraged - but having a hook that's intended for "forum" stuff instead of "user" stuff is cleaner IMO; I always try to find the most logical place rather than "can be used", and there might be a small efficiency gain as well in using a smaller data set.

N.B. I may not have much time left for now - I'm soon leaving on vacation and just need a working forum before I go; I'll pick up again when I'm back at least. I've been trying to share as much of my work (hacks, tweaks and mods) before I switch into full "preparation mode". ;)

-- Marjolein Katsma * Marjolein's Travel blog * Marjolein's Travel Forum
The first condition of understanding a foreign country is to smell it.
-- Rudyard Kipling



Edited 1 time(s). Last edit at 03/19/2007 07:10AM by iamback.
Re: Quoting style, and Markdown and Real Name modules
March 19, 2007 08:36AM
Quote
iamback
I know setting priorities is in the works - it's badly needed.

In fact, it's not in the works. It's already finished. But it will only be in 5.2. One more reason to upgrade when that tree goes stable.

Quote
iamback
I know I should use the index hook - but I've tried endless variations but could not get both listmoderators and Markdown to play together nicely. (listmoderators needs to be tweaked a little anyway because it's now injecting unstructured HTML).

If you use the "list" hook and make sure that your mod gets run as the very first one, then there should be no need to modify other modules for making them work together. This is always to goal to aim at: make modules work fully stand-alone and don't let them force other mods or phorum core into patches for playing together.


Maurice Makaay
Phorum Development Team
my blog linkedin profile secret sauce
Sorry, only registered users may post in this forum.

Click here to login