Open Stack

On Thu, Aug 14, 2014 at 1:47 PM, Andreas Jaeger <aj at suse.com> wrote:

> 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>)
>
>
Here's my vote.

I'm fine with this for these three books:
Ops Guide
Security Guide
Arch Design Guide

For all other deliverables, do 1) the normal style, or adopt the "remove
the http:" style indicted in 3.b below.


> 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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140814/9a4e0818/attachment.html>