[PATCH] doc: Reduce the validation errors of the docbook input
ppaalanen at gmail.com
Thu Dec 18 06:20:38 PST 2014
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
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?
> > ---
> > 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(-)
More information about the wayland-devel