MediaWiki Extension/Extension IDLTags

IDLTags extension for Mediawiki

When we moved the Developer's Guide into the wiki we thought about a way how we could achieve the useful IDL tags. The tags that get automatically converted into links to the related type in the generated IDL reference.

The IDLTags extension was written by Clayton Cornell and Terry Ellison to manage the IDL links in the OpenOffice.org Developer's Guide, as well as other documentation, like the BASIC Programming Guide. The extension converts Java paths, like com.sun.star.frame.Desktop to links back to the online IDL documentation, such as http://api.openoffice.org/docs/common/ref/com/sun/star/frame/Desktop.html which then gets redirected to https://www.openoffice.org/api/docs/common/ref/com/sun/star/frame/Desktop.html.

On the Mediawiki these links are, for instance, present on the pages of the OpenOffice Developers Guide. Yes, there are quite a lot of them there. Supposedly it was designed to have to enter as less characters in the wiki as possible. They invented some tags to use.

These are:

Tag	Use
<idl> </idl>	link
<idls> </idls>	probably used for services
<idlm> </idlm>	probably used for methods
<idlmodule> </idlmodule>	used for modules to lead to the index page
<idltopic> </idltopic>

This last tag is mentioned, but does not seem to have a function in the extension and will be ignored further.

On the wikipages these tags contain a part of the IDL reference to link back to:

<idl>com.sun.star.frame.Desktop</idl>

<idls>com.sun.star.lang.DisposedException</idls>

<idlm>com.sun.star.uno.XComponentContext:getServiceManager</idlm>

<idlmodule>com.sun.star.awt</idlmodule>

Use

This extension converts the content of the tag to a regular link. It is written in PHP and uses, besides functions from PHP, internal functions of Mediawiki.

Functions

It consist of five separate functions, one for each tag:

Function renderIDL

Function renderIDL uses the function str_replace from PHP to convert to URL:

function renderIDL( $input, $args, $parser ) {
               $parser->disableCache();
               $output = $parser->recursiveTagParse( $input );
               $output = '<a href="https://www.openoffice.org/api/docs/common/ref/' .
                str_replace ('.','/',$output).'.html" class="external 
                             text">'.$output.'</a>';
             return $output;
         }

Function renderIDLM

Function renderIDLM used to use the function ereg_replace from PHP to convert to URL:

function renderIDLM( $input, $args, $parser ) {
         $parser->disableCache();
         $output = $parser->recursiveTagParse( $input );
         $page = ereg_replace ('\.','/',$output);
         $anchor = ereg_replace (':','.html#',$page);
         $function = ereg_replace ('^.*:','',$page);
         $output = '<a href="http://api.openoffice.org/docs/common/ref/' .
             $anchor.'" class="external text">'.$function.'</a>';
         return $output;
     }

Function renderIDLS

Function renderIDLS used to use the function ereg_replace from PHP to convert to URL:

function renderIDLS( $input, $args, $parser ) {
         $parser->disableCache();
         $output = $parser->recursiveTagParse( $input );
         $function = ereg_replace ('^.*\.','',$output);
         $output = '<a href="http://api.openoffice.org/docs/common/ref/' .
             ereg_replace ('\.','/',$output).'.html" class="external 
                            text">'.$function.'</a>';
         return $output;
    }

Function renderIDLMODULE

Function renderIDLMODULE used to use the function ereg_replace from PHP to convert to URL:

function renderIDLM( $input, $args, $parser ) {
         $parser->disableCache();
         $output = $parser->recursiveTagParse( $input );
         $page = ereg_replace ('\.','/',$output);
         $anchor = ereg_replace (':','.html#',$page);
         $function = ereg_replace ('^.*:','',$page);
         $output = '<a href="http://api.openoffice.org/docs/common/ref/' .
             $anchor.'" class="external text">'.$function.'</a>';
         return $output;
     }

Function renderIDLTOPIC

The use or purpose of this function is unknown. Tags in the wiki are commented out.

function renderIDLTOPIC( $input, $args, $parser ) {
		$parser->disableCache();
		return '';
     }

A problem arose

The extension worked for a long time, but since some time contents of a lot of pages of the Developers Guide were no longer displayed. Investigation learned that the text still was there, but that it wasn't rendered on the page. Editing the pages was still possible by tweaking the URL of the page from (as an example):

https://wiki.openoffice.org/wiki/Documentation/DevGuide/Documentation/DevGuide/FirstSteps/First Contact

to

https://wiki.openoffice.org/w/index.php?title=Documentation/DevGuide/Documentation/DevGuide/FirstSteps/First Contact</nowiki>&action=edit

That would bring up the content of the page and the possibility to edit it. That investigation also led to the conclusion that effected pages contained one or more of the IDLS, IDLM or IDLMODULE tags. Further was determined that pages that only contained IDL tags were displayed correctly.

It was likely that the extension IDLTags did no longer do his fabulous work. Arrigo Marchiori set us on the right track pointing out that the function ereg_replace was deprecated and removed from PHP 7.0.* and therefore can't be used anymore. The version of Mediawiki for AOo uses version 7.0.3 of PHP.

This broke the existing extension so that it didn't render the IDLM, IDLS and IDLMODULE tags anymore. As a result of this the content of pages on the Mediawiki that contained one or more of these tags were no longer displayed. They rendered full white. Therefore function renderIDLM, function renderIDLS and function renderIDLMODULE did no longer do their work and content of pages that contained one of these tags were no longer displayed correctly but only fully white rendered.

Fix

The functions needed to be adapted to use another function than ereg_replace. That function proved to be preg_replace and Carl Marcum worked his magic on this one. He also changed the old redirect to the new places on the Apache OpenOffice website: https://www.openoffice.org/api/docs/common/ref/

function renderIDLM( $input, $args, $parser ) {
		$parser->disableCache();
		$output = $parser->recursiveTagParse( $input );
		$page = preg_replace ('/\./','/',$output);
		$anchor = preg_replace ('/:/','.html#',$page);
		$function = preg_replace ('/^.*:/','',$page);
		$output = '<a href="https://www.openoffice.org/api/docs/common/ref/' . 
			$anchor.'" class="external text">'.$function.'</a>';
		return $output;
	}

---

function renderIDLS( $input, $args, $parser ) {
		$parser->disableCache();
		$output = $parser->recursiveTagParse( $input );
		$function = preg_replace ('/^.*\./','',$output);
		$output = '<a href="https://www.openoffice.org/api/docs/common/ref/' . 
			preg_replace ('/\./','/',$output).'.html" class="external text">'.$function.'</a>';
		return $output;
	}

---

function renderIDLMODULE( $input, $args, $parser ) {
		$parser->disableCache();
		$output = $parser->recursiveTagParse( $input );
		$function = preg_replace ('/^.*\./','',$output);
		$output = '<a href="https://www.openoffice.org/api/docs/common/ref/' . 
			preg_replace ('/\./','/',$output).'/module-ix.html" class="external text">'.$output.'</a>';
		return $output;
         }

---

Using this new adapted functions the links in the DevGuide function again as of 2020-12-17.

References

References to this page on the wiki are on:

* https://wiki.openoffice.org/wiki/Documentation/DevGuide/Contributing_to_the_Developers_Guide#IDL_extension_and_links

* https://wiki.openoffice.org/wiki/API

* https://wiki.openoffice.org/wiki/Help:Extensions

(please add to the list if you come across one that is not yet listed)