[pmwiki-users] yet another documentation suggestion ...

[John Rankin]

On Thursday, 4 August 2005 12:40 AM, Neil Herber <nospam at eton.ca> wrote:
>At 2005-08-02  10:33 PM -0700, H. Fox is rumored to have said:
>>On 03 Aug 2005 10:50:42 +1200, John Rankin <john.rankin at affinity.co.nz> wrote:
>> > FYI
>> >
>> > The Cookbook:PageTableOfContents is designed to pick up Q: markup
>> > and generate a list of links to all the questions. When questions are
>> > very long, you can insert Christian's invisible stop (`.) and the
>> > table of contents only shows the text up to the stop, followed by
>> > an ellipsis. In ordinary text, invisible stops are, well, invisible.
>> >
>> > If the page includes major headings to separate the Q: tags, these
>> > headings appear in the TOC.
>>
>>I was tempted to suggest something like that, but it seemed like a lot
>>to ask. :-)
>
>I really like this idea, but to make it work for a FAQ that was part of the 
>distribution (as it is now), wouldn't the PageTableOfContents recipe need 
>to be installed by default?
>
Yes, that's correct.

Patrick has been properly reluctant to take third party recipes into the
core in the past. Where he has adopted functionality, he has AFAIK
chosen to re-write the code.

Some comments on the PageTableOfContents code:

- 80% is fine and is consistent with the way pmwiki does things

- 20% is really nurky and needs to be re-written (new pmwiki
  features mean it can potentially be simplified)

- all the features are there for a good reason, even if I can't 
  quite remember what the reasons are

- it has probably gone about as far as it can in its current form
  (the last thing to be added was to display a toc on PageA for
  the contents of PageZ)

The big thing I learnt was that authors expect to put any valid
wiki markup in a heading or Q: and have the toc 'just work'.

-- 
JR
--
John Rankin