Open Stack

On 08/14/2014 08:56 PM, Anne Gentle wrote:
> 
> 
> 
> On Thu, Aug 14, 2014 at 1:47 PM, Andreas Jaeger <aj at suse.com
> <mailto: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>
>     > <mailto: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>
>     >     <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.

Anybody around that likes to implement the transformation?

>     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

In which variant - a or b below?

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


b) is something we could do wherever we have to give a complete URL.

We have URLs like
<link xlink:href="http://docs.openstack.org/arch-design">Architecture
Design Guide</link> - this is 1)

But there are URLs like:
<link xlink:href="http://www.openstack.org/">www.openstack.org</link>

So, I would combine this - for the three books, it could be (clear text)
2a) Arch Design Guide (http://docs.openstack.org/arch-design)
2b) Arch Design Guide (docs.openstack.org/arch-design)


And for other guides, these are the options to discuss:
1a) Go to http://www.openstack.org
1b) Go to www.openstack.org

Andreas
> 
>     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
>     <http://www.openstack.org></link>
> 
>     Andreas
>     --
>      Andreas Jaeger aj@{suse.com <http://suse.com>,opensuse.org
>     <http://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
> 
> 
> 
> 
> _______________________________________________
> Openstack-docs mailing list
> Openstack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
> 


-- 
 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