[PATCH] doc: Reduce the validation errors of the docbook input

[Pekka Paalanen]

On Wed, 10 Dec 2014 16:53:01 -0800
Bryce Harrington <bryce at osg.samsung.com> wrote:

> On Tue, Dec 09, 2014 at 07:33:51PM -0800, Bill Spitzak wrote:
> > This removes all the validation errors except for missing link
> > targets. You can test this by removing the --skip-validation
> > from doc/publican/Makefile.am.
> > 
> > Main changes are to add <simpara> to lists, remove some extra
> > <para> commands, and prefix all the id's so that collisions
> > between libclient and libserver are avoided.
> 
> I had to look up what a <simpara> was.  Still not entirely certain what
> the point of it vs. <para>, but if it gets rid of validation errors, +1
> to that.  I suppose it must solve some layout issues.
> 
> Sounds like places where we are using <para> for regular text we should
> rather be using <simpara>.
>  
> > The remaining errors are due to missing links, due to it not
> > copying doxygen's output for struct, union, and a macro. Turning
> > on HIDE_UNDOC in wayland.doxygen.in fixes a lot of these but
> > not all of them.
> > 
> > PS: it would be useful if somebody who actually knows something
> > about xslt would come up with a way to translate a block of text
> > makde of <para> commands unchanged, but add <para> around plain
> > text. Most of the difficulty is that doxygen's output is rather
> > inconsistent here.
> 
> Jon Cruz, are you listening?  ;-)
> 
> Anyway, the changes all look good to me.
> 
> Reviewed-by: Bryce Harrington <bryce at osg.samsung.com>

The changes to Chapter 4 are nice.

The changes to Appendix A seem to be lacking somewhat, we get things
like:

callback_data
    Type: uintrequest-specific data for the wl_callback

There should be some separation between the type and the explanation.
There used to be <p> tags, but now there is nothing.

In Appendices B and C I did not notice any breakage.

Could you revise this patch to fix that one issue?


I think this patch does too many things in one go, the para changes are
not related for the id namespacing, are they?


Thanks,
pq

> 
> > ---
> >  doc/publican/doxygen-to-publican.xsl            |   44 +++++++++--------------
> >  doc/publican/protocol-interfaces-to-docbook.xsl |    8 +++--
> >  doc/publican/protocol-to-docbook.xsl            |   10 +++---
> >  3 files changed, 27 insertions(+), 35 deletions(-)