Open Stack

----- Original Message -----
> From: "Anne Gentle" <anne at openstack.org>
> To: openstack-docs at lists.openstack.org, "OpenStack Development Mailing List" <openstack-dev at lists.openstack.org>
> Cc: "Glen Campbell" <glen.campbell at rackspace.com>, "Anne Gentle" <anne.gentle at rackspace.com>
> Sent: Wednesday, August 14, 2013 5:17:14 PM
> Subject: [Openstack-docs] What's Up Doc? Aug 14, 2013

> 5. Doc tools updates:
> The Maven plugin that builds our docs is sourced at
> https://github.com/rackerlabs/clouddocs-maven-plugin and just released
> version 1.9.0.
> 
> Our pom.xml files still point to 1.8.0 but we could start testing 1.9.0
> which adds supports for olinks. By using olinks instead of our current
> linking with xrefs would prevent Oxygen from showing non-valid file
> warnings in individual chapter files and adds an easier interface for
> finding cross-reference links. David Cramer can demo at the Boot Camp, and
> then we'll need to make decisions about how much cross-referencing we want.
> With fewer books going to a "released" docs site, we may want to limit the
> use of cross-references altogether, but let's discuss in person. Our
> current linking conventions are here:
> https://wiki.openstack.org/wiki/Documentation/Conventions#Linking.

I am going to be very active/interested in where we take this both because I'm not overly familiar with the use of olinks and because Publican doesn't currently support them (shenanigans ahead!) at this time. Does anyone have some good examples from other projects? The page in The DocBook Guide gives me the impression some of the key attributes are used in fairly implementation specific/defined ways [1].

Thanks,

Steve

[1] http://docbook.org/tdg5/en/html/olink.html