[pmwiki-users] AutoToc and worse

[Petko Yotov]

On 12/02/2020 12:16, Benjamin Grassineau wrote:
> I didn't now that TOC was in the core now !

You can read about important changes between versions at:

   https://www.pmwiki.org/wiki/PmWiki/ReleaseNotes

There are a few other recent feature additions.


PmTOC was based on AutoTOC but is smaller, simpler, faster and is better 
adapted to use existing [[#anchor]] markups from the wiki page, while 
the automatic anchors (when there are no manually set ones) are 
different.

For example, for a heading "!! Привет" ("hello" in Bulgarian/Russian) 
without any existing [[#anchor]], the automatic anchors will be 
different:

AutoTOC has 4 different anchor rules, see $AutoTocIdEncoding, could be:

   #t.D0.9F.D1.80.D0.B8.D0.B2.D0.B5.D1.82 (intl chars to UTF8 codepoints)
    this is quite ugly for international websites
    especially for longer headings
    Latin/Roman headings will look like #Heading_in_English

   #privet (intl. chars replaced with lowercase Latin plain ones)
    this is nicer but requires a list of replacements for Latin,
    Greek and Cyrillic and irrelevant for many (most?) websites

   #at_3 (3 for the 3rd heading in the page)

   #_p (acronyms in lowercase)

   If there is an existing [[#anchor]] AutoTOC ignores it.


PmTOC accepts and reuses many cases of existing anchors and heading "id" 
from the page. When there is no anchor or "id" in the page, PmTOC uses a 
fifth rule to create the anchors:

   #toc-1.2.1

where 1.2.1 is the structural path to the heading, here section 1, 
subsection 2, sub-subsection 1. This is short, simple, and works 
reasonably well for both normal and international wikis.

If you need the automatic "Numbered headings" feature, AutoTOC only uses 
regular digits like 1.2.1, while with PmTOC you can configure Roman 
numerals or A-Z letters like XVII.6.A.c for the different levels.

If you already use AutoTOC, and have a number of incoming links to 
section anchors created by AutoTOC, you may prefer to keep using it, 
because switching to PmTOC will change the automatic anchors. Such a 
link, when there is no longer such anchor, will cause the browser to 
open the page and stay to the top without scrolling down to the section.

This is not a problem for many websites, in most cases I'd effectively 
switch to PmTOC to have fewer things to worry when upgrading.


Note that both AutoTOC and PmTOC are progressive enhancements in 
JavaScript. If you require a table of contents that will work with 
JavaScript disabled, or more features/options, look at some other table 
of contents recipes:

   https://www.pmwiki.org/wiki/Category/TOC


Petko

-- 
If you upgrade :  http://www.pmwiki.org/Upgrades

> Le mar. 11 févr. 2020 à 19:44, Petko Yotov <5ko at 5ko.fr> a écrit :
> 
>> All Worse headings are of level 2, and are considered the same as !!H2
>> headings from wiki text, and in the TOC should be aligned with them.
>> 
>> Both AutoTOC and its successor PmTOC only use the plain text of the
>> headings without any formatting. If you use bold in headings to 
>> simulate
>> a structure, indeed they will appear the same as the ones without 
>> bold:
>>    https://www.pmwiki.org/wiki/TestW7/TableOfContents
>> 
>> In addition, after you save a page with Worse, the TOC is not
>> immediately updated for the person who edits the page. It will be
>> updated the next time someone (or the same person) requests the same
>> page.
>> 
>> Petko
>> 
>> 
>> On 08/02/2020 08:29, Benjamin Grassineau wrote:
>> > I use the Worse (is better) cookbook on certain pages of my pmwiki
>> > website, to facilitate editing for users. In these pages, the AutoToc
>> > cookbook also works, but it does not respect the levels in the table
>> > of contents.
>> > Do you think this is a mishandling on my part, or if not, is there
>> > anything we can do about it?
>>