Open Stack

----- Original Message -----
> From: "David Cramer" <david.cramer at rackspace.com>
> To: "Steve Gordon" <sgordon at redhat.com>
> Cc: "Anne Gentle" <anne at openstack.org>, openstack-docs at lists.openstack.org
> Sent: Thursday, August 15, 2013 10:45:28 AM
> Subject: Re: [Openstack-docs] What's Up Doc? Aug 14, 2013
> 
> On 08/15/2013 09:34 AM, Steve Gordon wrote:
> >> 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.
> >>
> ...
> > 
> > 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].
> 
> So we could decide to use them in a way that would minimize the impact
> to Publican if that's important. For example, if we only use olinks to
> replace xrefs (i.e. for the convenience of inserting them via the Oxygen
> GUI), then the Publican workflow could just convert the olinks to xrefs
> and be done (in fact, that's what we do for olinks to a target in the
> same document).

Right, I already have a number of transforms that I apply [1] to achieve the goal of building with Publican - I'm just trying to ascertain what will be needed for this particular one :). Replacing with xrefs seems like what we've done previously when processing other content that contains olinks.

> For olinks between documents, we should have some conversations anyway
> about how to use them. Using them creates a dependency between documents
> that you'll want to take into account.

Yes, on our end for instance we ultimately build the documentation into RPMs for installation on a web server (or an end user workstation for that matter). If we can track these dependencies somehow then we can reflect them in the RPM, which would be very cool :).

Thanks,

Steve

[1] https://github.com/redhat-openstack/openstack-manuals-convert