Allow tracing of grids in groups

This implements #569
speedata · Feb 3, 2025 · d954cf5 · d954cf5
1 parent ecf1dbc
commit d954cf5
Show file tree

Hide file tree

Showing 10 changed files with 219 additions and 3 deletions.
diff --git a/doc/commands-xml/commands.xml b/doc/commands-xml/commands.xml
@@ -11162,6 +11162,30 @@
         </description>
       </choice>
     </attribute>
+    <attribute en="groups" optional="yes" since="4.21.8">
+      <description xml:lang="en">
+        <para>Draw the grid inside all groups.</para>
+      </description>
+      <description xml:lang="de">
+        <para>Wenn 'yes', dann zeichnet der Publisher das zugrunde liegende Raster in den Gruppen.</para>
+      </description>
+      <choice en="yes">
+        <description xml:lang="en">
+          <para>Show the grid.</para>
+        </description>
+        <description xml:lang="de">
+          <para>Zeige das Raster.</para>
+        </description>
+      </choice>
+      <choice en="no">
+        <description xml:lang="en">
+          <para>Don't show the grid (default).</para>
+        </description>
+        <description xml:lang="de">
+          <para>Das Raster wird nicht angezeigt (Voreinstellung).</para>
+        </description>
+      </choice>
+    </attribute>
     <attribute en="hyphenation" optional="yes">
       <description xml:lang="en">
         <para>Draw little marks to show all hyphenation points.</para>

diff --git a/doc/dbmanual/assets/img/group-tracing.png b/doc/dbmanual/assets/img/group-tracing.png
diff --git a/doc/newmanual/adoc-de/gruppen.adoc b/doc/newmanual/adoc-de/gruppen.adoc
@@ -65,3 +65,44 @@ Richtig benutzt sind sie ein mächtiges Werkzeug.
 Ein Hinweis auf das Kapitel <<ch-optimierung-mit-gruppen>> sei noch erlaubt.
 Dort wird die Optimierung mit einem Beispiel beschrieben.
 
+
+== Tracing
+
+Um das Debuggen des Layouts innerhalb einer Gruppe zu erleichtern, können Sie die Rastervisualisierung einschalten:
+
+
+[source, xml]
+----------------
+<Layout xmlns="urn:speedata.de:2009/publisher/en"
+	xmlns:sd="urn:speedata:2009/publisher/functions/en">
+  <Pageformat height="6cm" width="9cm"></Pageformat>
+  <Trace groups="yes" />
+
+  <Record element="data">
+    <Group name="foo">
+      <Grid width="4mm" height="4mm"></Grid>
+      <Contents>
+        <PlaceObject>
+          <Textblock width="11">
+            <Paragraph>
+              <Value>Hello world</Value>
+            </Paragraph>
+          </Textblock>
+        </PlaceObject>
+        <PlaceObject column="1" row="4">
+          <Image width="3" file="_samplea.pdf" />
+        </PlaceObject>
+      </Contents>
+    </Group>
+    <PlaceObject groupname="foo" column="2" row="2" />
+  </Record>
+</Layout>
+----------------
+
+Das wird so angezeigt:
+
+.Das Raster in der Gruppe kann angezeigt werden.
+image::group-tracing.png[width=50%,scaledwidth=80%]
+
+
+// EOF
diff --git a/doc/newmanual/adoc-en/groups.adoc b/doc/newmanual/adoc-en/groups.adoc
@@ -66,4 +66,42 @@ Used correctly, they are a powerful tool.
 See the chapter <<ch-layoutoptimizationusinggroups>> for an example how to optimize layout using groups.
 
 
+== Tracing
+
+Do help debugging the layout within a group, you can turn on the grid visualization:
+
+[source, xml]
+----------------
+<Layout xmlns="urn:speedata.de:2009/publisher/en"
+	xmlns:sd="urn:speedata:2009/publisher/functions/en">
+  <Pageformat height="6cm" width="9cm"></Pageformat>
+  <Trace groups="yes" />
+
+  <Record element="data">
+    <Group name="foo">
+      <Grid width="4mm" height="4mm"></Grid>
+      <Contents>
+        <PlaceObject>
+          <Textblock width="11">
+            <Paragraph>
+              <Value>Hello world</Value>
+            </Paragraph>
+          </Textblock>
+        </PlaceObject>
+        <PlaceObject column="1" row="4">
+          <Image width="3" file="_samplea.pdf" />
+        </PlaceObject>
+      </Contents>
+    </Group>
+    <PlaceObject groupname="foo" column="2" row="2" />
+  </Record>
+</Layout>
+----------------
+
+which gets rendered as
+
+.The grid within the group gets displayed.
+image::group-tracing.png[width=50%,scaledwidth=80%]
+
+
 // EOF
