Fix #59: Enforce para as first child in step

This fix is needed to avoid non-para elements as a first child in step. Related issue for the styleguide: SUSE/doc-styleguide#84
openSUSE · Mar 7, 2019 · ae0ba59 · ae0ba59
1 parent e8441f1
commit ae0ba59
Show file tree

Hide file tree

Showing 6 changed files with 119 additions and 39 deletions.
diff --git a/geekodoc/rng/geekodoc5-flat.rnc b/geekodoc/rng/geekodoc5-flat.rnc
@@ -162,38 +162,39 @@ div {
        | db.extension.blocks
        | db.admonition.blocks)*
   db.step.blocks =
-    db.para.blocks
-    | db.remark
-    | db.indexterm
-    | # TODO: Remove that (currently we have too much of that)
-      db.example
-    | db.figure
-    | db.informalexample
-    | db.informalfigure
-    | db.informaltable
-    | db.admonition.blocks
-    | db.graphic.blocks
-    | db.verbatim.blocks
-    | db.extension.blocks
-    | db.itemizedlist
-    | db.orderedlist
-    | db.simplelist
-    | db.variablelist
-    | db.calloutlist
-    | db.calloutlist
-    | db.annotation
-    | db.xi.include
-    | db.table
-  # no db.publishing.blocks, db.technical.blocks
-  # | db.formal.blocks - db.table - db.equation
-  # | db.informal.blocks - db.informaltable - db.informalequation
-  # | db.procedure
-  # | db.segmentedlist
-  # | db.glosslist
-  # | db.bibliolist
-  # | db.qandaset
-  # - - - -
-
+    (db.para.blocks
+     | db.remark
+     | db.indexterm
+     | # TODO: Remove that (currently we have too much of that)
+       db.example
+     | db.figure
+     | db.informalexample
+     | db.informalfigure
+     | db.informaltable
+     | db.admonition.blocks
+     | db.graphic.blocks
+     | db.verbatim.blocks
+     | db.extension.blocks
+     | db.itemizedlist
+     | db.orderedlist
+     | db.simplelist
+     | db.variablelist
+     | db.calloutlist
+     | db.calloutlist
+     | db.annotation
+     | db.xi.include
+     | db.table
+     | db.screen)
+    # no db.publishing.blocks, db.technical.blocks
+    # | db.formal.blocks - db.table - db.equation
+    # | db.informal.blocks - db.informaltable - db.informalequation
+    # | db.procedure
+    # | db.segmentedlist
+    # | db.glosslist
+    # | db.bibliolist
+    # | db.qandaset
+    # - - - -
+    *
 }
 div {
   db.xlink.hrefreq.simple.link.attributes =
@@ -10876,7 +10877,9 @@ div {
       element step {
         db.step.attlist,
         # db.step.info?,
-        ((db.step.blocks+,
+        db.remark?,
+        db.para,
+        ((db.step.blocks?,
           ((db.substeps | db.stepalternatives), db.step.blocks*)?,
           db.result?)
          | ((db.substeps | db.stepalternatives),

diff --git a/geekodoc/rng/geekodoc5.rnc b/geekodoc/rng/geekodoc5.rnc
@@ -117,7 +117,7 @@ db.entry.model =
 
 
 db.step.blocks =
-   db.para.blocks
+  ( db.para.blocks
    | db.remark
    | db.indexterm # TODO: Remove that (currently we have too much of that)
    | db.example
@@ -138,6 +138,7 @@ db.step.blocks =
    | db.annotation
    | db.xi.include
    | db.table
+   | db.screen
    # no db.publishing.blocks, db.technical.blocks
    #| db.formal.blocks - db.table - db.equation
    #| db.informal.blocks - db.informaltable - db.informalequation
@@ -147,6 +148,7 @@ db.step.blocks =
    #| db.bibliolist
    #| db.qandaset
    # ----
+   )*
 }
 
 div {
@@ -1507,12 +1509,17 @@ include "docbookxi.rnc"
     element step {
       db.step.attlist,
       # db.step.info?,
-      ((db.step.blocks+,
+      db.remark?,
+      db.para,
+      (
+       (db.step.blocks?,
         ((db.substeps | db.stepalternatives), db.step.blocks*)?,
         db.result?)
-       | ((db.substeps | db.stepalternatives),
+       |
+       ((db.substeps | db.stepalternatives),
           db.step.blocks*,
-          db.result?))
+          db.result?)
+      )
     }
   }
 

diff --git a/geekodoc/tests/bad/article-procedure-step-para.xml b/geekodoc/tests/bad/article-procedure-step-para.xml
@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<?xml-model href="../../rng/geekodoc5-flat.rnc" type="application/relax-ng-compact-syntax"?>
+<article xmlns="http://docbook.org/ns/docbook"
+    xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
+   <title>Procedure: para as first child of step</title>
+   <procedure>
+    <step>
+     <screen/>
+    </step>
+   </procedure>
+</article>
diff --git a/geekodoc/tests/bad/procedure-informalfigure-in-step.xml b/geekodoc/tests/bad/procedure-informalfigure-in-step.xml
@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<?xml-model href="../../rng/geekodoc5-flat.rnc" type="application/relax-ng-compact-syntax"?>
+<procedure xmlns="http://docbook.org/ns/docbook"
+    xmlns:xlink="http://www.w3.org/1999/xlink" version="5.1">
+    <title>A procedure with an invalid step</title>
+    <step>
+     <informalfigure>
+      <mediaobject>
+       <imageobject>
+        <imagedata fileref="just-an-image.png"/>
+       </imageobject>
+      </mediaobject>
+     </informalfigure>
+    </step>
+</procedure>
diff --git a/geekodoc/tests/good/book.storage.admin.xml b/geekodoc/tests/good/book.storage.admin.xml
@@ -1,4 +1,5 @@
 <?xml version="1.0"?>
+<?xml-model href="../../rng/geekodoc5-flat.rnc" type="application/relax-ng-compact-syntax"?>
 <book xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink" xml:base="book_storage_admin.xml" version="5.0" xml:lang="en" xml:id="book.storage.admin">
  <info>
   <title>Administration and Deployment Guide</title><productname>SUSE Enterprise Storage</productname><productname role="abbrev">SES</productname>
@@ -2892,8 +2893,7 @@ screen install-ses-admin</screen>
   </para>
 
   <procedure>
-   <step>
-    <warning>
+   <warning>
      <title>Do Not Run <command>zypper dup</command> or Reboot the Node</title>
      <para>
       After you prepare for the upgrade to SUSE Linux Enterprise Server 12 SP2 as suggested later in
@@ -2902,6 +2902,7 @@ screen install-ses-admin</screen>
       correctly.
      </para>
     </warning>
+   <step>
     <para>
      Upgrade the current SUSE Linux Enterprise Server to version 12 SP2. Refer to
      <link xlink:href="https://www.suse.com/documentation/sles-12/book_sle_deployment/data/cha_update_sle.html"/>
@@ -11018,6 +11019,7 @@ Superuser created successfully.
     </para>
    </step>
    <step>
+    <para/>
     <tip>
      <para>
       In order for Calamari to work correctly, the admin keyring needs to be

diff --git a/geekodoc/tests/good/procedure-step.xml b/geekodoc/tests/good/procedure-step.xml
@@ -0,0 +1,42 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<?xml-model href="../../rng/geekodoc5-flat.rnc" type="application/relax-ng-compact-syntax"?>
+<procedure version="5.1"
+    xmlns="http://docbook.org/ns/docbook"
+    xmlns:xlink="http://www.w3.org/1999/xlink">
+    <title>A procedure with valid steps</title>
+    <step>
+     <remark>Just a remark before a para</remark>
+     <para>A</para>
+    </step>
+    <step>
+     <para>B</para>
+     <remark>A remark after the para</remark>
+    </step>
+    <step>
+     <para>C</para>
+     <result>
+      <para/>
+     </result>
+    </step>
+    <step>
+     <para>D</para>
+     <screen/>
+     <substeps>
+      <step>
+       <para/>
+      </step>
+      <step>
+       <para/>
+      </step>
+     </substeps>
+     <para></para>
+    </step>
+    <step>
+     <para>E</para>
+     <itemizedlist>
+      <listitem>
+       <para/>
+      </listitem>
+     </itemizedlist>
+    </step>
+</procedure>