diff mbox

[1/5] Documentation: drm: Fix pdfdocs sect/title tags

Message ID 1440494805-13325-2-git-send-email-graham.whaley@linux.intel.com (mailing list archive)
State New, archived
Headers show

Commit Message

Graham Whaley Aug. 25, 2015, 9:26 a.m. UTC 
Building pdfdocs shows errors with !includes and <sect>s such as:
 jade:/Documentation/DocBook/drm.xml:666:11:E: document type does not
 allow element "para" here; missing one of "glossary", "bibliography",
 "index" start-tag
Fix by adding <title> items and add/shuffle <sect>, <title> and !include
items.

Signed-off-by: Graham Whaley <graham.whaley@linux.intel.com>
---
 Documentation/DocBook/drm.tmpl | 32 ++++++++++++++++++++++----------
 1 file changed, 22 insertions(+), 10 deletions(-)

Comments

Daniel Vetter Aug. 25, 2015, 11:34 a.m. UTC | #1 
On Tue, Aug 25, 2015 at 10:26:41AM +0100, Graham Whaley wrote:
> Building pdfdocs shows errors with !includes and <sect>s such as:
>  jade:/Documentation/DocBook/drm.xml:666:11:E: document type does not
>  allow element "para" here; missing one of "glossary", "bibliography",
>  "index" start-tag
> Fix by adding <title> items and add/shuffle <sect>, <title> and !include
> items.
> 
> Signed-off-by: Graham Whaley <graham.whaley@linux.intel.com>

The idea behind having both the overview sections and the detailed
function references in the same section is to have them in the same
section. Is there nothing we can do to salvage that? At least you seem to
add a lot more sections here, but it doesn't look entirely consistent.
-Daniel