diff --git a/schema/layoutschema-de.rng b/schema/layoutschema-de.rng
@@ -7029,6 +7029,17 @@
                </choice>
             </attribute>
          </optional>
+         <optional>
+            <attribute name="groups">
+               <a:documentation>Wenn &#39;yes&#39;, dann zeichnet der Publisher das zugrunde liegende Raster in den Gruppen.</a:documentation>
+               <choice>
+                  <value>yes</value>
+                  <a:documentation>Zeige das Raster.</a:documentation>
+                  <value>no</value>
+                  <a:documentation>Das Raster wird nicht angezeigt (Voreinstellung).</a:documentation>
+               </choice>
+            </attribute>
+         </optional>
          <optional>
             <attribute name="hyphenation">
                <a:documentation>Bei &#39;yes&#39; markiert der speedata Publisher die möglichen Trennstellen für die Silbentrennung.</a:documentation>

diff --git a/schema/layoutschema-de.xsd b/schema/layoutschema-de.xsd
@@ -8826,6 +8826,25 @@
           </xs:restriction>
         </xs:simpleType>
       </xs:attribute>
+      <xs:attribute name="groups">
+        <xs:annotation>
+          <xs:documentation>Wenn 'yes', dann zeichnet der Publisher das zugrunde liegende Raster in den Gruppen.</xs:documentation>
+        </xs:annotation>
+        <xs:simpleType>
+          <xs:restriction base="xs:token">
+            <xs:enumeration value="yes">
+              <xs:annotation>
+                <xs:documentation>Zeige das Raster.</xs:documentation>
+              </xs:annotation>
+            </xs:enumeration>
+            <xs:enumeration value="no">
+              <xs:annotation>
+                <xs:documentation>Das Raster wird nicht angezeigt (Voreinstellung).</xs:documentation>
+              </xs:annotation>
+            </xs:enumeration>
+          </xs:restriction>
+        </xs:simpleType>
+      </xs:attribute>
       <xs:attribute name="hyphenation">
         <xs:annotation>
           <xs:documentation>Bei 'yes' markiert der speedata Publisher die möglichen Trennstellen für die Silbentrennung.</xs:documentation>

diff --git a/schema/layoutschema-en.rng b/schema/layoutschema-en.rng
@@ -7029,6 +7029,17 @@
                </choice>
             </attribute>
          </optional>
+         <optional>
+            <attribute name="groups">
+               <a:documentation>Draw the grid inside all groups.</a:documentation>
+               <choice>
+                  <value>yes</value>
+                  <a:documentation>Show the grid.</a:documentation>
+                  <value>no</value>
+                  <a:documentation>Don&#39;t show the grid (default).</a:documentation>
+               </choice>
+            </attribute>
+         </optional>
          <optional>
             <attribute name="hyphenation">
                <a:documentation>Draw little marks to show all hyphenation points.</a:documentation>

diff --git a/schema/layoutschema-en.xsd b/schema/layoutschema-en.xsd
@@ -8826,6 +8826,25 @@
           </xs:restriction>
         </xs:simpleType>
       </xs:attribute>
+      <xs:attribute name="groups">
+        <xs:annotation>
+          <xs:documentation>Draw the grid inside all groups.</xs:documentation>
+        </xs:annotation>
+        <xs:simpleType>
+          <xs:restriction base="xs:token">
+            <xs:enumeration value="yes">
+              <xs:annotation>
+                <xs:documentation>Show the grid.</xs:documentation>
+              </xs:annotation>
+            </xs:enumeration>
+            <xs:enumeration value="no">
+              <xs:annotation>
+                <xs:documentation>Don't show the grid (default).</xs:documentation>
+              </xs:annotation>
+            </xs:enumeration>
+          </xs:restriction>
+        </xs:simpleType>
+      </xs:attribute>
       <xs:attribute name="hyphenation">
         <xs:annotation>
           <xs:documentation>Draw little marks to show all hyphenation points.</xs:documentation>

