Open Stack

On 08/04/2014 11:04 PM, Anne Gentle wrote:
> 
> 
> 
> On Mon, Aug 4, 2014 at 11:48 AM, Andreas Jaeger <aj at suse.com
> <mailto:aj at suse.com>> wrote:
> 
>     On 08/04/2014 09:17 AM, Christian Berendt wrote:
>     > Andreas proposed to add a linked URL in parentheses after the
>     title/name
>     > of the URL instead of directly linking the title/name.
>     >
>     >
>     https://review.openstack.org/#/c/111593/3/doc/arch-design/introduction/section_intended_audience.xml
>     >
>     > While this makes sense for printed documents like the Architecture
>     > Design Guide it does not makes sense for online documents.
>     >
>     > How should we proceed? At the moment we use both forms in all of our
>     > documents.
>     >
>     > I would really prefer it to have the full URLs in footnotes in printed
>     > documents instead of having them in parentheses in the text. This
>     way we
>     > have nice online documents and nice printed documents. Is it possible
>     > with DocBook to put linked URLs automatically in the footnotes?
> 
>     I checked the IBM Style Guide and it said that for printed form to add
>     the URL in parentheses after the label like I did in that example.
> 
> 
> Oh, good thinking to look at the IBM Style Guide.  
>  
> 
> 
>     They also have another recommendation: To leave out the http:// in the
>     display, so the example would read:
> 
>     <citetitle>OpenStack Operations Guide</citetitle> (<link
>     xlink:href="http://docs.openstack.org/openstack-ops">docs.openstack.org/openstack-ops
>     <http://docs.openstack.org/openstack-ops></link>)
> 
>     Since we're publishing for both print and Online, should we follow
>     everywhere the above example - or do this only for those guides that are
>     printed?
> 
> 
> I'd like to have a style that works for both since all of our current
> content is single-sourced. 
> 
> I did mock up some footnote examples in this
> patch: https://review.openstack.org/#/c/111823/
> 
> But honestly, looking at it, I'm not a huge fan of footnotes, though
> they would take care of both print and online. 
> 
> In the Ops Guide sprint itself, our convention was to use the parens
> around the actual clickable link. Then we used O'Reilly's convention,
> and their production team had a shortener script. They also have fancy
> output helpers that put the full URL in parens,
> see: http://chimera.labs.oreilly.com/books/1234000000058/ch02.html#inserting_hyperlinks
> 
> Ideal state would be closest to what O'Reilly does for print and online
> looking slightly different but being very usable for either output.
> 
> Think we can get there? :)

This would mean we have to enhance our tools so that for PDF building,
they would do the proposed transformation. Something that could be done
in clouddocs-maven-plugin for an expert.

So, how to continue now with the URLs?

Should we use:
1) the normal style of
<link xlink:href="http://..">Fancy Site</link>
which breaks printed books unless we add postprocessing - which can be
done later...

2) the style as used in the printed books:
Fancy Site (<link xlink:href="http://..">http:/..</link>)

3) something else?

Additionally, how to show URLs? Should we say:
a) <link
xlink:href="http://www.openstack.org/">http://www.openstack.org</link>

b) or follow the IBM Style Guide to use remove the "http://":
<link xlink:href="http://www.openstack.org/">www.openstack.org</link>

Andreas
-- 
 Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi
  SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
   GF: Jeff Hawn,Jennifer Guild,Felix Imendörffer,HRB16746 (AG Nürnberg)
    GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126