Open Stack

----- Original Message -----
> From: "Solly Ross" <sross at redhat.com>
> To: openstack-docs at lists.openstack.org
> Cc: "Lars Kellogg-Stedman" <lkellogg at redhat.com>
> Sent: Thursday, October 17, 2013 12:21:27 PM
> Subject: [Openstack-docs] Suggestion: Improved styling for "Replaceable" in	install guide
> 
> I was discussing the new install guide with Lars Kellogg-Stedman, and we were
> discussing how the underlying docbook metadata gets transformed into the
> final HTML and PDF products.  The idea came of up having some sort of tool
> tip show up for text tagged with "replaceable" to display more information
> about a particular "replaceable" entry.
> 
> For instance, the "EXTERNAL_INTERFACE" replaceable in the networking section
> could say something to the effect of "The external interface is the NIC
> responsible for enabling communication between your networks and the outside
> world".

Generally this is the kind of explanatory text I feel should be put immediately before a command that uses replaceable values rather than hidden in a tooltip. I suspect part of the issue that leads you to raise this is that we're missing such text entirely in many cases - so regardless of style we need to be better at highlighting in the prose what is replaceable, what it's replaceable with, and why. Perhaps it would be appropriate to mark these up as callout lists?:

    http://www.docbook.org/tdg/en/html/programlistingco.html

> At the very least, a static tooltip or style that better indicated that
> something should be replaced with an actual value would perhaps be useful
> (this could be accomplished pretty trivially in the style sheet for the
> docs).
> 
> What do people think?

In Publican styles we typically apply both bold and italic to replaceable values, I think at some point Summer already got David to add this to the clouddocs-maven styles though so I am unsure how to further proceed to make these "pop" as is. I'd personally be hesitant to use anything that only appears on mouseover because it hinders discoverability somewhat and may not be accessible at all in some output formats.

Thanks,

Steve