diff --git a/src/lua/publisher/commands.lua b/src/lua/publisher/commands.lua
@@ -3477,11 +3477,18 @@ function commands.place_object( layoutxml,dataxml)
         if not publisher.groups[groupname] then
             err("Unknown group %q in PlaceObject",groupname)
         else
-            objects[1] = { object = node.copy(publisher.groups[groupname].contents),
-                objecttype = string.format("Group (%s)", groupname)}
+            local g = publisher.groups[groupname]
+            objects[1] = { object = node.copy(g.contents),objecttype = string.format("Group (%s)", groupname)}
+            if publisher.options.showgroups then
+                local p = node.new(publisher.whatsit_node,publisher.pdf_literal_whatsit)
+                p.data = publisher.grid.draw_grid_group(g)
+                publisher.setprop(p,"origin","trace group")
+                objects[1].object.head = node.insert_before(objects[1].object.head,objects[1].object.head,p)
+
+            end
         end
     else
-        for i,j in ipairs(tab) do
+        for _,j in ipairs(tab) do
             object = publisher.element_contents(j)
             objecttype = publisher.elementname(j)
             if objecttype == "Image" then
@@ -5054,6 +5061,7 @@ function commands.trace(layoutxml,dataxml)
     local assignments      = publisher.read_attribute(layoutxml,dataxml,"assignments",   "boolean")
     local debug            = publisher.read_attribute(layoutxml,dataxml,"debug",         "boolean")
     local grid             = publisher.read_attribute(layoutxml,dataxml,"grid",          "boolean")
+    local groups           = publisher.read_attribute(layoutxml,dataxml,"groups",        "boolean")
     local gridallocation   = publisher.read_attribute(layoutxml,dataxml,"gridallocation","boolean")
     local gridlocation     = publisher.read_attribute(layoutxml,dataxml,"gridlocation",  "string")
     local hyphenation      = publisher.read_attribute(layoutxml,dataxml,"hyphenation",   "boolean")
@@ -5068,6 +5076,9 @@ function commands.trace(layoutxml,dataxml)
     if debug ~= nil then
         publisher.options.showdebug = debug
     end
+    if groups ~= nil then
+        publisher.options.showgroups = groups
+    end
     if grid ~= nil then
         publisher.options.showgrid = grid
     end

diff --git a/src/lua/publisher/grid.lua b/src/lua/publisher/grid.lua
@@ -688,6 +688,48 @@ function draw_frame(self,frame,width_sp)
     return table.concat(ret,"\n")
 end
 
+function draw_grid_group(group)
+    local ht = group.contents.height
+    local wd = group.contents.width
+    local ret = {"q 0.4 w [2] 1 d "}
+    local gray1 = "0.6"
+    local gray2 = "0.8"
+    local gray3 = "0.2"
+    local color = gray3
+    local g = group.grid
+    local gridwidth = g.gridwidth
+    local gridheight = g.gridheight
+    local x = 0
+    local y = 0
+    local i = 0
+    while x <= wd do
+        -- every 5 grid cells draw a gray rule
+        if (i % 5 == 0) then color = gray1 else color = gray2 end
+        -- every 10 grid cells draw a black rule
+        if (i % 10 == 0) then color = gray3 end
+        i = i + 1
+
+        ret[#ret+1] = string.format("%g G %g %g m %g %g l S", color, sp_to_bp(x), sp_to_bp(y), sp_to_bp(x), sp_to_bp(y - ht) )
+        x = x + gridwidth
+    end
+    x = 0
+    y = 0
+    local i = 0
+    while y <= ht do
+        -- every 5 grid cells draw a gray rule
+        if (i % 5 == 0) then color = gray1 else color = gray2 end
+        -- every 10 grid cells draw a black rule
+        if (i % 10 == 0) then color = gray3 end
+        i = i + 1
+
+        ret[#ret+1] = string.format("%g G %g %g m %g %g l S", color, 0, sp_to_bp(-1 * y), sp_to_bp(wd), sp_to_bp( -1 * y) )
+        y = y + gridheight
+    end
+
+    ret[#ret+1] = string.format("Q q 0 0 %g %g re S",sp_to_bp(wd),-1 * sp_to_bp(ht))
+    ret[#ret + 1] = "Q"
+    return string.format(table.concat(ret,"\n"))
+end
 
 -- Draw internal grid (return PDF-strings)
 function draw_grid(self)