History: TOC revamp

((doc:Maketoc)) has some design challenges: some bugs will never be fixed. See: ((Maketoc))

Proposal: replace by a client-side Table of Content generation using JavaScript, removing or not the current server-side maketoc

It should use https://getbootstrap.com/docs/4.0/components/scrollspy/ like ((doc:Auto TOC)) but with
* global params which can be overridden per page (like ((doc:maketoc)) does now.) or perspective
** active vs inactive by default
**Subsection titles:
*** Static (classic behavior) or dynamic (TOC sections expand and collapse depending on the viewport's location, as can be seen when scrolling on [https://getbootstrap.com/docs/3.3/javascript|this page]) 
*** If static, the maximum level to display (ex.: 2,3 like in maketoc)
** position: right, left, center, where plugin is on page

Should TOC-s be available for objects other than wiki pages? {sign user="Chealer9" datetime="2017-08-30T14:56:02+00:00"}
* Another use case: long tracker forms in popups (nice to have) {sign user="marclaporte" datetime="2017-09-05T18:28:59+00:00"}
** Are you talking about forms using wiki pages as templates (pretty  trackers)? {sign user="Chealer9" datetime="2017-09-05T21:06:29+00:00"}

Should the presumably much less used TOC plugin (for structures) not be renamed to something like STRUCTURETOC, or STRUCTURECONTENTS? {sign user="Chealer9" datetime="2018-05-07T20:12:58+00:00"}

!! Issues with automatic tables of contents
* When the toc is higher than the page's view-port, there should be a scroll bar.
** It is already possible to scroll using the browser's scrollbar. 
*** ok, so maybe it's been solved? This only was visible on huge tocs  {sign user="marclaporte" datetime="2017-09-05T18:28:59+00:00"}
**** I don't think that's what I meant, but looking at https://getbootstrap.com/docs/4.0/layout/grid/ there is a TOC scrollbar. Unlike in https://getbootstrap.com/docs/3.3/components/. But unfortunately it's not Bootstrap 4 per se which adds such a scrollbar since it is still lacking in Tiki 19. {sign user="Chealer9" datetime="2017-09-07T13:02:45+00:00"}
** Is this to enable scrolling in the TOC using the keyboard or to allow exploring the TOC without losing the current position in the document? Should this be requested upstream against Bootstrap's affix? {sign user="Chealer9" datetime="2017-08-29T20:50:31+00:00"}
*** Yes, perhaps an upstream thing. Maybe solved, if not, maybe in Bootstrap 4 {sign user="marclaporte" datetime="2017-09-05T18:28:59+00:00"}
**** But what advantages do you see in this scrollbar? {sign user="Chealer9" datetime="2017-09-06T15:54:10+00:00"}
** This is probably solved by {commit id="69553"} and {commit id="69554"} (for Tiki 19.2). {sign user="Chealer9" datetime="2019-03-29T17:24:40+00:00"}
* {wish id=5511} (if still current)

Related discussion about the interest of keeping traditional TOC-s:
*What would be the interest of keeping server-side as a possibility? {sign user="Chealer9" datetime="2017-08-29T19:13:31+00:00"}
** Good question! Since PluginMaketoc doesn't use the regular wiki plugin code, the regular plugin helper doesn't let us show all the options. But here are the docs: ((doc:PluginMaketoc)) and it seems to me all doable client-side. One issue though is when JavaScript is not available, like in some printing context, so it could require the same solution as for other similar cases: ((Converting dynamic JavaScript content into static assets)). But, in any case, mPDF has another way of dealing with this: https://mpdf.github.io/what-else-can-i-do/table-of-contents.html All in all, I would get rid of maketoc (ex.: last version would be Tiki18) assuming AutoToc (or whatever it's called) can do an acceptable job. {sign user="marclaporte" datetime="2017-08-29T19:54:41+00:00"}
*** maketoc does not accept any parameter other than those documented. So, you are saying that:
#### Currently, maketoc is more configurable thanks to these parameters.
#### Once #1 is solved, the only interest of keeping server-side would be JavaScript. Is there a context other than PDF exportation which could be affected? And if not, do you agree that once #1 is solved a client-side parameter would be useless?{sign user="Chealer9" datetime="2017-08-29T21:24:09+00:00"}
**Well, a lot of people find it currently useful. Just because the server-side plugin has a bunch of ''wontfix'' bugs does not guarantee that the client-side plugin won't have other, different unfixable issues. In this context I understand ''make it optional'' as let people switch to the new version when ''they'' decide it better fits their needs.
*** But do you see any such issue? {sign user="Chealer9" datetime="2017-09-28T18:16:15+00:00"}

!!! Option A: maketoc with a new param client-side
* {QUOTE(replyto="Marc")}Since PluginMaketoc doesn’t use the regular wiki plugin code{QUOTE}.
+ I'm strongly in favor of consistency and code reduction. If there is some plugin standard or regular tiki/wiki code we should be sure we go to that direction for any plugin we improve. I'm not in favor of exception and "aliens" implementation because a project or two need it. {sign user="Bsfez" datetime="2017-09-07T08:54:46+00:00"}
+ I'm strongly in favor of improving Tiki as users see it more than improving code only devs see. I move from ''undecided'' to ''reject'' because I'd prefer keeping maketoc working until we get autotoc in shape. {sign user="Jyhem" datetime="2017-09-07T09:57:10+00:00"}
** What do you mean. Why would adding this parameter stop maketoc from working? {sign user="Chealer9" datetime="2017-10-06T21:27:49+00:00"}

{PROPOSAL(caption="maketoc with a new param client-side")}0~1 luci
0 Torsten
-1 Jyhem
-1 MarcLaporte{PROPOSAL}

!!! Option B: replace with a new autotoc plugin
Add a plugin which would have parameters allowing to set options of the Bootstrap TOC. There could be extra options to define how (or if) the TOC displays when the page is printed, accessed from a mobile device, or exported as a PDF file.

Having a plugin (rather than wiki page properties) would allow using TOC-s with more object types.

The location of the plugin call in the syntax could define the position of the TOC, but not necessarily (there could be an option to override that).

---
What would happen with the current "Automatic table of contents" tiki-editpage field? If it is removed, what would happen with the values of the field at the time of removal? And if it is not removed, what would happen if the autotoc plugin is used in a page with "Automatic table of contents" set to No? {sign user="Chealer9" datetime="2017-10-10T16:31:11+00:00"}
* Marc says we should keep a field so that TOC-s can be disabled if they are enabled by default. In that case, should the field not become just a "Display TOC" checkbox?

Why would the plugin be called "autotoc"? {sign user="Chealer9" datetime="2017-10-18T15:07:24+00:00"} "automatic" in the sense that the author does not have to manually copy-paste (let's say) each title? If so, is that not obvious? There is already [https://doc.tiki.org/Auto%20TOC|something called "Auto TOC"].

{PROPOSAL(caption="new autotoc plugin")}-1~1 luci
~1 Torsten
+1 Jyhem
+1 MarcLaporte{PROPOSAL}

* MakeToc, in its current design is fundamentally flawed in today's context (it likely was best way to do at the time it was done). It needs to understand the logic of any other plugin on the page. Even with a lot of work, it will never be reliable, which is why we need a revamp or a replacement. Seems to be best to start with a fresh code base. {sign user="marclaporte" datetime="2017-09-21T03:29:32+00:00"}

!!!! Optional : Remove maketoc
{PROPOSAL(caption="finally remove maketoc")}-1 Jyhem
-1 Torsten
+1 MarcLaporte
{PROPOSAL}

* Autotoc is nice, although autotoc in no means is a full or at least sufficient replacement for maketoc. -- Torsten Fabricius
* I think we should remove in 2 or 3 years,  once AutoTOC is a suitable replacement. After an LTS so sites can stay with that another 5 years, and they have ample time to transition. We could add a ((doc:PluginAlias)) as we've done for other deprecated plugins in the past but this is not a perfect solution as parameters won't neatly match up. {sign user="marclaporte" datetime="2017-09-21T03:29:32+00:00"}

What would happen with existing calls to maketoc if it is removed? {sign user="Chealer9" datetime="2018-05-07T19:01:22+00:00"}
It will be just text, like if you put {thenameofapluginthatdoesnotexit}

!!! Option C: Make maketoc generate a TOC client-side (rather than server-side)
replace maketoc code so users get new version on upgrade
Ideally, params would continue working
{PROPOSAL(replace maketoc code)}0~1 luci
-1 Jyhem
0 Torsten
-1 Marc Laporte{PROPOSAL}


New options we want
* param to put toc where the plugin is vs right aligned vs...

!! About using mPDF's ToCs
* [item6611-Allow-replacing-hardcoded-call-to-maketoc-in-page-with-the-one-produced-by-mpdf]

-= Alias =-
(alias(Maketoc revamp))