> ---
>  Documentation/DocBook/drm.tmpl | 32 ++++++++++++++++++++++----------
>  1 file changed, 22 insertions(+), 10 deletions(-)
> 
> diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl
> index 66bc646..586f1b8 100644
> --- a/Documentation/DocBook/drm.tmpl
> +++ b/Documentation/DocBook/drm.tmpl
> @@ -303,6 +303,9 @@ char *date;</synopsis>
>        </para>
>  !Edrivers/gpu/drm/drm_pci.c
>  !Edrivers/gpu/drm/drm_platform.c
> +    </sect2>
> +    <sect2>
> +      <title>Calling Registration Directly</title>
>        <para>
>          New drivers that no longer rely on the services provided by the
>          <structname>drm_bus</structname> structure can call the low-level
> @@ -2352,7 +2355,7 @@ void intel_crt_init(struct drm_device *dev)
>        </itemizedlist>
>      </sect2>
>      <sect2>
> -      <title>Atomic Modeset Helper Functions Reference</title>
> +      <title>Atomic Modeset Helper Functions Introduction</title>
>        <sect3>
>  	<title>Overview</title>
>  !Pdrivers/gpu/drm/drm_atomic_helper.c overview
> @@ -2365,14 +2368,20 @@ void intel_crt_init(struct drm_device *dev)
>  	<title>Atomic State Reset and Initialization</title>
>  !Pdrivers/gpu/drm/drm_atomic_helper.c atomic state reset and initialization
>        </sect3>
> +    </sect2>
> +    <sect2>
> +      <title>Atomic Modeset Helper Functions Reference</title>
>  !Iinclude/drm/drm_atomic_helper.h
>  !Edrivers/gpu/drm/drm_atomic_helper.c
>      </sect2>
>      <sect2>
> +      <title>Modeset Helper Functions Introduction</title>
> +!Pdrivers/gpu/drm/drm_crtc_helper.c overview
> +    </sect2>
> +    <sect2>
>        <title>Modeset Helper Functions Reference</title>
>  !Iinclude/drm/drm_crtc_helper.h
>  !Edrivers/gpu/drm/drm_crtc_helper.c
> -!Pdrivers/gpu/drm/drm_crtc_helper.c overview
>      </sect2>
>      <sect2>
>        <title>Output Probing Helper Functions Reference</title>
> @@ -2432,8 +2441,8 @@ void intel_crt_init(struct drm_device *dev)
>      </sect2>
>      <sect2>
>        <title id="drm-kms-planehelpers">Plane Helper Reference</title>
> -!Edrivers/gpu/drm/drm_plane_helper.c
>  !Pdrivers/gpu/drm/drm_plane_helper.c overview
> +!Edrivers/gpu/drm/drm_plane_helper.c
>      </sect2>
>      <sect2>
>  	  <title>Tile group</title>
> @@ -2449,6 +2458,9 @@ void intel_crt_init(struct drm_device *dev)
>  	 <title>Default bridge callback sequence</title>
>  !Pdrivers/gpu/drm/drm_bridge.c bridge callbacks
>        </sect3>
> +    </sect2>
> +    <sect2>
> +      <title>Bridges Function Reference</title>
>  !Edrivers/gpu/drm/drm_bridge.c
>      </sect2>
>    </sect1>
> @@ -4114,19 +4126,19 @@ int num_ioctls;</synopsis>
>        <sect2>
>          <title>GTT Fences and Swizzling</title>
>  !Idrivers/gpu/drm/i915/i915_gem_fence.c
> -        <sect3>
> -          <title>Global GTT Fence Handling</title>
> +      </sect2>
> +      <sect2>
> +        <title>Global GTT Fence Handling</title>
>  !Pdrivers/gpu/drm/i915/i915_gem_fence.c fence register handling
> -        </sect3>
> -        <sect3>
> -          <title>Hardware Tiling and Swizzling Details</title>
> +      </sect2>
> +      <sect2>
> +        <title>Hardware Tiling and Swizzling Details</title>
>  !Pdrivers/gpu/drm/i915/i915_gem_fence.c tiling swizzling details
> -        </sect3>
>        </sect2>
>        <sect2>
>          <title>Object Tiling IOCTLs</title>
> -!Idrivers/gpu/drm/i915/i915_gem_tiling.c
>  !Pdrivers/gpu/drm/i915/i915_gem_tiling.c buffer object tiling
> +!Idrivers/gpu/drm/i915/i915_gem_tiling.c
>        </sect2>
>        <sect2>
>          <title>Buffer Object Eviction</title>
> -- 
> 2.4.3
> 
> _______________________________________________
> Intel-gfx mailing list
> Intel-gfx@lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/intel-gfx
Graham Whaley Aug. 25, 2015, 2:42 p.m. UTC | #2 
On Tue, 2015-08-25 at 13:34 +0200, Daniel Vetter wrote:
> On Tue, Aug 25, 2015 at 10:26:41AM +0100, Graham Whaley wrote:
> > Building pdfdocs shows errors with !includes and <sect>s such as:
> >  jade:/Documentation/DocBook/drm.xml:666:11:E: document type does
> > not
> >  allow element "para" here; missing one of "glossary",
> > "bibliography",
> >  "index" start-tag
> > Fix by adding <title> items and add/shuffle <sect>, <title> and
> > !include
> > items.
> > 
> > Signed-off-by: Graham Whaley <graham.whaley@linux.intel.com>
> 
> The idea behind having both the overview sections and the detailed
> function references in the same section is to have them in the same
> section. Is there nothing we can do to salvage that? At least you
> seem to
> add a lot more sections here, but it doesn't look entirely
> consistent.
> -Daniel
Let me go re-visit and have a look. I suspect there is an underlying
rule or feature of the processing that either has restrictions on
include ordering or section depth when including or both. I'll search
to see if there are any examples that currently work as we'd like these
to.
Thanks for the feedback.

