[PATCH v2 wayland 3/4] doc: Provide a fallback solution when Publican is not found

[Tiago Vignatti]

On 11/19/2012 11:55 AM, Pekka Paalanen wrote:
> On Mon, 19 Nov 2012 10:32:59 -0200
> Tiago Vignatti <tiago.vignatti at intel.com> wrote:
>
>> It provides a simple HTML solution extracted from DocBook. Also now XSLTPROC
>> is a strong requirement for building all the documentation (which is fair,
>> because is used for building both man-pages and the Wayland Manual).
>>
>> Signed-off-by: Tiago Vignatti <tiago.vignatti at intel.com>
>> ---
>> - changes since v1: now it uses a URL in the catalog file to find the given
>>    stylesheet (xhtml/docbook.xsl). This is the recommended way to do it. Also,
>>    this version strictly requires XSLTPROC for building all the documentation.
>>
>>   configure.ac            |   24 +++++++++++++++---------
>>   doc/Wayland/Makefile.am |    5 ++++-
>>   doc/man/Makefile.am     |    4 ----
>>   3 files changed, 19 insertions(+), 14 deletions(-)
>
> Hi Tiago,
>
> all the changes you did are good, and the build succeeds without any
> tweaking, but I'm still getting this:
>
> make[3]: Entering directory `/home/pq/git/wayland/doc/Wayland'
> /bin/mkdir -p en-US/images
> /usr/bin/xsltproc ./protocol-to-docbook.xsl \
> 		../../protocol/wayland.xml > en-US/ProtocolSpec.xml
> /bin/mkdir -p en-US/images
> /usr/bin/xsltproc ./protocol-interfaces-to-docbook.xsl \
> 		../../protocol/wayland.xml > en-US/ProtocolInterfaces.xml
> /bin/mkdir -p en-US/images
> mv ../../doc/doxygen/xml/wayland-client_8h.xml \
> 		../../doc/doxygen/
> /usr/bin/xsltproc ../../doc/doxygen/xml/combine.xslt \
> 		../../doc/doxygen/xml/index.xml > \
> 		../../doc/doxygen/xml/clientAPI.xml
> warning: failed to load external entity "../../doc/doxygen/xml/wayland-client_8h.xml"
> mv ../../doc/doxygen/wayland-client_8h.xml \
> 		../../doc/doxygen/xml
> /usr/bin/xsltproc ./doxygen-to-docbook.xsl \
> 		../../doc/doxygen/xml/clientAPI.xml > en-US/WaylandClientAPI.xml
>
>
> Notice the warning, though I'm not sure anything is actually missing in
> the result.

oh sorry, I forgot to explain the reason of this warning.

At Chapter 4, all the Client API section is being auto generated via 
doxygen commentaries on the code; specifically wayland-client.h and 
wayland-client.c. Because we separate all the methods in different 
classes, doxygen will output them in several XML files. So it end up 
with one file for each class (classwl__*.xml) containing the class 
description and the methods for it. So instead converting to DocBook one 
by one and later transform and group them in one HTML, I preferred to 
first combine all in one doxygen XML. The consequence of it is that it 
duplicates the methods outputted because we're reading twice them so we 
needed that hack of removing for a while one of the headers...

I'm sure there're better ways to solve this with the scripting language 
or something but I haven't tried enough. Anyway, this changes were 
introduced previously, not on the series in question.


> Do we need xmllint when xsltproc has --xinclude switch, too?

I guess so. That's how I learned to do the conversion.


Thanks for checking all and reviewing, Pekka. For Kristian, all the 
patches are rebased here now:

http://cgit.freedesktop.org/~vignatti/wayland/log/?h=doc

Tiago