[pmwiki-users] FAQs and anchors and TOC

John Rankin john.rankin at affinity.co.nz
Thu Nov 3 15:27:05 CST 2005

On Friday, 4 November 2005 7:03 AM, Waylan Limberg <waylan at gmail.com> wrote:
>Wow, I'm gone for half a day and there's all sorts of stuff to sort
>through. Thanks for all the tips everyone. Now to respond where
>On 03 Nov 2005 12:21:52 +1300, John Rankin <john.rankin at affinity.co.nz> wrote:
>> On Thursday, 3 November 2005 10:03 AM, Waylan Limberg <waylan at gmail.com> wrote:
>> >
>> >The list looks like this in the browser:
>> >
>> >1. 1 My first question
>> >2. 2 My second question...
>> >
>> I'm not sure why this problem is happening, as there is an ol.toc with
>> list-style: none; to turn the browser's automatic numbering
>Why in the world would you do that? Just use the browsers numbering.
>If your not going to, don't use <ol>.

Well, it started out using auto-numbering, but things change...

2 reasons:
- somebody made the very strong recommendation that the number in 
  first level items not have a full stop after it, to be consistent
  with the auto numbering of the headings below -- AFAIK, it's not
  possible to tell a browser to display 1 instead of 1.
- the sub items are nunmbered manually to produce 2.1 2.2 and
  so on

>> It works fine for me and others.
>> Is there a link where I can view it, with $EnableDiag = 1; set?
>> The only thing I can think of is that there is a $HTMLStylesFmt['toc']
>> declared elsewhere, which is overriding the toc recipe's settings.
>Oh right. In this particular install, any css generated by PmWiki is
>completely ignored. We use all our own css. You see, in our view, if
>it doesn't look right in a text browser with no css, then its a
>problem on your end. You should never have html that requires css to
>be readable. That's just bad practice IMHO.

I'm not sure I wholly agree, but that's a different subject...

What do you suggest doing instead? I am always happy to take guidance 
and consider alternatives. How do I produce a list that looks like 
this without using css:

  1 an item
    1.1 a subitem
    1.2 another subitem
  2 a further item
    2.1 and its sub item

and so on
>Anyway, it is a non-issue now as I'm using <ul> instead by setting
>$NumberToc = false;. Btw, thanks for making that so easy to set. If
>only everything was so simple.
>> >
>> >The other problem is that I don't like the anchor links: #toc1,
>> >#toc2?? Yuck! Wouldn't "#My_first_question" work much better? Anyone
>> >know of an easy way to change that for the recipe?
>> If you insert your own anchors, the script will use them, eg
>> Q:[[#my_first_question]]Which way is up?
>Sorry, I can't expect my non-technical users to type it all that way
>every time. That will never work.

That was kind of my point... And some people *do* wish to define
their own anchors, so the script has to cater for them.
>> Or are you suggesting that the script should form its anchor from
>> the text of the question, replacing spaces with underscores,
>> removing disallowed characters and detecting duplicates?
>Yes, that is exactly what I had in mind. Except for the duplicates, it
>shouldn't be to hard (actually, I already have the code - minus the
>duplicates part, I just need to pass it the text of the question. That
>will take some hacking of the recipe though).

What is the maximum allowed length of an anchor? What is the list of
disallowed characters? And note that the script also gets used when 
publishing page collections, when it gains a Group.PageName. prefix 
to remove possible duplicates, so it's not enough to truncate long 
questions to the maximum length.
>> What are the reasons for not using #toc1, #toc2, ... ?
>Human readable links. "To find out which way is up, simply point your
>browser to http://example.com/FAQ/General#which_way_is_up" sounds so
>much better that "...#toc3" If we really have to use some general
>anchors, wouldn't #faq1, #faq2 make more sense? I realize this does
>more than faqs, so have #heading1.. for headings, or perhaps
>#section1. After all, the anchor links to the faq/heading/section, not
>to the table of contents. Shouldn't the link reflect that?

Well I normally use link text rather than spelling out a url,
because these are never human readable. Personally, I find
'which way is up?' much more readable than 
>Now that I've thought about it, as a quick fix, I think I'll edit the
>recipe to use faq instead of toc in the anchor (seeing I am only using
>this for faqs - wouldn't work if I was useing it for heading too).
>Maybe if I, or someone else, finds the time, we can actually get the
>questions to become the anchors. Until then, #faq1 is certainly better
>than #toc1. Thanks for triggering that thought process.

A couple of points:

- I can easily make the anchor text a variable -- you are the first
  person who has wanted to change it :)

- the script can't easily decide for itself that 'faq' is better than
  'heading' -- suppose we have a page like this:

!!Technical matters
Q: First

Q: Second

Q: First

Q: Second

Now the toc is a mixture of headings and questions.

So now we need to mix different anchor texts and then we'd 
maybe want to maintain 2 counters for heading1 faq1 faq2 heading2 
faq3 ...

And then somebody will write:

!!Technical matters
Q: First

Q: [[#nota_bene]]Second

Q: First

Q: Second

So the links will be to faq1, nota_bene, faq2 but faq2 is actually
the third question not the second question, so maybe we don't want
to use anchor text that relates to the target. Or, or ...

The conclusion I reached was that the safest course was to use a
neutral string like 'toc', because there were just too many cases
to think aboout. But I *will* make the text a configurable variable.

Thanks very much for the thoughtful suggestions.

I am happy to have a separate debate on the role of css, graceful
page degredation and so on.

John Rankin

More information about the pmwiki-users mailing list