[pmwiki-users] FAQs and anchors and TOC

[Waylan Limberg]

On 04 Nov 2005 10:27:05 +1300, John Rankin <john.rankin at affinity.co.nz> wrote:
> On Friday, 4 November 2005 7:03 AM, Waylan Limberg <waylan at gmail.com> wrote:
> >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:
[snip]
> 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

You have a good point there. Hadn't though of that.

[snip]
> >>
> >> 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.

Good questions I hadn't thought of. Although, I'm sure they wouldn't
be to hard to dig up answers for.
> >
> >>
> >> 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
> 'http://example.com/FAQ/General#which_way_is_up'

So do I. I meant when publishing the link in print media or something
like that. Sorry I didn't make myself clear.
> >
> >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 :)

This would be much appreciated.
>
> - 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
>
> !!Specification
> 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
>
> !!Specification
> 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.

Right, right, different users will be using this in very different
situations, so your going with what works best for everyone. That
means those of us that are a little more picky (myself) have to give
in a little or write our own code. I understand. Just thought I'd ask.
Anyway, if I get the anchor text as a configurable variable out of all
this, that should be good enough for me.

>
> Thanks very much for the thoughtful suggestions.

Your welcome. And thanks for working through this with me, despite our
differing approaches.
>
> I am happy to have a separate debate on the role of css, graceful
> page degredation and so on.

That won't be necessary. Its likely we've both been through that
before and besides, its only partially my opinion. I'm also trying to
meet the needs of the project I'm working on which has resulted in
doing a few things different than the norm. I also recognize that
while complete separation of content from design is often better, in a
wiki that can be nearly impossible sometimes and concessions need to
be made.



--
----
Waylan Limberg
waylan at gmail.com