Graham
> 
> > ---
> >  Documentation/DocBook/drm.tmpl | 32 ++++++++++++++++++++++--------
> > --
> >  1 file changed, 22 insertions(+), 10 deletions(-)
> > 
> > diff --git a/Documentation/DocBook/drm.tmpl
> > b/Documentation/DocBook/drm.tmpl
> > index 66bc646..586f1b8 100644
> > --- a/Documentation/DocBook/drm.tmpl
> > +++ b/Documentation/DocBook/drm.tmpl
> > @@ -303,6 +303,9 @@ char *date;</synopsis>
> >        </para>
> >  !Edrivers/gpu/drm/drm_pci.c
> >  !Edrivers/gpu/drm/drm_platform.c
> > +    </sect2>
> > +    <sect2>
> > +      <title>Calling Registration Directly</title>
> >        <para>
> >          New drivers that no longer rely on the services provided
> > by the
> >          <structname>drm_bus</structname> structure can call the
> > low-level
> > @@ -2352,7 +2355,7 @@ void intel_crt_init(struct drm_device *dev)
> >        </itemizedlist>
> >      </sect2>
> >      <sect2>
> > -      <title>Atomic Modeset Helper Functions Reference</title>
> > +      <title>Atomic Modeset Helper Functions Introduction</title>
> >        <sect3>
> >  	<title>Overview</title>
> >  !Pdrivers/gpu/drm/drm_atomic_helper.c overview
> > @@ -2365,14 +2368,20 @@ void intel_crt_init(struct drm_device *dev)
> >  	<title>Atomic State Reset and Initialization</title>
> >  !Pdrivers/gpu/drm/drm_atomic_helper.c atomic state reset and
> > initialization
> >        </sect3>
> > +    </sect2>
> > +    <sect2>
> > +      <title>Atomic Modeset Helper Functions Reference</title>
> >  !Iinclude/drm/drm_atomic_helper.h
> >  !Edrivers/gpu/drm/drm_atomic_helper.c
> >      </sect2>
> >      <sect2>
> > +      <title>Modeset Helper Functions Introduction</title>
> > +!Pdrivers/gpu/drm/drm_crtc_helper.c overview
> > +    </sect2>
> > +    <sect2>
> >        <title>Modeset Helper Functions Reference</title>
> >  !Iinclude/drm/drm_crtc_helper.h
> >  !Edrivers/gpu/drm/drm_crtc_helper.c
> > -!Pdrivers/gpu/drm/drm_crtc_helper.c overview
> >      </sect2>
> >      <sect2>
> >        <title>Output Probing Helper Functions Reference</title>
> > @@ -2432,8 +2441,8 @@ void intel_crt_init(struct drm_device *dev)
> >      </sect2>
> >      <sect2>
> >        <title id="drm-kms-planehelpers">Plane Helper
> > Reference</title>
> > -!Edrivers/gpu/drm/drm_plane_helper.c
> >  !Pdrivers/gpu/drm/drm_plane_helper.c overview
> > +!Edrivers/gpu/drm/drm_plane_helper.c
> >      </sect2>
> >      <sect2>
> >  	  <title>Tile group</title>
> > @@ -2449,6 +2458,9 @@ void intel_crt_init(struct drm_device *dev)
> >  	 <title>Default bridge callback sequence</title>
> >  !Pdrivers/gpu/drm/drm_bridge.c bridge callbacks
> >        </sect3>
> > +    </sect2>
> > +    <sect2>
> > +      <title>Bridges Function Reference</title>
> >  !Edrivers/gpu/drm/drm_bridge.c
> >      </sect2>
> >    </sect1>
> > @@ -4114,19 +4126,19 @@ int num_ioctls;</synopsis>
> >        <sect2>
> >          <title>GTT Fences and Swizzling</title>
> >  !Idrivers/gpu/drm/i915/i915_gem_fence.c
> > -        <sect3>
> > -          <title>Global GTT Fence Handling</title>
> > +      </sect2>
> > +      <sect2>
> > +        <title>Global GTT Fence Handling</title>
> >  !Pdrivers/gpu/drm/i915/i915_gem_fence.c fence register handling
> > -        </sect3>
> > -        <sect3>
> > -          <title>Hardware Tiling and Swizzling Details</title>
> > +      </sect2>
> > +      <sect2>
> > +        <title>Hardware Tiling and Swizzling Details</title>
> >  !Pdrivers/gpu/drm/i915/i915_gem_fence.c tiling swizzling details
> > -        </sect3>
> >        </sect2>
> >        <sect2>
> >          <title>Object Tiling IOCTLs</title>
> > -!Idrivers/gpu/drm/i915/i915_gem_tiling.c
> >  !Pdrivers/gpu/drm/i915/i915_gem_tiling.c buffer object tiling
> > +!Idrivers/gpu/drm/i915/i915_gem_tiling.c
> >        </sect2>
> >        <sect2>
> >          <title>Buffer Object Eviction</title>
> > -- 
> > 2.4.3
> > 
> > _______________________________________________
> > Intel-gfx mailing list
> > Intel-gfx@lists.freedesktop.org
> > http://lists.freedesktop.org/mailman/listinfo/intel-gfx
>
diff mbox

