PmWiki | Cookbook / PublishFAQ

Summary: Supplied with a raw list of Qs and As, it outputs a formatted FAQ complete with TOC

Version: 1.0rc - initial release

Prerequisites: PmWiki 2.1

Status: RC

Maintainer: Octocias

Categories: Layout

Questions answered by this recipe

How can I automate the process of FAQ creation and maintainance?

Description

Creating and managing any compilation of data is a tedious task and a waste of time. FAQs are not exempt. This script takes a raw list of Qs and As, and it outputs a formatted FAQ list complete with a table of contents which automatically point to the Q & A pairs further down the page. Each Q&A also links back to the top for fluid navigation.

Usage & Format

All you need to insert a formatted FAQ is a page with the data and it's inclusion using the following format:

: (:PublishFAQ <faq data page>:)

FAQ format:

: [TOC-Style: <div name>:] (optional)
: [Q-Title: <question title text>:] (optional)
: [A-Title: <answer title text>:] (optional)

followed by any number of pairs in the following format:

[Q: <Question text>:]

[A: <Answer to the preceding question>:]

: .
: .
: .

Installing

Download oct-publishfaq.php Δ and copy it to your cookbook folder. Install by adding to config.php:

: include_once("$FarmD/cookbook/oct-publishfaq.php");

About the div name

The look you see in the demo page is achieved by the following code extracted from my skin's css:

div.faqtoc 
{ 
	border: 1px rgb(140, 172, 187) solid; 
	padding:0px;
	background: rgb(249, 251, 255);
	width: 100%;
	visibility: visible;
}

FAQ Example page(s)

To see it in action, visit Octocias' FAQDemo.

Release Notes

2006.04.15 - 1.0rc: first released into the wild.

Comments

I would very much like to use this recipe, but I cannot get it to work. I looked at the example and copied and pasted all the variations and combinations I could think of, but it still won't work. This is the error message I get:
PublishFAQ: The number of questions and answers are zero or not equal to eachother. Click to edit or view the data.

This is the code I have on the edit page:
(:publishthisFAQ:) [Q-Title: Questions:] [A-Title: Answers:] [Q: How do I get my question answered? :] [A: The quickest and best way is to An alternative way is to leave your question on the Questions page. :] [Q: Where can I get help with PmWiki? (This is a pretty vague question!):] [A: See this FAQ. :]

Could you please include a little more detailed explanation of how this thing works and maybe verify that the script file is up-to-date and accurate (especially since your example is more updated than the script here)? ~Jennifer Humphrey

Yup, broken here too. Marc, 8 June 06

Same here... broken for me... I tried applying the updates the author suggested at the bottom... still can't make it work. Anybody figure out how to make a working copy of this? Or, it looks like the author has an updated version on his/her site... any way to download that? Frank G. 10/4/2006

I think you have to do it like (:publishFAQ Main.FAQData:) making sure yourefer to the page where the actual FAQ data resides ~bouton June 9, 06

GmB-(September 26, 2006.) I had to create two pages to get it to work. Put all your questions and answers on one page, then on your main faq page put in the tag (:publishFAQ Main.FAQ:). Main.FAQ is just an example, type in your faq page. Then as long as all the questions and answers are on the page you are pointing to you should be fine. Oh don't forget to remove the <>.

I've got a workaround for me that may help others. Basically, people want the page with the FAQ to be the same page as the data page. The author provides some code fixes below, but I couldn't get them to work.

My workaround is to pass in the same pages name as the parameter. For example, let's say you have your FAQ page at Main.FAQ and you also want your data to reside on the same page. Put (:publishfaq Main.FAQ:) at the top of the page and your FAQ data below it. Now this has the side effect of all this nasty stuff showing up below the FAQ output. No problem, simply wrap your data in (:if !true:) and (:ifend:). This will still allow the data to show up to the recipe, but hide it from view. A more complete example:

(:publishfaq Main.FAQ:)

(:if !true:)
[Q-Title: Questions:]
[A-Title: Answers:]
[TOC-Style: faqtoc:]

[Q: How do I add to the FAQ as I figure out stuff? :] [A: Edit this page and the syntax should be obvious. Please add to it and make the FAQ grow!! :] (:ifend:)

Works well for me.

Frank G. 10/4/2006

Contributors

^[Octocias] - Thanks to Kaleb Kajero & Nik Makepeace (no PmWiki profile)

Small Revision

I didn't like it too much that it was necessary to define the name of a page where the FAQ should be displayed because very often this is the same as the data page itself. I revised the oct-publishfaq a little bit and now it is possible to either define a page or leave it blank in order to use the same.

(:publishfaq:)... - displays the FAQ on the same page (:publishfaq Group.Page:)... - displays the FAQ on the page which is defined within the tag.

Please note. This is rather quick and dirty. Therefore (:publishfaq :)... is not working at the moment. you might consider this as a bug but for me it works. :-)

Changes made in oct-publishfaq.php

Before:

Markup('publishfaq', '<[[<<]]', 
        '/\\(:[p|P]ublish[f|F][A|a][Q|q] +(.+)\\s*:\\)/e', "PublishFAQ('$1')");

Now:

Markup('publishfaq', '<[[<<]]', 
        '/\\(:[p|P]ublish[f|F][A|a][Q|q]+(.*)\\s*:\\)/e', "PublishFAQ('$1')");

PublishFAQ is now:

function PublishFAQ($PagePath = '') 
{
  if(empty($PagePath)){
	$tmp = explode('/', $GLOBALS['GLOBALS']['_SERVER']['PATH_INFO']);
	$PagePath = $tmp[1] . "." . $tmp[2];
  }
...

User notes +1: If you use, used or reviewed this recipe, you can add your name. These statistics appear in the Cookbook listings and will help newcomers browsing through the wiki.

PublishFAQ