Meta:Tools/DPL for Blender's wiki
目次
Bare MINIMUM Guide to using DPL in Blender wiki
Blender is a highly powerful, very flexible, oft updated and improved 3D Graphical Modeller and Production Suite. Chances are that if you're reading this, you already know that.
All this flexibility and power within Blender is great for Blender users. The constantly changing features and functionality of Blender does sometimes cause problems though. Two of those problems being:
- 1. Blender wiki documentation sometimes being out of date or incomplete, when documenting the newer/changed features of an updated version of Blender.
- 2. Shared functionality in different parts of Blender and the Blender interface, which means documentation often repeats itself.
Thankfully though the Blender wiki has many tools which help ease the work needed to deal with points 1 and 2 above.
DPL (Dynamic Page List) is one of those tools.
DPL is according to the official DPL website:
- "DPL is a report generator for MediaWikis. It creates lists of articles that match certain criteria. Meta data like author, popularity or date of last update can be added. Contents from articles can be included in the result, based on chapters, templates or special markers in the text. DPL gives great flexibility in designing output (multi-column article lists, sortable tables etc.)"
Blender wiki is based on MediaWiki and MediaWiki is able to add multiple extensions to itself to extend its power and flexibility when it comes to wiki page creation and organisation. DPL is one such extension.
Using DPL the Blender wiki editor is able include content in their articles which is automatically obtained from different places within Blender wiki, dynamically.
This included content can be in the form of whole articles, sections of an article, stats on articles (such as number of links to it, sizes, title, date created, etc), or articles which are assigned to a particular category. Not just single articles can used, multiple sources can be used for generating reports/articles/stats.
So it is should be clear that DPL is very powerful and can be very useful to Blender wiki editors. Unfortunately all the flexibility of DPL comes at a price, which is that it can be difficult to decipher how DPL works and how to configure it to make it give you the information you need, the way you want it. Also at least as regards Blender wiki there are many features of DPL which most normal Blender wiki editors do not need.
All of this flexibility in DPL is reflected in the official DPL user manual, which means that the official manual to DPL can take some effort to understand simply because of its sheer size and level of detail it goes into.
To try and help with the difficulty of getting to grips with DPL usage, this document was put together to describe some of the ways in which DPL can be used within the Blender wiki site. It will only explain the bare minimum of features that will be useful for Blender wiki editors and wont cover other features. If you need a complete breakdown of all features of DPL you should see the official DPL MANUAL.
This document just hopes to give you enough information to be able to understand and make headway with both reading and understanding the DPL MANUAL and allowing you to use some of DPL's features to write Blender wiki articles.
DPL Example 1 - Full Article Inclusions
Below is an example of an article that has been included fully within this section of the document using DPL:
<dpl> titlematch=%Example usage 1
- mode = userformat
includepage = * </dpl>
The above is included using DPL. This can be proved by looking at the wiki code for that section. Below you can see the wiki code:
001 =DPL Example 1 - Full Article Inclusions= 002 Below is an example of an article that has been included fully within this section of 003 the document using DPL: 004 005 <DPL> 006 titlematch=%Example usage 1 007 includepage = * 008 </DPL> . . . (rest of the wiki code) . . .
Looking at the wiki code we can see that lines 001 to 004 are just normal wiki code and work in the normal way. Lines 005 to 008 aren't normal wiki code, they are using DPL code.
It can be seen that the section of article uses DPL in few ways.
- 1. Is that it is bounded by the markup tags <DPL> and </DPL> on lines 005 and 008. This tells Blender wiki to use the DPL reporting engine features to interpret the data between the <DPL> and </DPL> tags.
- 2. Looking at the wiki code between lines 001 and 008 nowhere does the phrase "Hi there, I am from a completely different Article contained in the Blender wiki someplace else." appear in the wiki code. Also above the included text there is a link titled "Meta:Guides/DPL for Blender's wiki/Example usage 1" which also isn't in the wiki code, and if clicked, the link takes you to the article which is being included.
005 <DPL> 006 titlematch=%Example usage 1 007 includepage = * 008 </DPL>
From the snippet of code above it can been seen that as well as the <DPL></DPL> enclosing tags there are also other options enclosed within the DPL tags, in this case "titlematch" and "includepage". These are DPL command options and say to DPL which article/s and how much of those article/s to include in the current wiki page.
Most DPL options are in the following format:
optionname=optionvalue
Where optionname is the name of the DPL command option you wish to set.
Where optionvalue is the value you wish to set for a DPL command optionname.
DPL command option titlematch
The DPL command option titlematch is used to tell DPL which page/s to process based on their page title.
The title of a Blender wiki page is usually displayed near the top of the page:
To tell DPL to process a page with the title "Example usage 1" you would use the following DPL code:
<DPL> titlematch=%Example usage 1 includepage=* </DPL>
The DPL command option titlematch, on its own wont produce any visible output in Blender wiki pages. What it does do is say that when a DPL command option that does output text is encountered it will be outputting text from pages that have a page title which matches the value of titlematch.
There are many DPL command options which actually output text onto a Blender wiki page, see includepage for details of one DPL command option that does this.
There are a few different ways of using the DPL command option titlematch but they are not covered here. For a full in-depth description of DPL command option titlematch see the official DPL MANUAL.
DPL command option includepage
The DPL command option includepage will tell DPL to include either specific sections or a whole page of text in the current wiki page.
<DPL> titlematch=%Example usage 1 includepage=* </DPL>
In the DPL code above the DPL command option includepage has a value of *. This says to the DPL command option includepage to include all text on the selected page/s and include them in the current wiki page.
DPL command option namespace
The DPL command option namespace will tell DPL to only search for information that is requested of it from within certain namespaces which are specified.
For example:
<DPL> namespace=Meta, Doc titlematch=%Example usage 1 includepage=* </DPL>
Would indicate that DPL will only use Meta: & Doc: namespaces to retrieve information requested using DPL.
This is useful for a number of things. It helps in cases where titlematch would match a document in multiple different namespaces, and by setting the namespace DPL command option to a particular namespace, you can prevent this.
Another use for the namespace option is that when using the titlematch DPL command option, sometimes titlematch will not match a valid page that starts with a namespace name.
For example:
<DPL> titlematch=Meta:%Example usage 1 includepage=* </DPL>
May not match even though "Meta:%Example usage 1" is a valid page. The Meta: namespace seems to upset DPL.
To get around this you would omit the namespace Meta: from the titlematch DPL command option and instead use the namespace DPL command option to indicate the namespace that needs to be searched instead.
The namespace DPL command option can accept 1 or more namespace names, just separate them with comma's.
It's also worth mentioning that the namespace option affects the way most DPL commands work not just titlematch, basically limiting where it can get information returned from.
DPL Example 2 - Marked Section Inclusions
Using DPL to include whole articles in a wiki page is very useful in certain situations, but there are other times when what is needed is to be more selective in what is taken from a DPL page and included in the current wiki page.
There are many ways to alter the selectivity of DPL when including text within a wiki page but one of the simpler and more powerful ways of doing so is to use "Marked Sections".
Marked Sections work by adding special DPL codes in a document which can later be used by other DPL documents to drag in specifically named areas of text, without having to drag in the rest of the document text into the current wiki page.
Here is an example of a document that has had parts of the wiki text marked up in DPL Marked Sections format:
This is a second example of DPL, this time though we want to include only certain sections of this document in the other documents. <section begin=the-first-section /> *This is the first section <section end=the-first-section /> <section begin=the-second-section /> *This is the second section <section end=the-second-section /> <section begin=the-third-section /> *This is the third section <section end= the-third-section />
In the above example there are 3 sections named "the-first-section", "the-second-section" and "the-third-section".
Each Marked Section is marked in the following format:
<section begin=sectionname /> Text contained within a section block goes here <section end=sectionname />
The sectionname can be any combination of alphabetic letters and numbers, but it is probably best to have a name with just letters and numbers and a - to represent spaces, so you can make the sectionname's easier to read. It is also a good idea to try and give the sectionname a meaningful name that informs the user just what is being included in that section.
Once the sections of the document have had their sections marked, the next step is to reference those Marked Sections in other documents.
Below is a section of document included with DPL:
<dpl> titlematch=%Example usage 2 includepage=the-second-section </dpl>
The difference with the above DPL inclusion text is that the DPL command option includepage, no longer has just a * (for including everything from the page specified in titlematch), but instead has the name of the Marked Section that will be inserted into the wiki page. The DPL code for this is shown below:
<DPL> titlematch=%Example usage-2 includepage=the-second-section </DPL>
As well as including a single named section with the DPL command option includepage, it is also possible to include more than one section using DPL command option includepage in following format:
<DPL> titlematch=%Example usage 2 includepage=the-second-section, the-third-section </DPL>
Which results in the following text being included in the wiki page:
<dpl> titlematch=%Example usage 2 includepage=the-second-section, the-third-section </dpl>
DPL Other Options
Almost all aspects of the ways in which DPL displays information on a Blender wiki page can be changed with various DPL command options. This section lists some of the other DPL option commands which can come in handy.
DPL command option mode
One of the things that you may have noticed while using Marked Sections and Full Page Inclusions was that every time you included an article or sections in a wiki page, the DPL engine added some extra formatting, see below for an example:
<dpl>
- mode=userformat
- listseparators=
- secseparators=
titlematch=DPL/DPL example usage 2 includepage=the-second-section, the-third-section </dpl>
As well as the original 2 Marked Sections "This is the second section" and "This is the third section", which is the data I marked up into sections and then used DPL command option includepage to include the 2 sections. There is also a link to the original page of the article above the top of the 2 sections, and the content of the 2 sections has been indented to the right, this is because the sections have been added to a list.
The above situation is fine if that is what you want, having the link to the original included section of the referenced document is useful (especially if you're a wiki editor who needs to update a section of DPL included text). Sometimes though what is needed is to be able to include text seamlessly within another page, to do that you need change the mode in which DPL operates.
This is done with the DPL command option mode.
Setting the DPL command option mode to the value of userformat, tells DPL to not do any automatic formatting on the included text and just present it as it is from the original wiki page/section.
<DPL> mode=userformat titlematch=DPL example usage-2 includepage=the-second-section, the-third-section </DPL>
Which produces the following output from DPL: <dpl> mode=userformat titlematch=DPL/DPL example usage 2 includepage=the-second-section, the-third-section </dpl>
The DPL command option mode=userformat, is doing much more than just telling DPL not to interfere with included text, it is telling DPL to respect the values of certain other DPL command options, which I haven't mentioned here, but since those other DPL command options are by default empty, using this setting means that it also gets rid of all the extraneous items added around the included data.
It is possible by setting DPL option command to mode=userformat to then specify how various included data items are formatted and laid out, if you want further information on this topic, go to the DPL MANUAL and read the information on mode
Blender Wiki Categories DPL-INCLUDE, DPL-SHARE & DPL?
When a page contains DPL code or is referenced by DPL, then it is probably a good idea to include a wiki-text category tag on the relevant pages indicating whether a page references text using DPL from another page (a DPL-INCLUDE category page) or if the page is a source of text included in another page (a DPL-SHARE category page).
To add a page to a DPL-INCLUDE category (thereby indicating that this page references text using DPL from some other section of the wiki) add the following wiki-text to the bottom of the page:
[[Category:DPL-INCLUDE]]
To add a page to a DPL-SHARE category (thereby indicating that this page is referenced by other pages using DPL, either for its entire page contents or just specific sections) add the following wiki-text to the bottom of the page:
[[Category:DPL-SHARE]]
This will later allow people to easily see if a page uses DPL and take extra care in altering the information in that DPL page, and make sure that altering a page which uses or is used by DPL, wont have unintended consequences.
A more general category that can be added to a page is called DPL. This category is more general because it covers use of features of DPL that do not include text from other documents, but are used for getting information, such as generating indexes and statistics dynamically.
To add a page to a DPL category add the following wiki-text to the bottom of the page:
[[Category:DPL]]
The Template:Subpages template is an example of a template that uses DPL features to generate a hierarchy page index. Doc:RU shows a page which uses the Subpages template and as a result also is in the DPL category.
If you click on the category tag for DPL-INCLUDE, DPL-SHARE or DPL you should be able to see all the pages that reference/use the contents of other pages (DPL-INCLUDE), are referenced by other pages (DPL-SHARE) or using other DPL features (DPL).
More depth to this page?
DPL is a large and very flexible extension. You could make a document 10 times the size of this one and still only be scratching the surface as to what it is capable of. This document is deliberately skipping describing most of the ways DPL can be used and just sticking to a few methods of using various aspects of DPL.
Remember that Blender wiki is about making it easy for wiki editors to write up documents and keep things updated with regards to Blender, in a quick and efficient manner. If a page has anything more than the simpler usages of DPL contained within it, then it could make updating pages difficult. If an editor has to fight with decoding the more complex and advanced DPL usages, it could be a real problem.
So with the above in mind.
If you feel that this page misses out important and useful features of DPL and feel that they should be included in this document then either, please add them or contact Terrywallwork and I will try to. I don't use any other features than the ones mentioned in this document, so I may not be able to help. Ultimately though if use and information on the more advanced features of DPL is required going to the DPL MANUAL website may be more useful to you.
Examples
Examples placed here.