Patch

diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl
index 66bc646..586f1b8 100644
--- a/Documentation/DocBook/drm.tmpl
+++ b/Documentation/DocBook/drm.tmpl
@@ -303,6 +303,9 @@  char *date;</synopsis>
       </para>
 !Edrivers/gpu/drm/drm_pci.c
 !Edrivers/gpu/drm/drm_platform.c
+    </sect2>
+    <sect2>
+      <title>Calling Registration Directly</title>
       <para>
         New drivers that no longer rely on the services provided by the
         <structname>drm_bus</structname> structure can call the low-level
@@ -2352,7 +2355,7 @@  void intel_crt_init(struct drm_device *dev)
       </itemizedlist>
     </sect2>
     <sect2>
-      <title>Atomic Modeset Helper Functions Reference</title>
+      <title>Atomic Modeset Helper Functions Introduction</title>
       <sect3>
 	<title>Overview</title>
 !Pdrivers/gpu/drm/drm_atomic_helper.c overview
@@ -2365,14 +2368,20 @@  void intel_crt_init(struct drm_device *dev)
 	<title>Atomic State Reset and Initialization</title>
 !Pdrivers/gpu/drm/drm_atomic_helper.c atomic state reset and initialization
       </sect3>
+    </sect2>
+    <sect2>
+      <title>Atomic Modeset Helper Functions Reference</title>
 !Iinclude/drm/drm_atomic_helper.h
 !Edrivers/gpu/drm/drm_atomic_helper.c
     </sect2>
     <sect2>
+      <title>Modeset Helper Functions Introduction</title>
+!Pdrivers/gpu/drm/drm_crtc_helper.c overview
+    </sect2>
+    <sect2>
       <title>Modeset Helper Functions Reference</title>
 !Iinclude/drm/drm_crtc_helper.h
 !Edrivers/gpu/drm/drm_crtc_helper.c
-!Pdrivers/gpu/drm/drm_crtc_helper.c overview
     </sect2>
     <sect2>
       <title>Output Probing Helper Functions Reference</title>
@@ -2432,8 +2441,8 @@  void intel_crt_init(struct drm_device *dev)
     </sect2>
     <sect2>
       <title id="drm-kms-planehelpers">Plane Helper Reference</title>
-!Edrivers/gpu/drm/drm_plane_helper.c
 !Pdrivers/gpu/drm/drm_plane_helper.c overview
+!Edrivers/gpu/drm/drm_plane_helper.c
     </sect2>
     <sect2>
 	  <title>Tile group</title>
@@ -2449,6 +2458,9 @@  void intel_crt_init(struct drm_device *dev)
 	 <title>Default bridge callback sequence</title>
 !Pdrivers/gpu/drm/drm_bridge.c bridge callbacks
       </sect3>
+    </sect2>
+    <sect2>
+      <title>Bridges Function Reference</title>
 !Edrivers/gpu/drm/drm_bridge.c
     </sect2>
   </sect1>
@@ -4114,19 +4126,19 @@  int num_ioctls;</synopsis>
       <sect2>
         <title>GTT Fences and Swizzling</title>
 !Idrivers/gpu/drm/i915/i915_gem_fence.c
-        <sect3>
-          <title>Global GTT Fence Handling</title>
+      </sect2>
+      <sect2>
+        <title>Global GTT Fence Handling</title>
 !Pdrivers/gpu/drm/i915/i915_gem_fence.c fence register handling
-        </sect3>
-        <sect3>
-          <title>Hardware Tiling and Swizzling Details</title>
+      </sect2>
+      <sect2>
+        <title>Hardware Tiling and Swizzling Details</title>
 !Pdrivers/gpu/drm/i915/i915_gem_fence.c tiling swizzling details
-        </sect3>
       </sect2>
       <sect2>
         <title>Object Tiling IOCTLs</title>
-!Idrivers/gpu/drm/i915/i915_gem_tiling.c
 !Pdrivers/gpu/drm/i915/i915_gem_tiling.c buffer object tiling
+!Idrivers/gpu/drm/i915/i915_gem_tiling.c
       </sect2>
       <sect2>
         <title>Buffer Object Eviction</title>