[pmwiki-users] Table of Contents (Was: picks up Q:-markup)

[John Rankin]

This is a long answer -- I have tried to unravel the issues and options.

On Friday, 28 January 2005 9:51 PM, chr at home.se wrote:
>I think (:toc:) should *not* include Q: by default (but that's possible to 
>change as you describe below). 

The options are:
1 Q: included by default

2 Q: excluded by default

3 the wiki administrator decides what policy to apply

Currently, the implementation goes with option 3.

>However, what about definitions (:: :)? Are 
>these included?

IIRC, no they are not. They could be, but let's not go there just yet.
...
>
>Basically I think I we only do this:
>
>* Generate a TOC where I don't want any questions etc included
>* Generate a TOC where I do want questions etc (on a FAQ page
>typically)
>
>...then I'd suggest something like
>
>	(:toc Table of Contents without questions:)
>
>or
>
>	(:toc include=all Table of Contents with questions etc:)
>
>and if we want special cases of what should be included, we could fiddle 
>with the argument to the 'include'-option. What do you think of
>this?

I think it depends whether one wants option 1, 2 or 3 above.

This suggestion implies option 2.

Similarly (from Scott's post)
> 
> So ... how about (:toc -Q:) or (:toc !Q:) or something to that effect.
> Or even (:tocq:) adds Q: markup entries and (:toc:) does not.

This suggestion implies option 1.

Philosophically, I'm of the view that an administrator ought to
be able to decide whether (:toc:) includes or excludes Q: markup
and be able to set this as a wiki-wide policy (option 3). So I 
think the script should aim to be policy-agnostic. But that's
just my 5¢.

We could always try the following, perhaps more natural syntax,
based on option 3:

- (:toc:) does whatever an $IncludeQMarkup policy defines

- if $IncludeQMarkup = true, (:toc -Q:) omits Q: markup

- if $IncludeQMarkup = false, (:toc +Q:) includes Q: markup

(We might make the + or - characters optional.)


>I agree, (:toc Q:) looks backward.. and from a user's perspective, why
>wouldn't this put 'Q' as the heading of the TOC?

answer a: that would be (:toc Q :)

answer b: or we could use (:toc+q:) and (:toc-q:) if that would be clearer

>Besides, I think there could be an option to be more verbose, for 
>instance:
>
>	(:toc include-questions=yes:)

answer c: or we could use (:toc include-questions=yes:) and
(:toc include-questions=no:)

I think since the writer already knows Q: produces a question, 
we ought to reuse the Q character in the (:toc:) markup.

So a shorter version is (:toc Q=yes:) and (:toc Q=no:)

'Choosing good markup is the hardest part.'

-- 
JR
--
John Rankin