Bug 83349

Summary: Migrate documentation away from Publican
Product: Wayland Reporter: Pekka Paalanen <ppaalanen>
Component: waylandAssignee: Wayland bug list <wayland-bugs>
Status: RESOLVED FIXED QA Contact:
Severity: enhancement    
Priority: medium CC: peter.hutterer
Version: unspecified   
Hardware: All   
OS: All   
Whiteboard:
i915 platform: i915 features:
Bug Depends on:    
Bug Blocks: 83429    
Attachments: 0001-doc-replace-publican-with-xmlto.patch

Description Pekka Paalanen 2014-09-01 11:26:19 UTC
Some distributions like Gentoo still haven't packaged Publican, so building the documentation gets tricky. The entry to building documentation should be especially low, as it encourages contributions, and we are lacking a lot of documentation.

Evaluate whether Publican really offers us added benefits, or could we just migrate to a more plain docbook(?) based documentation generator.
Comment 1 Peter Hutterer 2014-09-01 23:59:44 UTC
Created attachment 105579 [details] [review]
0001-doc-replace-publican-with-xmlto.patch

first attempt, turns out that we can just switch to xmlto for the html documentation. tested the pdf one but it failed with a missing cfg file and I haven't looked into that yet.

for the html documentation though it's quite easy, most of this is just making sure the file lists are updated.

it looks a bit different but that shouldn't matter much. And since we now ship the css files ourselves it'd be trivial to change that if anyone is motivated.
Comment 2 Peter Hutterer 2014-09-02 00:00:58 UTC
Probably worth adding the "stop excessive rebuilds" patch here too. Might conflict though, not sure.

http://lists.freedesktop.org/archives/wayland-devel/2014-September/017021.html
Comment 3 Pekka Paalanen 2014-09-04 08:54:27 UTC
The patch is on the mailing list, and scheduled for 1.7.
http://lists.freedesktop.org/archives/wayland-devel/2014-September/017086.html
Comment 4 Pekka Paalanen 2014-09-22 08:11:49 UTC
commit f3e7eedf1c0824639a816519ccfbdacb946cc63f
Author: Peter Hutterer <peter.hutterer@who-t.net>
Date:   Thu Sep 4 17:32:10 2014 +1000

    doc: replace publican with xmlto

Use of freedesktop.org services, including Bugzilla, is subject to our Code of Conduct. How we collect and use information is described in our Privacy Policy.