00955

Is there a simple way to configure pmWiki such that all headings (H1,
H2, etc) are automatically generated with anchor tags so people can link
directly to a section or subsection?  (I believe MediaWiki has this
functionality by default.)

!! Heading Name

[[#Heading_name]]
!! Heading Name

Any character not allowed in an anchor tag, I suppose.  The example on
the PITS page is just something I discovered when I was looking at how
it was done elsewhere.

Stripping out disallowed characters may be adequate.

<?php
$foo = 'See also';
echo '<pre>';
echo 'crc32: h'.crc32($foo)."\n";
echo 'md5: h'.md5($foo)."\n";
echo 'sha1: h'.sha1($foo)."\n";
echo '</pre>';

crc32: h-441119427
md5: h611114a3a55940e855fb96b973f897fc
sha1: h2d8243a2c0e464492c9d563c4f92c56ae3421bcc

On Thursday, 26 July 2007 11:47 AM, H. Fox <haganfox@users.sourceforge.net> wrote:
>On 26 Jul 2007 10:34:35 +1200, John Rankin <john.rankin@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.

MediaWiki [1] has this capability from version 1.8 [2], one can link to a section like this:

where there is a heading "==Editing wiki pages==".

The conversion algorythm heading->anchor_id is quite simple:

• wiki to plain text (all links and styles removed)
• whitespace trimmed ("= Title =" and "=Title=" are the same)
• in case there is a repeated heading in the same page (including "included" pages), a _2 or _3 etc. is added;
• spaces replaced with underscores;
• the string is "urlencoded";
• "%"-signs are replaced with dots.

This allows to have html that validates, and is very easy for the writers (PmWiki philosophy n°1). The conversion function works also in other languages, that is UTF-8 encoding: while it is not very nice in the html code for non-latin languages, it works both with the page table of contents and with links from other pages .

If the section heading changes order, the links to it will still work (unlike if all anchor_ids are id1, id2...). If the section heading dissapears or changes, the anchor_id will also change and then the links will redirect to the top of the page (least surprise).

I would add some items to the above list...

• use strtolower() so changing capitalization won't affect an existing anchor.
• prior to "urlencoding", strip certain characters out. Which characters? We'd need to come up with a list. (Maybe it should be locally customizable, too.) Here's a starter
  • ","
  • "("
  • ")"

Both of these have the advantage of making the anchor name easier to guess without looking at the page source. The second one (stripping certain characters) also mitigates having a heading start with a non-alphanumeric character.

The list becomes

• wiki to plain text (all links and styles removed)
• whitespace trimmed ("= Title =" and "=Title=" are the same)
• alpha characters to lower case
• certain special characters stripped (e.g. ",()" and others TBD)
• in case there is a repeated heading in the same page (including "included" pages), a _2 or _3 etc. is added;
• spaces replaced with underscores;
• the string is "urlencoded";
• "%"-signs are replaced with dots.

...or something like that. ;-)

--Hagan

Perhaps the link code could be extended to look for
existing/non-existing anchors in pages and display
links to non-existing anchors slightly differently
making misspelled anchors more obvious?

Would abbreviations be a good option for people? At least in the test
page below, not one abbreviation was repeated, and if it were, the _2
and _3 would fix it right up. This would take care of many of the human
errors we've been talking about, though in pages with (way too many)
headings, it might add some new ones.

 #wiki_style_basics = #wsb
 #scopes = #s
 #wikistyle_attributes = #wa
 #applying_wikistyles_to_block = #awtb
 #enabling_Styles  = #es
 #custom_style_shortcuts = #css
 #predefined_style_shortcuts = #pss
 #Examples = #e
 #known_issues = #ki
 #see_also = #sa

Also, how can we use this automatic anchoring to create quick TOCs?
Generally speaking, an (:include function that stripped everything but
headers, or a (:pagelist toc= that tracked headers instead of trail=
tracking bullets would also work... My thought on this is that as long
as we are talking about anchors across an entire wiki, we should also
provide a way to just as easily index these anchors. Right?