3,897
edits
Changes
Jump to navigation
Jump to search
Created page with "{{todo|This page documents the situation that will become active in a few days/a week when the newly developed wiki extension will be ported over from the test wiki. This page..."
{{todo|This page documents the situation that will become active in a few days/a week when the newly developed wiki extension will be ported over from the test wiki. This page is written in preparation. Soon, this todo block will be deleted.
We have a heatwave right now, and even though there are some things in the extension that I still want to improve on, it is too hot in the actual office to do any programming. Instead, I am on the couch in front of a fan.
--[[User:Taco|Taco]] ([[User talk:Taco|talk]]) 19:48, 10 August 2020 (CEST)}}
== An extension for editing `/Command` subpages ==
The ConTeXtXML extension is a new wiki feature specifically designed to edit the ConTeXt command referencs pages (the ones that live under the `/Command/` URL.
It does this by intercepting the creation of new wiki pages below `/Command/`, and using a ContentHandler extension to maintain those pages. The text model of those pages is `contextxml`, which is a special XML format developed for documenting ConTeXt commands that is based in the interface XML files by Wolfgang Schuster.
For details of the XML format and the subtree structure below `/Command/`, see the pages [[Command]] and [[Help:Command]]. This page documents some features of the wiki extension itself.
== Building on `wikitext` ==
The core of the extension is made up of two connected php classes:
* `ConTeXtXMLContentHandler`, which extends `WikitextContentHandler`
* `ConTeXtXMLContent`, which extends `WikitextContent`
Together they ensure that even though the declared page format is `CONTENT_FORMAT_XML` (which expands to the mime-type `text/xml`) and the page model is `contextxml` instead of `wikitext`, it remains possible to use wiki code. The extension achieves this by using a preprocessor on the XML data that converts it to wiki code that can then be used by the normal mediawiki page viewing and parser code. At the same time, it keeps the XML format available for edits to take place on, so that any documentation text that is added by the user(s) can be easily extracted and exported for other uses outside of the wiki.
It turns out that for this to work, some tweaks have to be made. Either I have not understood the mediawiki documentation well, or there are issues with extending `WikitextContent`, or perhaps even both. Anyway:
* The `content_models` mediawiki SQL database table needed an extra row with the values `4`,`contextxml`. Added manually as I could not figure out how to do this automatically at extension registration time.
* `WikitextContent` does not like being subclassed, so some functions from the `parent::` needed to be copied wholesale instead of just wrapping a bit of code around the parent implementation.
== Building on `Article` ==
When a user loads an existing page, that page is normally of class `Article` (except for some special cases). The `Article` class sets the page content model to `wikitext`, which makes it use the standard `WikitextContent` and `WikitextContenthandler`. Because that would not work for the ConTeXtXML pages, there is a third class:
* `CmdPage`, which extends `Article`
This class is really small. It only exists are a coatrack for using `ConTeXtXMLContent`. It may not even be really needed in the current implementation, but it could prove useful for future further extensions.
== And then the `Hooks` ==
The extension uses a set of hooks to link into the mediawiki processing:
=== `ArticleFromTitle` ===
Creates a `CmdPage` if the wiki page title starts with `/Command`.
=== `ContentHandlerDefaultModelFor` ===
Sets the content model to `contextxml` if the wiki page title starts with `/Command`.
=== `PageContentSave` ===
On save, this saves `contextxml` pages to a designated harddisk location as well as in the wiki database.
=== `ArticleAfterFetchContentObject` ===
On load, this checks whether the page content on the designated harddisk location has changed. If yes, it will replace the text of the mediawiki revision with the content of the file on the harddisk. This is so that there is an easy interface for integrating updated versions of the interface xml files from Wolfgang.
=== `EditFormPreloadText` ===
This fills the edit area for newly created `/Command` pages from the file on the harddisk
=== `EditPageNoSuchSection` ===
Error hook that is triggered if the user tried to edit a section that is generated from wiki code instead of from the XML data. This is an error because it is quite hard to extract the right block of text in that case and still keep track of where it is in relation to the XML data.
=== `EditPage::showEditForm:fields` ===
Prints a simple help message at the top of the edit field for `/Command` pages.
{{todo|more later --[[User:Taco|Taco]] ([[User talk:Taco|talk]]) 19:48, 10 August 2020 (CEST)}}
We have a heatwave right now, and even though there are some things in the extension that I still want to improve on, it is too hot in the actual office to do any programming. Instead, I am on the couch in front of a fan.
--[[User:Taco|Taco]] ([[User talk:Taco|talk]]) 19:48, 10 August 2020 (CEST)}}
== An extension for editing `/Command` subpages ==
The ConTeXtXML extension is a new wiki feature specifically designed to edit the ConTeXt command referencs pages (the ones that live under the `/Command/` URL.
It does this by intercepting the creation of new wiki pages below `/Command/`, and using a ContentHandler extension to maintain those pages. The text model of those pages is `contextxml`, which is a special XML format developed for documenting ConTeXt commands that is based in the interface XML files by Wolfgang Schuster.
For details of the XML format and the subtree structure below `/Command/`, see the pages [[Command]] and [[Help:Command]]. This page documents some features of the wiki extension itself.
== Building on `wikitext` ==
The core of the extension is made up of two connected php classes:
* `ConTeXtXMLContentHandler`, which extends `WikitextContentHandler`
* `ConTeXtXMLContent`, which extends `WikitextContent`
Together they ensure that even though the declared page format is `CONTENT_FORMAT_XML` (which expands to the mime-type `text/xml`) and the page model is `contextxml` instead of `wikitext`, it remains possible to use wiki code. The extension achieves this by using a preprocessor on the XML data that converts it to wiki code that can then be used by the normal mediawiki page viewing and parser code. At the same time, it keeps the XML format available for edits to take place on, so that any documentation text that is added by the user(s) can be easily extracted and exported for other uses outside of the wiki.
It turns out that for this to work, some tweaks have to be made. Either I have not understood the mediawiki documentation well, or there are issues with extending `WikitextContent`, or perhaps even both. Anyway:
* The `content_models` mediawiki SQL database table needed an extra row with the values `4`,`contextxml`. Added manually as I could not figure out how to do this automatically at extension registration time.
* `WikitextContent` does not like being subclassed, so some functions from the `parent::` needed to be copied wholesale instead of just wrapping a bit of code around the parent implementation.
== Building on `Article` ==
When a user loads an existing page, that page is normally of class `Article` (except for some special cases). The `Article` class sets the page content model to `wikitext`, which makes it use the standard `WikitextContent` and `WikitextContenthandler`. Because that would not work for the ConTeXtXML pages, there is a third class:
* `CmdPage`, which extends `Article`
This class is really small. It only exists are a coatrack for using `ConTeXtXMLContent`. It may not even be really needed in the current implementation, but it could prove useful for future further extensions.
== And then the `Hooks` ==
The extension uses a set of hooks to link into the mediawiki processing:
=== `ArticleFromTitle` ===
Creates a `CmdPage` if the wiki page title starts with `/Command`.
=== `ContentHandlerDefaultModelFor` ===
Sets the content model to `contextxml` if the wiki page title starts with `/Command`.
=== `PageContentSave` ===
On save, this saves `contextxml` pages to a designated harddisk location as well as in the wiki database.
=== `ArticleAfterFetchContentObject` ===
On load, this checks whether the page content on the designated harddisk location has changed. If yes, it will replace the text of the mediawiki revision with the content of the file on the harddisk. This is so that there is an easy interface for integrating updated versions of the interface xml files from Wolfgang.
=== `EditFormPreloadText` ===
This fills the edit area for newly created `/Command` pages from the file on the harddisk
=== `EditPageNoSuchSection` ===
Error hook that is triggered if the user tried to edit a section that is generated from wiki code instead of from the XML data. This is an error because it is quite hard to extract the right block of text in that case and still keep track of where it is in relation to the XML data.
=== `EditPage::showEditForm:fields` ===
Prints a simple help message at the top of the edit field for `/Command` pages.
{{todo|more later --[[User:Taco|Taco]] ([[User talk:Taco|talk]]) 19:48, 10 August 2020 (CEST)}}
