Topic: [1.3] A better help page administration

I never paid that much attention to it, but I just made a small mod for one of my forums and was?rightfully?requested to describe it in the help section.

Ouch. It hurts.

To do that, I must (in 1.2): know PHP, know HTML; fiddle with the language files, the PHP file...

So, it would be nice to have at least a simple, neat, fast tool for help editing & customizing in 1.3. There are two simple options to do that, in fact more simple than the 1.2 way:

1. Give the admin a HTML textarea, populated with the default localized help (in one string, pleeease). Let him edit it the way it wants. It's quite simple to code for the Pun's dev team; but not very user friendly especially if the admin doesn't speaks fluent HTML. Anyhow, if this is done this way, don't forget the hook to plug an external parser here (hmmhhmmmhh... Textile...).

2. Same as 1), but make it both bbcode and HTML, so that at least the non-geek admin can use bbcode to edit it. Again, don't forget the hook for an external parser smile And I guess it will need some kind of [nop][/nop] special bbcode, with the enclosed string not parse by bbcode and escaped to avoid html; and maybe some kind of header string to divide sections and place anchors.


There are more complex way of doing it, but I can't think of one that's in the PunBB's spirit, simple, powerful, yet easy to use, and with a good added value over the two above. If you can...


There's also room for improvement in the help's content area, but I will give a hand at that when 1.3 is in beta.

Re: [1.3] A better help page administration

I don't think that would work very well (I'm assuming "populated with the default localized help" means "a copy of the HTML for the page"). As you pointed out, there are language issues, there is PHP involved in some cases, etc. I don't think you can reduce the existing help file into an HTML page for editing.
However, adding a hook at the end of the page and creating an extension that allows you to add "entries" to the existing help would certainly be possible.

Re: [1.3] A better help page administration

I don't see where the PHP is needed in that kind of setup.

At the core, what's the difference between the help page and, for example, a forum's post? As far as I can see, only permission and the ability to use specific bbcodes and/or html in it (for headers, code example, anchors, etc.).

The basic admin would still have nothing to do, the appropriate localization would be loaded (the "post" would be populated with it) when the forum is installed and that would be it. The average/a little more advanced admin would simply have to edit the "post"n as any other post, only with more freedom. And the advanced admin could do his own trick.

The only kind of code I think would be needed is for the smiley list, to generate automatically the correct and up-to-date array of images|meaning|code. But that could be done with a simple string replacement, something like [smiley_list] that would be replace with the smiley list.

Adding a simple hook at the end still require of the admin to know PHP, and wouldn't be enough for anything but "stand alone" extension. If for example you add a new bbcode tag, you need to add something in the bbcode section of the help. If you change a bbcode working, or even delete it, you need to edit that section. And so on.

Re: [1.3] A better help page administration

On the subject of languages, what happens if the user chose a different UI language than the default for the board?

5 (edited by Jérémie 2007-06-18 22:08)

Re: [1.3] A better help page administration

Good point. So it's not one "area" or "post" that's needed, but one by language. It's default content would be the standard help (localized, as now). But the "post" structure of the help would mean the admin can edit, customize, expend, rewrite each and everyone of them.


Overall, the thing with the current system is that you can't edit it at all without at least some PHP knowledge (a very minimal knowledge is not enough, it's a little more than that). And being able to customize, rewrite, edit the forum's help is not an advance feature; imho it's a very very basic one.

If what I propose isn't clear, I can try to clarify it.