[pmwiki-users] Automatically add anchors to heading tags? pmwiki-users Digest, Vol 25, Issue 50

[John Rankin]

On Thursday, 26 July 2007 11:47 AM, H. Fox <haganfox at users.sourceforge.net> wrote:
>On 26 Jul 2007 10:34:35 +1200, John Rankin <john.rankin at affinity.co.nz> wrote:
>> Turning heading text into an anchor guaranteed to be valid would also need
>> a bit of care; eg
>>
>> !!!Christian Ridderström
>>
>> would need to turn the ö into something else,
>
>Maybe there's some regular-expression magic that can do that.

The trick I used in the citations recipe was to pass the text
through the htmlentities function and remove the & and ; from 
the result.
>
>> I think. [[#h_numbers]]
>> would be easier *and* safer.
>
>It might be easier, but it would be next-to-worthless to use for
>linking to a document section, except perhaps for a dynamic table of
>contents.  A link like [[SomePage#h_123]] would stop working when
>someone inserts another heading, making it pointless to create such a
>link.

I agree up to a point. First, if somebody changes the text of the
heading, it also breaks any links to an anchor hased on the text.
Somebody can delete the heading too, of course.

The other potential minor problem is generating duplicate anchors.

So text-based anchors are also not 100% robust. The suggestion that
Dom made would partially address the issue:

[[#h1.2.3]] = The 3rd H3 in the 2nd H2 in the 1st H1.
[[#h6.0.1]] = The 1st H3 in the 6th H1. (the 0 is for a missing H2)

I added dots between the levels in his example.

That proposal is robust under some inserts and deletes, but 
obviously not others.
>
>Using numbers is fine, but once an anchor exists the number needs to
>remain the same when more headings are added to the page.

Yes -- stable urls are a good thing! One precedent I can think of
is amendments to legislation, where the drafters of the law go to
great lengths to make sure that clause numbers, once enacted, don't
change. So if there is a new clause inserted between 1 and 2, it is 
numbered 1a. It's not at all clear how one might achieve that with
heading numbers, unless one generated the anchors and stored them
as part of the page. Then if someone inserts a new heading, pmwiki
would notice that it doesn't have an anchor and generate one with
an alpha suffix to the previous anchor in the current series.

It's still not 100% robust, because an editor could remove an
anchor (say [[#h2.3.4]]) and pmwiki would create a new one
([[#h2.3.3a]]), thinking it's a new heading, unless pmwiki
noticed that the next one is [[#h2.3.5]] or [[#h2.4]].

So no scheme is going to be 100% robust. The question is, what
level of non-robustness is acceptable?

How common is this in practice? For general usage, inter-page
links to specific headings are the exception rather than the
rule, and in such cases, perhaps the author should explicitly 
create an anchor, rather than automatically anchoring every
heading on the off chance that somebody might like to link
to it. On the other hand, where the site is heavily inter-page
linked to specific headings, perhaps a site policy to add 
headings at the ends of sections could suffice in some cases,
to make a number-based scheme more robust.

My most common use for this is to send an email linking to
a specific heading. That's a transient piece of information
and I only need the link to be stable until the recipeint
has read it. So in that case one can live with the idea
that the probability the link is invalid depends on the
elapsed time between my sending it and the reader clicking.

I don't have a good feel for how big a problem this is in 
practice but suspect that different solutions will be 
appropriate in different situations.

Just my 10¢ worth.


-- 
JR
--
John Rankin

       \_      
        \)   
         \,\__/7
         /    /
        (   c'
         \  / 
     /,  /_/  
    |  & *   Wellington
    )  /    
   /  /,    
  /  (    
 |   /      
 \__/       
   V