Publican isn't packaged for some distros, xmlto is a lot more common. Most of
what publican provides for us is the stylesheet anyway, so we can just use
xmlto and the publican stylesheet to get roughly the same look.
PDF and XML generation has been dropped, this needs a bit more more effort
than a mere switchover to xmlto.
The top-level directory structure imposed by publican is kept for now
(specifically the Wayland/en-US/html tree). This makes it easier to transition over
for packagers. Note that the list of files inside has changed.
CSS files are taken from publican to keep a uniform look compared to previous
documentations. Stylesheets are licensed under CC0 1.0 Universal license, see
publican/LICENSE:
1. Files in the datadir/Common_Content directory and its subdirectories are
licensed under the CC0 1.0 Universal license.
To the extent possible under law, the developers of Publican waive all
copyright and related or neighboring rights to the files contained
in the datadir/Common_Content directory and its subdirectories.
Acked-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
Same reason as commit cd31275f28b0a04d2ec5426dc81e875197b47e52 from weston:
The scanner needs to be good enough. If it crashes or fails to report
invalid input, that needs to get fixed.
If posix_fallocate is available, use it instead of ftruncate. Unlike
ftruncate, when posix_fallocate succeeds, it guarantees that you cannot
run out of disk space, when later writing to the mmap()'ed file.
With posix_fallocate, if os_create_anonymous_file() succeeds, the
program cannot get a SIGBUS later from accessing this file via mmap. If
there is insufficient disk space, the function fails and errno is set to
ENOSPC.
This is useful on systems, that limit the available buffer space by
having XDG_RUNTIME_DIR on a small tmpfs.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
The scanner is not very forgiving if the protocol doesn't match it's
expectations and crashes without much of a notice. Thus, validate the protocol
against a DTD.
Move the protocol subdir forward so we validate first before trying anything
else, and install the DTD so we can validate weston's protocols as well.
This sure is ugly - we feed output of publican -v into bc to compare
against minimum required version, 2.8. That's bad enough, but when
publican suddenly report 3.0.0, bc starts complaining...
Use sed to filter out 3.0 from the 'version=3.0.0' output from publican
instead. Seem a little more robust, but it's just a matter of time before
something else breaks this flaky setup.
Hey, publican, how about shipping .pc files?
This directory was called Wayland during my early tries with publican where
the source layout was different and it needed to be set to the same name as
the publican output directory. This reason doesn't exist anymore, so re-name
it to publican to make it more obvious what's hiding in here.
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
The idea was to use 1.1.0 for the git master version, so that git master
would always be newer than any release or 1.1.x version. This means
we have to skip 1.1 as a release, which turns out to be confusing.
We can just use version 1.0.90 instead, which lets us call the next
release 1.1.0.
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>
5909dddc78 removed protocol/Makefile.am
which meant protocol/wayland.xml no longer got included in the tarball.
Add back protocol/Makefile.am and configure.ac bits and add protocol to
subdirs in Makefile.am to fix this.
This was added previously (commit 015c42e1) when we didn't have docbook
formatted documentation. Now it became quite useless.
Signed-off-by: Tiago Vignatti <tiago.vignatti@intel.com>
Also, now doxygen is mandatory for building the documentation (looks
reasonable because both man-pages and publican will need it).
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 adds a man-page infrastructure based on Docbook XML files. This
allows us to integrate the man-pages into the publican books later. An
example page for wl_display_connect() (with an alias
wl_display_connect_to_fd()) is also added.
Feel free to add more man-pages. Function calls are put in man3 and
overview pages into man7. All pages (including aliases) have to be added
to the Makefile.
Docbook does generate aliases automatically from the additional names that
were put in the XML file. However, a small SED script is needed to fixup
the include-paths in the generated troff files. If someone knows how to
avoid that (or even install them gzip'ped), please fix it up.
Signed-off-by: David Herrmann <dh.herrmann@googlemail.com>
