Change Details

T114051 is a problem. We need a meaningful table of contents as an object that we can work with, both in core and especially for extensions. This applies to parser functions, skins, and potentially anything introducing a new datamodel. As is, the only approach to working with a custom/modified table of contents is disable the normal one and then reconstruct it from parts, and often that doesn't work at all, forcing developers to simply implement a new one for the extension itself. Both of these are messy and inefficient, and result in inconsistencies and difficulty updating, with different structures and styles in every new one that likewise cannot be updated easily nor interacted with by other extensions. It is also currently causing issues with caching due to how it handles i18n. The question, of course, is what will the solution to this problem look like? Where will it be (it's currently scattered across the parser, the linker, and the skin backend, or some such)? What do we need from it to meet the needs of existing extensions, as well as potential new ones down the line? How do we not break core, and potentially all manner of skins that try to use it as is (bluesky, refreshed)? Answering this, we can then establish a way forward.

We need a better Table of Contents. (T114051) We need to determine stakeholders and a path forward. >>! In T114057#1795082, @MZMcBride wrote: > Are there specific pain points with the current table of contents implementation? * Caching problems due to partial i18n (it's treated as part of the content, but localised) * Improving it is unnecessarily difficult (source is scattered across several different classes), and patches improving it are also quickly obsoleted by unrelated changes due to how spread out it is * Extensions cannot easily reuse it (technically it is possible to replicate the several different calls required to generate its html, but it's a mess and results in duplicate ids and stuff - Extension:DeToc, Skin:BlueSky, and others all do this) * Extensions cannot hook into it to modify it or reuse it for different content models > It seems like I'm not the only person struggling for use-cases here. Extension use cases modifying/adding to the ToC: * **Parser extensions dealing with particularly long, sectionable content.** A discrete example is the ScreenPlay extension, which introduces a parser to render screenplay formatting. This includes scene headings, which would ideally appear in the table of contents as, well, the contents of the page (part of T114033). As is, however, even ordinary == == sections within the screenplay tags do not appear within the table of contents because it is being parsed separately from this part of normal wikitext. Currently there is no way to hook back into the table of contents and fix this for either case. * **Formatted discussion extensions, which implement sections for different threads.** LQT got around this by just making its own. Flow gets around this by not having a ToC at all (unless it also just implements its own now; I haven't checked recently). While they can get away with this due to replacing all the usual content on the page (and thus avoiding ever having two ToCs), this is not ideal. They should be able to hook into the core table of contents and reuse that, not reinvent the wheel in a different way every time. * **Anything else that wants a ToC of unusual content.** Books (T33075, T78329), Special pages (T15862), preferences, whatever. If special pages and whatever could also register sections with a standard ToC object and place that on the page, this would standardise output for all of them, regardless of what generated the content. Reusing the ToC: * **Skins like BlueSky, Naiad, and Refreshed, which incorporate the table of contents into their interface.** This is currently possible, but incredibly hacky, and it does not persist even on edit. There are also issues (when using more than one) with duplicated ids because all the html is pretty much hardcoded into the output. Other uses: * **Multiple tables of contents on a page.** For when you're insane or dealing with insanely long pages. Or have multiple pages on a page. Or something. * **Getting a ToC for a page by title.** Possibly useful for semantic stuff. Or generating contents for see also links. Or for the skins mentioned above. Or for the API. Having a single object to interact with should vastly simplify the process whether it exists already or not. What else?

T114051 is a problem. We need a meaningful table of contents as an object that we can work with, both in core and especially for extensions. This applies to parser functions, skins, and potentially anything introducing a new datamodel. As is, the only approach to working with a custom/modified table of contents is disable the normal one and then reconstruct it from parts, and often that doesn't work at all, forcing developers to simply implement a new one for the extension itself. Both of these are messy and inefficient, and result in inconsistencies and difficulty updating,We need a better Table of Contents. with different structures and styles in every new one that likewise cannot be updated easily nor interacted with by other extensions(T114051) We need to determine stakeholders and a path forward. It is also currently causing issue>>! In T114057#1795082, @MZMcBride wrote: > Are there specific pain points with caching due to how it handles i18n.th the current table of contents implementation? The question, of course, is what will the solution to this problem look like? Where will it be (it's currently scattered across the parser* Caching problems due to partial i18n (it's treated as part of the content, the linker, and the skin backendbut localised) * Improving it is unnecessarily difficult (source is scattered across several different classes), or some such)? What do we need from it to meet the needs of existing extensionsand patches improving it are also quickly obsoleted by unrelated changes due to how spread out it is * Extensions cannot easily reuse it (technically it is possible to replicate the several different calls required to generate its html, as well as potential new ones down the line?but it's a mess and results in duplicate ids and stuff - Extension:DeToc, How do we not break coreSkin:BlueSky, and potentially all manner of skins that try to others all do this) * Extensions cannot hook into it to modify it or reuse it as is (bluesky, refreshed)?for different content models Answering this,> It seems like I'm not the only person struggling for use-cases here. Extension use cases modifying/adding to the ToC: * **Parser extensions dealing with particularly long, sectionable content.** A discrete example is the ScreenPlay extension, which introduces a parser to render screenplay formatting. This includes scene headings, which would ideally appear in the table of contents as, well, the contents of the page (part of T114033). As is, however, even ordinary == == sections within the screenplay tags do not appear within the table of contents because it is being parsed separately from this part of normal wikitext. Currently there is no way to hook back into the table of contents and fix this for either case. * **Formatted discussion extensions, which implement sections for different threads.** LQT got around this by just making its own. Flow gets around this by not having a ToC at all (unless it also just implements its own now; I haven't checked recently). While they can get away with this due to replacing all the usual content on the page (and thus avoiding ever having two ToCs), this is not ideal. They should be able to hook into the core table of contents and reuse that, not reinvent the wheel in a different way every time. * **Anything else that wants a ToC of unusual content.** Books (T33075, T78329), Special pages (T15862), preferences, whatever. If special pages and whatever could also register sections with a standard ToC object and place that on the page, this would standardise output for all of them, regardless of what generated the content. Reusing the ToC: * **Skins like BlueSky, Naiad, and Refreshed, which incorporate the table of contents into their interface.** This is currently possible, but incredibly hacky, and it does not persist even on edit. There are also issues (when using more than one) with duplicated ids because all the html is pretty much hardcoded into the output. Other uses: * **Multiple tables of contents on a page.** For when you're insane or dealing with insanely long pages. Or have multiple pages on a page. Or something. * **Getting a ToC for a page by title.** Possibly useful for semantic stuff. Or generating contents for see also links. Or for the skins mentioned above. Or for the API. we can then establish a way forward.Having a single object to interact with should vastly simplify the process whether it exists already or not. What else?