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

[Graham Whaley <graham.whaley@linux.intel.com>]

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
> 
_______________________________________________
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/intel-gfx