<div dir="ltr"><br><div class="gmail_extra"><br><br><div class="gmail_quote">On Thu, Aug 14, 2014 at 1:47 PM, Andreas Jaeger <span dir="ltr"><<a href="mailto:aj@suse.com" target="_blank">aj@suse.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div class="">On 08/04/2014 11:04 PM, Anne Gentle wrote:<br>
><br>
><br>
><br>
> On Mon, Aug 4, 2014 at 11:48 AM, Andreas Jaeger <<a href="mailto:aj@suse.com">aj@suse.com</a><br>
</div><div class="">> <mailto:<a href="mailto:aj@suse.com">aj@suse.com</a>>> wrote:<br>
><br>
> On 08/04/2014 09:17 AM, Christian Berendt wrote:<br>
> > Andreas proposed to add a linked URL in parentheses after the<br>
> title/name<br>
> > of the URL instead of directly linking the title/name.<br>
> ><br>
> ><br>
> <a href="https://review.openstack.org/#/c/111593/3/doc/arch-design/introduction/section_intended_audience.xml" target="_blank">https://review.openstack.org/#/c/111593/3/doc/arch-design/introduction/section_intended_audience.xml</a><br>
> ><br>
> > While this makes sense for printed documents like the Architecture<br>
> > Design Guide it does not makes sense for online documents.<br>
> ><br>
> > How should we proceed? At the moment we use both forms in all of our<br>
> > documents.<br>
> ><br>
> > I would really prefer it to have the full URLs in footnotes in printed<br>
> > documents instead of having them in parentheses in the text. This<br>
> way we<br>
> > have nice online documents and nice printed documents. Is it possible<br>
> > with DocBook to put linked URLs automatically in the footnotes?<br>
><br>
> I checked the IBM Style Guide and it said that for printed form to add<br>
> the URL in parentheses after the label like I did in that example.<br>
><br>
><br>
> Oh, good thinking to look at the IBM Style Guide.<br>
><br>
><br>
><br>
> They also have another recommendation: To leave out the http:// in the<br>
> display, so the example would read:<br>
><br>
> <citetitle>OpenStack Operations Guide</citetitle> (<link<br>
> xlink:href="<a href="http://docs.openstack.org/openstack-ops" target="_blank">http://docs.openstack.org/openstack-ops</a>"><a href="http://docs.openstack.org/openstack-ops" target="_blank">docs.openstack.org/openstack-ops</a><br>
</div>> <<a href="http://docs.openstack.org/openstack-ops" target="_blank">http://docs.openstack.org/openstack-ops</a>></link>)<br>
<div class="">><br>
> Since we're publishing for both print and Online, should we follow<br>
> everywhere the above example - or do this only for those guides that are<br>
> printed?<br>
><br>
><br>
> I'd like to have a style that works for both since all of our current<br>
> content is single-sourced.<br>
><br>
> I did mock up some footnote examples in this<br>
> patch: <a href="https://review.openstack.org/#/c/111823/" target="_blank">https://review.openstack.org/#/c/111823/</a><br>
><br>
> But honestly, looking at it, I'm not a huge fan of footnotes, though<br>
> they would take care of both print and online.<br>
><br>
> In the Ops Guide sprint itself, our convention was to use the parens<br>
> around the actual clickable link. Then we used O'Reilly's convention,<br>
> and their production team had a shortener script. They also have fancy<br>
> output helpers that put the full URL in parens,<br>
> see: <a href="http://chimera.labs.oreilly.com/books/1234000000058/ch02.html#inserting_hyperlinks" target="_blank">http://chimera.labs.oreilly.com/books/1234000000058/ch02.html#inserting_hyperlinks</a><br>
><br>
> Ideal state would be closest to what O'Reilly does for print and online<br>
> looking slightly different but being very usable for either output.<br>
><br>
> Think we can get there? :)<br>
<br>
</div>This would mean we have to enhance our tools so that for PDF building,<br>
they would do the proposed transformation. Something that could be done<br>
in clouddocs-maven-plugin for an expert.<br>
<br>
So, how to continue now with the URLs?<br>
<br>
Should we use:<br>
1) the normal style of<br>
<link xlink:href="http://..">Fancy Site</link><br>
which breaks printed books unless we add postprocessing - which can be<br>
done later...<br>
<br>
2) the style as used in the printed books:<br>
Fancy Site (<link xlink:href="http://..">http:/..</link>)<br>
<br></blockquote><div><br></div><div>Here's my vote.</div><div><br></div><div>I'm fine with this for these three books:</div><div>Ops Guide</div><div>Security Guide</div><div>Arch Design Guide</div><div><br></div>
<div>For all other deliverables, do 1) the normal style, or adopt the "remove the http:" style indicted in 3.b below.</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
3) something else?<br>
<br>
Additionally, how to show URLs? Should we say:<br>
a) <link<br>
xlink:href="<a href="http://www.openstack.org/" target="_blank">http://www.openstack.org/</a>"><a href="http://www.openstack.org" target="_blank">http://www.openstack.org</a></link><br>
<br>
b) or follow the IBM Style Guide to use remove the "http://":<br>
<link xlink:href="<a href="http://www.openstack.org/" target="_blank">http://www.openstack.org/</a>"><a href="http://www.openstack.org" target="_blank">www.openstack.org</a></link><br>
<div class="HOEnZb"><div class="h5"><br>
Andreas<br>
--<br>
Andreas Jaeger aj@{<a href="http://suse.com" target="_blank">suse.com</a>,<a href="http://opensuse.org" target="_blank">opensuse.org</a>} Twitter/Identica: jaegerandi<br>
SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany<br>
GF: Jeff Hawn,Jennifer Guild,Felix Imendörffer,HRB16746 (AG Nürnberg)<br>
GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126<br>
</div></div></blockquote></div><br></div></div>