[Intel-gfx] [PATCH 1/5] Documentation: drm: Fix pdfdocs sect/title tags

[Daniel Vetter]

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 at 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 at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/intel-gfx

-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch