<div dir="ltr"><br><div class="gmail_extra"><br><br><div class="gmail_quote">On Mon, Aug 4, 2014 at 11:48 AM, 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:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div>On 08/04/2014 09:17 AM, Christian Berendt wrote:<br>
> Andreas proposed to add a linked URL in parentheses after the title/name<br>
> of the URL instead of directly linking the title/name.<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 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>
</div>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></blockquote><div><br></div><div>Oh, good thinking to look at the IBM Style Guide. </div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<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></link>)<br>
<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></blockquote><div><br></div><div>I'd like to have a style that works for both since all of our current content is single-sourced. </div><div><br></div><div>I did mock up some footnote examples in this patch: <a href="https://review.openstack.org/#/c/111823/" target="_blank">https://review.openstack.org/#/c/111823/</a></div>
<div><br></div><div>But honestly, looking at it, I'm not a huge fan of footnotes, though they would take care of both print and online. </div><div><br></div><div>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: <a href="http://chimera.labs.oreilly.com/books/1234000000058/ch02.html#inserting_hyperlinks">http://chimera.labs.oreilly.com/books/1234000000058/ch02.html#inserting_hyperlinks</a></div>
<div><br></div><div>Ideal state would be closest to what O'Reilly does for print and online looking slightly different but being very usable for either output.</div><div><br></div><div>Think we can get there? :)</div>
<div>Anne</div>
<div><br></div><div><br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<br>
AFAIK we have these printed guides: Architecture Design, Security Guide,<br>
HA Guide, Ops Guide.<br>
<span><font color="#888888"><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>
</font></span></blockquote></div><br></div></div>