Talk:Document.php

From OrganicDesign Wiki

Legacy: This article describes a concept that has been superseded in the course of ongoing development on the Organic Design wiki. Please do not develop this any further or base work on this concept, this is only useful for a historic record of work done. You may find a link to the currently used concept or function in this article, if not you can contact the author to find out what has taken the place of this legacy item.

1 What is it?

Wiki is excellent for simple and fast production of collaborative articles. Using transclusion (the ability to embed articles content into one another) documents can be divided into smaller sections to be worked on separately, or included in more than one document.

One of the problems we've encountered using the Wiki for documentation is the inability to create proper structured documents with outline numbering that accounts for the embedding level. We needed to be able to export these documents to a word-processor where it could then be printed as a booklet.

Printing such booklets is the reason document.php was written. It doesn't currently have any other features and can only handle very simple content. But it's so commonly used, that it's included in the default-properties.xml article which means its features are automatically available to any article without changing its properties.

The exporting functionality has been separated out to its own transform. There are two versions - the one in use is called oo-regexp-export.php which is based on Regular Expressions. The other which is not complete yet is based on DOM, but is much more processor intensive. Both of them only currently support exporting to the Wikipedia:Open Office Writer format, but the current Microsoft product can probably read it. To export a document simply click on the "Export" link at the top of the page and select "Open" or "Save" like usual.

2 Transclusion

Transclusion is the ability to embed content from one article into another. MediaWiki already comes with a syntax for this, see Templates. This is the best method to use, unless you want to combine the embedding with outline numbering or other active features like syntax highlighting and stylesheets. MediaWiki's template syntax is to enclose the name in curly-braces, eg.

{{My-Included-Article}}

XmlWiki's transclusion syntax extends the usual link syntax by preceeding the article title with a + (transclusion-operator) as in the following syntax examples:

[[+Main Page]]
[[+Main Page|My Heading]]

The above examples both render the link the usual way, but render it as a title for the embedded content they link to. The second example uses the pipe to specify an alternative heading to the article title. To edit the transcluded article, click the heading.

• Note: A key difference between MediaWiki {{syntax}} and xmlwiki [[+syntax]] is that the Transclusion is static and dynamic respectively for embedded pages

Often it is desirable to embed the content without a heading, for example if you're rendering a remote article's content within quote-marks. This is the way MediaWiki's transclusion normally works, to do this with XmlWiki's active content, use a pipe like you usually would to define a title other than the article, but make it empty as in the following quote example:

[[+My-Included-Article|]]

XmlWiki will apply the default transforms and the articles own data and view transforms for dynamic content or design templates as usual. Below is an actual working example. The default-properties.xml article has been transcluded, and as you can see by the XML syntax highlighting, it's being transformed properly and is using the empty-pipe syntax shown above to make a null heading.

<?xml version="1.0" standalone="yes"?>
<!DOCTYPE xmlwiki:properties SYSTEM "xmlwiki-properties.dtd">
<properties>
<!-- This defines the initial properties for all articles -->
	<init>domain-properties.php</init>
	<data>document.php</data>
	<data>categories.php</data>
	<data>geshi.php</data>
	<view>default-skin.css</view>
	<view>wikitext-skin.php</view>
	<view>expandable.php</view>
	<view>tree-view.php</view>
	<view>remove-section-edit-links.php</view>
</properties>

3 Outline Numbering

The outline numbering level of a heading can be defined by preceeding it with # characters, as in the following example:

 #Heading             (this makes "1. Heading")
 #Another heading     (this makes "2. Another heading")
 ##A sub level        (this makes "2.1 A sub level")

Transclusion and outline can numbering work together (which is why they're both in the document.php transform. If the transcluding link includes outline numbering as in the example below, and the remote article does too, then the numbering will be unbroken by the transition from one transclusion layer to the next.

 #[[+SomeArticle|Heading]]

4 Using the Apply operator

+Apply