A bunch of changes to the xsl transformation stylesheet to make Chapter 4
(Client API) look nicer and more readable.
Main changes:
- function synopsis listed
- lists for parameters and return values
- long function descriptions
- misc other hooks for "see also", "note", etc
The long description is a sore point. doxygen xml output is difficult to
parse with the output being in the form of
<detailed description>
<para>
<parameterlist> .... </parameterlist>
<simplesect kind="return">... </simplesect>
First paragraph of long description
</para>
<para>
Second paragraph of long <sometag>description</sometag>
</para>
</detaileddescription>
So we need to ignore parameterlist and simplesect, but extract the text from
everything else. Any improvements on that welcome.
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
The reason this directory exists is because we need to copy it into
$builddir so we can combine it with generated sources (we can't pass
multiple source paths into publican).
So instead of having en_US, renamed to en-US stop the confusion and rename
the sources to "sources". That gets copied to en-US which will then contain
the actual output.
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
This makefile is a bit hard to read due to some publican requirements and
the need to generate some files through XSLT. Explain the lot, so that those
looking at this roughly know what will hit them.
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
I found the comment a bit confusing and it's quite hard to read. re-explain
with a simple step-by-step list
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
Rename Overview.xml to Introduction.xml, reflecting the previous commit.
Organize also Wayland.xml order of the includes.
Signed-off-by: Tiago Vignatti <tiago.vignatti@intel.com>
Reviewed-by: Peter Hutterer <peter.hutterer@who-t.net>
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
In the beginning of the chapter, it was defined what is the so called "X"
thing and was removed the "Wayland" and "Weston" definitions cause we're
defining later at 1.2 anyway.
"Introduction", "Motivation" and "Compositing manager as the display server"
names sound better a bit than "Overview", "Replacing X11" and "Make the
compositing manager the display server" respectively. That was changed also.
Signed-off-by: Tiago Vignatti <tiago.vignatti@intel.com>
Reviewed-by: Peter Hutterer <peter.hutterer@who-t.net>
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
"1" sounds better when we mention about the "first" edition or say the
"publishing" edition.
If needed, we might want to increase the edition numbers automatically later,
for instance based on the micro version of the protocol or something like
that.
Signed-off-by: Tiago Vignatti <tiago.vignatti@intel.com>
Reviewed-by: Peter Hutterer <peter.hutterer@who-t.net>
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
In particular, the preface defines the scope of this document we're building
-- is the definition there enough with respect to what we want with this?
Signed-off-by: Tiago Vignatti <tiago.vignatti@intel.com>
Reviewed-by: Peter Hutterer <peter.hutterer@who-t.net>
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
Instead of relying on downloading the stylesheet from the Internet for
generating man pages, only generate them if the stylesheet is available
locally.
Signed-off-by: Jonas Ådahl <jadahl@gmail.com>
Instead of failing to generate documentation because xsltproc doesn't
exist, don't try to generate at all.
Signed-off-by: Jonas Ådahl <jadahl@gmail.com>
The amount of generated files and hacks over hacks in the doc/ directory
is getting out of hand and we need a better solution. For now, just get
distcheck back to working.
There's work to do still for giving a prettier style on the documentation, for
instance splitting paragraphs correctly and printing the detailed description
of the methods as well.
Signed-off-by: Tiago Vignatti <tiago.vignatti@intel.com>
Add some brief documentation for the public libwayland-client entry
points. This is by no means complete, some functions are still
undocumented and some might need extra information.
Signed-off-by: Ander Conselvan de Oliveira <ander.conselvan.de.oliveira@intel.com>
Signed-off-by: Tiago Vignatti <tiago.vignatti@intel.com>
The xsl translation from the protocol xml to publican would create only
one paragraph for all the text in a description. Make it generate one
paragraph for each block of text separated by two consecutive line
breaks instead.
Signed-off-by: Ander Conselvan de Oliveira <ander.conselvan.de.oliveira@intel.com>
Signed-off-by: Tiago Vignatti <tiago.vignatti@intel.com>
For now only Wayland Client API is described on that chapter, which is
extracted via doxygen on ./src/wayland-client.h. We apply a stylesheet
(doxygen-to-publican) on doxygen output so it becomes docbook valid.
Now all we need to do is populate that header while developing in order to
grow a decent documentation. So please use it!
Signed-off-by: Tiago Vignatti <tiago.vignatti@intel.com>
This way looks more pretty, in particular for the Appendix which spawns a big
subsections chain.
Signed-off-by: Tiago Vignatti <tiago.vignatti@intel.com>
Replace the outdated section about drag and drop support with a
rewritten section covering the data source/offer mechanism and
wl_data_device, explaining how selection and drag ang drop works.
We really shouldn't add the man-pages when HAVE_XSLTPROC is not true so
move it into the if-clause.
But declare the automake-variables outside of the if-clause to avoid
automake complaints.
Signed-off-by: David Herrmann <dh.herrmann@googlemail.com>
