Editing DPL3/Parameters: Controlling output format (section)

== General approach to output formatting ==

The general approach to output formatting is two-fold:

# There are a couple of simple predefined output formats which generate lists of articles.
#:You will understand their meaning directly from reading.
# There is a mode called {{dpl3|userformat}} which puts complete control into your hands.
#:This is somewhat complicated.

While the standard output formats are meant to be used for fast generation of simple page lists, the {{dpl3|userformat}} approach aims at transcluding contents from other pages and requires some effort to understand. There is a '''system of three tags''' which are used to enclose (a) the whole output, (b) each item, (c) each transcluded section of an item. A '''fourth tag''' is used to separate values between items of one section which occur more than once.

We assume that we have two documents which use templates {{tt|x}} and {{tt|y}} with varying arguments; while {{tt|x}} is being used once within each document, {{tt|y}} is used several times. In very short notation the structure might look as follows:
<pre style="padding-left:5px; width:30%">
 A: x(a) y(3) y(5)
 B: x(b) y(4) y(1) y(2)</pre>

The following DPL parameters are used to define a set of tags which are used to construct the output:
* {{dpl3|listseparators}} = ''liststart'',''itemstart'',''itemend'',''listend''
* {{dpl3|secseparators}} = ''sec-1-start'',''sec-1-end'',''sec-2-start'',''sec-2-end'', .. , ..
* {{dpl3|multisecseparators}} = ''multi-sep''
The arguments of the above statements can contain '''references to {{dpl3|VARIABLES|%VARIABLES%}}'''. So ''sec-1-start'' might contain a reference like {{tt|%PAGE%}} to output the page name. See {{dpl3|format}} for more details on variable substitution.

Now think of the following page inclusion statement:
<pre style="padding-left:5px; width:30%">
  includepage={x}.dpl,{y}.dpl</pre>

The output will then look like this:
<pre style="padding-left:5px; width:30%">
  liststart
     itemstart
        sec-1-start
           x.dpl(a)
        sec-1-end
        sec-2-start
           y.dpl(3)
           multi-sep
           y.dpl(5)
        sec-2-end
     itemend
     itemstart
        sec-1-start
           x.dpl(b)
        sec-1-end
        sec-2-start
           y.dpl(4)
           multi-sep
           y.dpl(1)
           multi-sep
           y.dpl(2)
        sec-2-end
     itemend
  listend</pre>

Assuming that the tags ({{tt|liststart}}, {{tt|itemstart}}, etc.) contain wiki syntax for table definitions and {{tt|multi-sep}} defines a horizontal line, the output might look like this:
<pre style="padding-left:5px; width:30%">
  +------+---------------------+
  |      |          | y.dpl(3) |
  |  A   | x.dpl(a) |  ----    |
  |      |          | y.dpl(5) |
  +------+----------+----------+
  |      |          | y.dpl(4) |
  |      |          |  ----    |
  |  B   | x.dpl(b) | y.dpl(1) |
  |      |          |  ----    |
  |      |          | y.dpl(2) |
  +------+----------+----------+</pre>

In some situations, however, you may want to create an output table where each of the calls of template {{tt|y}} is used to create a separate output row. Using a sortable table you could then easily rearrange the output.
<pre style="padding-left:5px; width:700px">
  +------+---------------------+       +------+---------------------+
  |  A   | x.dpl(a) | y.dpl(1) |       |  B   | x.dpl(b) | y.dpl(1) |
  +------+---------------------+       +------+---------------------+
  |  A   | x.dpl(a) | y.dpl(2) |       |  B   | x.dpl(b) | y.dpl(2) |
  +------+---------------------+       +------+---------------------+
  |  B   | x.dpl(b) | y.dpl(3) |       |  A   | x.dpl(a) | y.dpl(3) |
  +------+---------------------+       +------+---------------------+
  |  B   | x.dpl(b) | y.dpl(4) |       |  A   | x.dpl(a) | y.dpl(4) |
  +------+---------------------+       +------+---------------------+
  |  B   | x.dpl(b) | y.dpl(5  |       |  B   | x.dpl(b) | y.dpl(5) |
  +------+---------------------+       +------+---------------------+</pre>

There is a special parameter called {{dpl3|dominantsection}} which you can use to mark one section of your {{dpl3|includepage}} statement as "dominant" (in our example: {{dpl3|dominantsection|=2}} as {{tt|{y}.dpl}} is the second argument of our {{dpl3|includepage}} statement). You can only have one dominant section in a DPL statement. Marking a section as "dominant" only makes sense if you have multiple calls of the same template (or multiple chapters with the same heading) in your documents. Each piece of content in the dominant section will generate an individual output row with the values of all other columns being repeated.

----
As all of the above is not very easy to understand there are additional DPL commands ({{dpl3|table}}, {{dpl3|tablerow}}) which make it fairly easy to create tabular output.