D: Update documentation

This fixes #553 and #548

News.md

@@ -5,13 +5,18 @@ This file gets updated before a stable release. There is a [detailed changelog](
 
 ## Version 5
 
-* New XPath engine.
+* New defaults for the XPath engine and the font loader.
+
+## Version 4.18
+
+* New output / logging backend.
 
 ## Version 4.16
 
 Not yet released.
 
 * Complete overhaul of the MetaPost integration.
+* New XPath engine (optional).
 
 ## Version 4.14
 

doc/commands-xml/commands.xml

@@ -3665,18 +3665,18 @@
     </attribute>
     <attribute en="framecolor" type="text" optional="yes">
       <description xml:lang="en">
-        <para>The color of the frame around the object. Only makes sense in combination with the attribute 'frame'.</para>
+        <para>The color of the frame around the object. This defaults to 'black'. Can be hidden with the special color '-'.</para>
       </description>
       <description xml:lang="de">
-        <para>Die Farbe des Rahmens, wenn ein Rahmen ausgegeben wird. Nur sinnvoll zusammen mit dem Attribut rahmen.</para>
+        <para>Die Farbe des Rahmens, wenn ein Rahmen ausgegeben wird. Voreinstellung ist 'black'. Kann mit der speziellen Farbe '-' ausgeschaltet werden.</para>
       </description>
     </attribute>
     <attribute en="rulewidth" type="length" optional="yes">
       <description xml:lang="en">
-        <para>The thickness of the frame that is drawn around the object. Only makes sense in combination with the attribute 'frame'.</para>
+        <para>The thickness of the frame that is drawn around the object.</para>
       </description>
       <description xml:lang="de">
-        <para>Die Dicke des Rahmens, der um das Objekt gezogen wird. Nur sinnvoll zusammen mit dem Attribut rahmen.</para>
+        <para>Die Dicke des Rahmens, der um das Objekt gezogen wird. </para>
       </description>
     </attribute>
     <attribute en="class" optional="yes" type="text">

doc/newmanual/adoc-de/dateiorganisation.adoc

@@ -12,6 +12,7 @@ Daraus folgt:
 . Wenn sich während des Laufs etwas im Dateisystem ändert, bekommt der Publisher davon nichts mit.
 . Es ist egal, wie die Verzeichnisse heißen. Die Bilder können, müssen aber nicht, im Verzeichnis mit dem Namen »bilder« gespeichert sein.
 . Wenn das Arbeitsverzeichnis zu groß ist, ist der Startvorgang langsam. Einige Tausend Dateien im Arbeitsverzeichnis sind  in der Regel kein Problem.
+. Gibt es Duplikate im Dateibaum, wird eine Datei »zufällig« ausgewählt. Z.B. `data.xml` im Hauptverzeichnis und in einem Unterverzeichnis.
 
 Es gibt Ausnahmen von der Regel:
 
@@ -47,8 +48,6 @@ Es gibt zwei Möglichkeiten, die Dateien zusammenzuführen.
 Auf der Kommandozeile kann man mit `--extra-xml` ein oder mehrere Layoutregelwerke angeben, die zusätzlich eingelesen werden.
 Alternativ dazu kann man den Mechanismus über XInclude(((`Include`))) benutzen, hier im Fall einer Fontdefinition:
 
-// und  Fontdefinitionen kann man dann in eine eigene Datei auslagern (z. B. `dejavu.xml`) und so quasi »kapseln«:
-
 [source,xml]
 -------
 <Layout
@@ -82,7 +81,7 @@ Der Namensraum für XInclude muss wie oben deklariert werden, sonst gibt es eine
 [[ch-include_data]]
 == Daten in einzelne Dateien aufteilen
 Auch die Datendatei kann in mehrere Dateien aufgeteilt werden.
-Hierzu wird XInclude(((`Include`))) genutzt. 
+Hierzu wird XInclude(((`Include`))) genutzt.
 
 [source,xml]
 -------
@@ -94,7 +93,11 @@ Hierzu wird XInclude(((`Include`))) genutzt.
 </catalog>
 -------
 
-Im Wurzelknoten (im obigen Beispiel 'catalog') muss der Namensraum für XInclude deklariert werden. 
+Im Wurzelknoten (im obigen Beispiel 'catalog') muss der Namensraum für XInclude deklariert werden.
+
+=== XInclude und Schema
 
+Wird der XInclude-Mechanismus benutzt, so kann es sein, dass der XML Editor die `<xi:include ...>`-Anweisungen als unbekannt bemängelt.
+Um das zu verhindern, muss das RELAX NG Schema anstelle des XML-Schemas mit dem Editor verknüpft werden. Siehe das Kapitel <<ch-anhang-schemazuweisen,Schema zuweisen>>.
 
 // Ende

doc/newmanual/adoc-de/eingabeformat.adoc

@@ -187,7 +187,7 @@ Das nachfolgende Beispiel erzeugt für jedes Kindelement mit dem Namen `article`
     <PlaceObject>
       <Table stretch="max"> <!--1-->
         <Tablehead> <!--2-->
-          <Tr backgroundcolor="gray">
+          <Tr background-color="gray">
             <Td>
               <Paragraph><Value>Article number</Value></Paragraph>
             </Td>

doc/newmanual/adoc-de/farben.adoc

@@ -11,7 +11,7 @@ In der Regel reicht eine Angabe bei dem Objekt, das ausgegeben werden soll:
     <PlaceObject column="4" row="4">
       <Circle
          radiusx="2"
-         backgroundcolor="deeppink"
+         background-color="deeppink"
          framecolor="mediumaquamarine"
          rulewidth="8pt"/>
     </PlaceObject>
@@ -30,7 +30,7 @@ Farben können mit <<cmd-definecolor,`<DefineColor>`>> einem Namen zugewiesen un
 -------------------------------------------------------------------------------
 <DefineColor name="logocolor" model="cmyk" c="0" m="18" y="90" k="2" />
 <PlaceObject>
-  <Box height="4" width="3" backgroundcolor="logocolor" />
+  <Box height="4" width="3" background-color="logocolor" />
 </PlaceObject>
 -------------------------------------------------------------------------------
 
@@ -62,7 +62,7 @@ Im folgenden Fall ist die Sonderfarbe schon bekannt und kann ohne CMYK-Werte ben
 
 <Record element="data">
   <PlaceObject>
-    <Box width="5" height="2" backgroundcolor="logocolor"/>
+    <Box width="5" height="2" background-color="logocolor"/>
   </PlaceObject>
 </Record>
 -------------------------------------------------------------------------------
@@ -94,7 +94,7 @@ Farben können beim Benutzen direkt definiert werden:
 [source, xml]
 -------------------------------------------------------------------------------
 <PlaceObject allocate="no" column="3">
-    <Box height="4" width="5" backgroundcolor="#FFC72C"  />
+    <Box height="4" width="5" background-color="#FFC72C"  />
 </PlaceObject>
 -------------------------------------------------------------------------------
 

doc/newmanual/adoc-de/griffmarken.adoc

@@ -34,7 +34,7 @@ Es folgt ein Beispiel für Kapitelnummern in einer quadratischen Box.
       <PlaceObject column="200mm"
           row="{20 + 20 * $chapter}mm"> <!--2-->
 
-        <Box width="1cm" height="1cm" backgroundcolor="black"
+        <Box width="1cm" height="1cm" background-color="black"
              bleed="right"/> <!--3-->
       </PlaceObject>
 

doc/newmanual/adoc-de/indexerstellen.adoc

@@ -123,7 +123,7 @@ Anschließend wird für jeden Eintrag innerhalb dieses Abschnittes eine Zeile mi
       <Table width="3" stretch="max">
         <ForAll select="section">
           <Tr break-below="no" top-distance="10pt">
-            <Td colspan="2" backgroundcolor="lightgray">
+            <Td colspan="2" background-color="lightgray">
               <Paragraph><Value select="@name"></Value></Paragraph>
             </Td>
           </Tr>

doc/newmanual/adoc-de/kommandozeile.adoc

@@ -90,7 +90,7 @@ kann man sich eine Liste der erlaubten Befehle und Parameter ausgeben lassen.
 `--grid`::
    Zeichnet das Raster. Mit `--no-grid` wird es ausgeschaltet. Konfigurierbar auch im <<cmd-trace,Layout>> über den Befehl `<Trace>`.
 `--ignore-case`::
-    Ignoriere die Groß- und Kleinschreibung für Dateizugriff.
+    Ignoriere die Groß- und Kleinschreibung für Dateizugriff in der rekursiven Dateiliste.
 `--imagecache=PATH`::
    Setzt das Verzeichnis für den Bildzwischenspeicher (image cache). Das Verzeichnis wird bei Bedarf erstellt.
 `--inkscape=PATH`::

doc/newmanual/adoc-de/konfigurationsdatei.adoc

@@ -71,7 +71,7 @@ erkannt. Folgende Optionen werden unterstützt:
 `imagehandler`::
   Zuordnungen von Bildtyp zu externen Konvertern. Z.B. `imagehandler="mermaid:(/usr/bin/mmdc -i %%input%% -o %%output%%.pdf)"`. Der Bildtyp _mermaid_ wird mit dem Programm `/usr/bin/mmdc` konvertiert und erhält als Eingabeparameter `-i`, die Eingabedatei, `-o` und die Ausgabedatei mit angehängter Dateiendung `.pdf`. Die Dateinamen werden zur Laufzeit ersetzt und zufällig generiert. Mehrere Einträge werden mit Semikolon getrennt. Siehe auch <<ch-externalconverting>>.
 `ignore-case`::
-  Ignoriere die Groß- und Kleinschreibung für Dateizugriff.
+  Ignoriere die Groß- und Kleinschreibung für Dateizugriff in der rekursiven Dateiliste.
 `inkscape`::
   Pfad zum Inkscape-Programm.
 `inkscape-command`::

doc/newmanual/adoc-de/objekteausgeben.adoc

@@ -251,7 +251,7 @@ endif::[]
 [source, xml]
 -------------------------------------------------------------------------------
 <PlaceObject>
-  <Box width="4" height="3" backgroundcolor="limegreen"/>
+  <Box width="4" height="3" background-color="limegreen"/>
 </PlaceObject>
 -------------------------------------------------------------------------------
 
@@ -275,10 +275,10 @@ Kreise werden mit dem Befehl `<Circle>` ausgegeben:
 -------------------------------------------------------------------------------
 <Record element="data">
   <PlaceObject column="5" row="5">
-    <Circle radiusx="3" backgroundcolor="goldenrod"/>
+    <Circle radiusx="3" background-color="goldenrod"/>
   </PlaceObject>
   <PlaceObject column="5" row="5">
-    <Circle radiusx="1pt" backgroundcolor="black"/>
+    <Circle radiusx="1pt" background-color="black"/>
   </PlaceObject>
 </Record>
 -------------------------------------------------------------------------------

doc/newmanual/adoc-de/tabellen.adoc

@@ -101,7 +101,7 @@ Dh. in der Zeile
 
 haben alle Spalten bis auf die letzte die Ausrichtung »linksbündig«.
 
-In der Zeile kann auch die Hintergrundfarbe für die einzelnen Spalten festgelegt werden (`backgroundcolor`).
+In der Zeile kann auch die Hintergrundfarbe für die einzelnen Spalten festgelegt werden (`background-color`).
 Ebenso kann die minimale Höhe (`minheight`, Angabe in Rasterzellen bzw. einer Maßangabe) und der Abstand oberhalb der Zelle, sofern sie nicht auf einen Seitenumbruch folgt, festgelegt werden.
 
 [discrete]
@@ -137,7 +137,7 @@ Das bezieht sich auf die Anordnung innerhalb der Tabellenzelle:
         <Paragraph textformat="justified">
           <Value select="sd:dummytext()"/>
         </Paragraph>
-        <Box width="2" height="1" backgroundcolor="green"/>
+        <Box width="2" height="1" background-color="green"/>
       </Td>
     </Tr>
   </Table>
@@ -239,7 +239,7 @@ endif::[]
             <Paragraph><Value>1/3</Value></Paragraph>
           </Td>
         </Tr>
-        <Tr backgroundcolor="yellow">
+        <Tr background-color="yellow">
           <Td>
             <Paragraph><Value>2/1</Value></Paragraph>
           </Td>
@@ -373,7 +373,7 @@ Die Kopfzeile definiert man in der Tabelle wie folgt (als Kindelement des Elemen
 [source, xml,indent=0]
 -------------------------------------------------------------------------------
 <Tablehead>
-  <Tr backgroundcolor="gray">
+  <Tr background-color="gray">
     <Td>
       <Paragraph>
         <Value>Head</Value>
@@ -405,7 +405,7 @@ Das geht analog zu `<Tablehead>`, nur dass die Seitenauswahl anstelle von `first
 [source, xml,indent=0]
 -------------------------------------------------------------------------------
 <Tablefoot page="last">
-  <Tr backgroundcolor="gray">
+  <Tr background-color="gray">
     <Td>
       <Paragraph>
         <Value>Table foot last page</Value>
@@ -414,7 +414,7 @@ Das geht analog zu `<Tablehead>`, nur dass die Seitenauswahl anstelle von `first
   </Tr>
 </Tablefoot>
 <Tablefoot page="all">
-  <Tr backgroundcolor="gray">
+  <Tr background-color="gray">
     <Td>
       <Paragraph>
         <Value>Table foot for all pages</Value>
@@ -432,7 +432,7 @@ Sie können auch Linien und mehrere Zeilen enthalten. Werden bestimmte Kopf- ode
 -------------------------------------------------------------------------------
 <Tablefoot page="last" />
 <Tablefoot page="all">
-  <Tr backgroundcolor="gray">
+  <Tr background-color="gray">
     <Td>
       <Paragraph>
         <Value>Table foot for all pages</Value>
@@ -454,7 +454,7 @@ Beide Varianten können kombiniert werden.
 
 [source, xml,indent=0]
 -------------------------------------------------------------------------------
-<Tr sethead="yes" backgroundcolor="lightgray">
+<Tr sethead="yes" background-color="lightgray">
   <Td>
     <Paragraph>
       <Value>New head</Value>
@@ -494,7 +494,7 @@ In einer Schleife werden die gewünschten Zeilen ausgegeben.
     <PlaceObject>
       <Table padding="1mm" stretch="max">
         <ForAll select="section">
-          <Tr sethead="yes" backgroundcolor="lightgray">
+          <Tr sethead="yes" background-color="lightgray">
             <Td>
               <Paragraph>
                 <Value select="@name"/>
@@ -565,7 +565,7 @@ Um dies zu illustrieren, gibt es ein vollständiges Layoutregelwerk, das diesen
     <PlaceObject>
       <Table stretch="max">
         <Tablehead>
-          <Tr backgroundcolor="#eee">
+          <Tr background-color="#eee">
             <Td>
               <Paragraph>
                 <Value>Value of $_last_tr_data: </Value>
@@ -664,15 +664,15 @@ Eine etwas ausführlichere Beschreibung findet sich im Abschnitt <<ch-optimierun
 == Abwechselnde Zeilenfarben
 
 Wechselnde Zeilenfarben werden häufig in Tabellen mit vielen Spalten benutzt, um eine Hilfe für das Auge beim Lesen der Tabelle zu geben.
-Die Zeilenfarbe kann man durch `backgroundcolor="..."` bei `<Tr>` angeben.
+Die Zeilenfarbe kann man durch `background-color="..."` bei `<Tr>` angeben.
 
 
 .Wechselnde Zeilenfarben. Das erste Argument der Funktion  sd:alternating() ist eine Kennung, um verschiedene Alternierungen in einem Dokument zu unterscheiden.
 [source, xml, indent=0]
 -------------------------------------------------------------------------------
 <Table>
   <Loop select="5" variable="i">
-    <Tr backgroundcolor="{sd:alternating('tab', 'white', 'gray')}">
+    <Tr background-color="{sd:alternating('tab', 'white', 'gray')}">
       <Td>
         <Paragraph>
           <Value>Zeile </Value>
@@ -690,7 +690,7 @@ Die Zeilenfarbe kann man durch `backgroundcolor="..."` bei `<Tr>` angeben.
 image::tab-wechselnde-zeilenfarben.png[width=20%,scaledwidth=50%]
 
 Der Trick ist hier die Anwendung der Layoutfunktion `sd:alternating()`, die zwischen den Argumenten wechselt.
-Da das Attribut `backgroundcolor` einen festen Wert erwartet, muss mit den geschweiften Klammern in den »XPath-Modus« gesprungen werden.
+Da das Attribut `background-color` einen festen Wert erwartet, muss mit den geschweiften Klammern in den »XPath-Modus« gesprungen werden.
 
 Nach der Ausgabe der Tabelle ist nicht sichergestellt, dass beim nächsten Aufruf von `sd:alternating()` mit der Kennung `tab` wieder mit dem ersten Wert angefangen wird.
 Das kommt darauf an, welcher Wert zuletzt benutzt wurde.

doc/newmanual/adoc-de/umfliessenvonbildern.adoc

@@ -26,13 +26,13 @@ Das vollständige Beispiel ist unter https://github.com/speedata/examples/tree/m
   <Record element="data">
     <PlaceObject column="8" row="1" keepposition="yes">
       <Box width="3" height="6"
-           backgroundcolor="thistle" padding-left="2mm"
+           background-color="thistle" padding-left="2mm"
            padding-bottom="2mm"/>
     </PlaceObject>
 
     <PlaceObject column="1" row="12" keepposition="yes">
       <Box width="3" height="6"
-           backgroundcolor="lightgreen" padding-top="2mm"
+           background-color="lightgreen" padding-top="2mm"
            padding-right="2mm"/>
     </PlaceObject>
 

doc/newmanual/adoc-en/colors.adoc

@@ -11,7 +11,7 @@ The output of colors in speedata Publisher is very simple. Usually one specifica
     <PlaceObject column="4" row="4">
       <Circle
          radiusx="2"
-         backgroundcolor="deeppink"
+         background-color="deeppink"
          framecolor="mediumaquamarine"
          rulewidth="8pt"/>
     </PlaceObject>
@@ -31,7 +31,7 @@ Colors can be assigned to a name with <<cmd-definecolor,`<DefineColor>`>> and th
 -------------------------------------------------------------------------------
 <DefineColor name="logocolor" model="cmyk" c="0" m="18" y="90" k="2" />
 <PlaceObject>
-  <Box height="4" width="3" backgroundcolor="logocolor" />
+  <Box height="4" width="3" background-color="logocolor" />
 </PlaceObject>
 -------------------------------------------------------------------------------
 
@@ -63,7 +63,7 @@ In the following case, the spot color is already known and can be used without C
 
 <Record element="data">
   <PlaceObject>
-    <Box width="5" height="2" backgroundcolor="logocolor"/>
+    <Box width="5" height="2" background-color="logocolor"/>
   </PlaceObject>
 </Record>
 -------------------------------------------------------------------------------
@@ -94,7 +94,7 @@ HTML and CSS like colors can be used directly:
 [source, xml]
 -------------------------------------------------------------------------------
 <PlaceObject allocate="no" column="3">
-    <Box height="4" width="5" backgroundcolor="#FFC72C"  />
+    <Box height="4" width="5" background-color="#FFC72C"  />
 </PlaceObject>
 -------------------------------------------------------------------------------
 

doc/newmanual/adoc-en/commandline.adoc

@@ -95,7 +95,7 @@ you can display a list of the allowed commands and parameters.
 `--grid`::
    Display background grid. Disable with `--no-grid`
 `--ignore-case`::
-   Ignore case when accessing files (on a case-insensitive file system)
+   Ignore case when accessing files (on a case-insensitive file system) in the recursive file lookup.
 `--imagecache=PATH`::
    Set the image cache
 `--inkscape=PATH`::

doc/newmanual/adoc-en/configuration.adoc

@@ -63,7 +63,7 @@ The format of the file is important, otherwise it won’t be recognized. The fol
 `imagehandler`::
    Assignments of screen type to external converters. For example, `imagehandler="mermaid:(/usr/bin/mmdc -i %%input%% -o %%output%%%.pdf)"`. The image type _mermaid_ is converted with the program `/usr/bin/mmdc` and receives as input parameter `-i`, the input file, `-o` and the output file with attached file extension `.pdf`. The file names are replaced at runtime and generated randomly. Multiple entries are separated by semicolons. See also <<ch-externalconverting>>.
 `ignore-case`::
-   Ignore case when accessing files (on a case-insensitive file system).
+   Ignore case when accessing files (on a case-insensitive file system) in the recursive file lookup.
 `inkscape`::
    The path to the program inkscape when you need on the fly SVG to PDF conversion.
 `inkscape-command`::

doc/newmanual/adoc-en/fileorganization.adoc

@@ -11,6 +11,7 @@ It follows from this:
 . If something changes in the file system during the run, the Publisher will not notice this.
 . It does not matter what the directories are called. The images can, but do not have to be stored in the directory with the name "images".
 . If the working directory is too large, the startup process is slow. A few thousand files in the working directory are usually no problem.
+. If there are duplicates in the file tree, a file is selected “at random”. E.g. `data.xml` in the main directory and in a subdirectory.
 
 There are exceptions to the rule:
 
@@ -78,4 +79,10 @@ The data file can also be split into several files. XInclude is used for this.
 
 The namespace for XInclude must be declared in the root node (in the above example, 'catalog').
 
+=== XInclude and XML schema
+
+If the XInclude mechanism is used, it is possible that the XML editor will flag the `<xi:include ...>` statements as unknown.
+To prevent this, the RELAX NG schema must be linked to the editor instead of the XML schema. See the chapter <<ch-appendix-schema-assigning,Associate XML editor with schema>>.
+
+
 // EOF