style/style-links.xml

   1 <?xml version="1.0" encoding="utf-8"?>\r
   2 <chapter xml:id="style-links" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="EN"\r
   3     xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink">\r
   4 \r
   5     <info>\r
   6 \r
   7         <title>Creating Links</title>\r
   8     </info>\r
   9 \r
  10 <para>There are many way to link w/ docbook but the options in the table below cover the most common documentation scenarios.</para>\r
  11 \r
  12 \r
  13     <informaltable>\r
  14 \r
  15         <tgroup cols="4" align="left" colsep="1" rowsep="1">\r
  16 \r
  17             <thead>\r
  18                 <row>\r
  19                     <entry>Linking scenario</entry>\r
  20                     <entry>Syntax</entry>\r
  21                     <entry>Output</entry>\r
  22                     <entry>Notes</entry>\r
  23 \r
  24                 </row>\r
  25             </thead>\r
  26 \r
  27 \r
  28 \r
  29             <tbody>\r
  30                 <row>\r
  31                     <entry>Internal link with auto-generated link text</entry>\r
  32                     <entry><![CDATA[ <xref linkend="style-glossary"/> ]]></entry>\r
  33                     <entry>\r
  34                         <xref linkend="style-glossary"/>\r
  35                     </entry>\r
  36                     <entry>The <emphasis>linkend</emphasis> value (<emphasis>style-glossary</emphasis>) is the xml:id of\r
  37                         the target element; link text is auto-generated from the target. The tag is\r
  38                         self-closing (no <![CDATA[</xref>]]> closing tag required></entry>\r
  39                 </row>\r
  40                 <row>\r
  41                     <entry>Internal link with custom link text</entry>\r
  42                     <entry><![CDATA[ <link linkend="style-glossary">The Sitka glossary page</link> ]]></entry>\r
  43                     <entry><link linkend="style-glossary">The Sitka glossary page</link></entry>\r
  44                     <entry><emphasis>linkend</emphasis> is the <emphasis>xml:id</emphasis> of the target element; link text is supplied by author</entry>\r
  45                 </row>\r
  46                 <row>\r
  47                     <entry>External link</entry>\r
  48                     <entry><![CDATA[ <link xlink:href="https://bc.libraries.coop/" xlink:title="Link hover text goes here">https://bc.libraries.coop/</link> ]]></entry>\r
  49                     <entry><link xlink:href="https://bc.libraries.coop/" xlink:title="Link hover text goes here">https://bc.libraries.coop/</link></entry>\r
  50                     <entry><emphasis>xlink:href</emphasis> is the target URL. In Sitka docs show full URL so users can see it in PDF or copy and paste from the staff client (to open in a separate browser)</entry>\r
  51                 </row>\r
  52 <row>\r
  53                     <entry>External link open in New Tab</entry>\r
  54                     <entry><![CDATA[ <link xlink:show="new" xlink:href="https://bc.libraries.coop/"><emphasis role="bold">Sitka's Evergreen New Features in release 2.10 (5:55)</emphasis> </link> ]]></entry>\r
  55                     <entry><link xlink:show="new" xlink:href="https://bc.libraries.coop/" xlink:title="Link hover text goes here">https://bc.libraries.coop/</link></entry>\r
  56                     <entry><emphasis>xlink:show="new"</emphasis> opens the target in a New Browser Tab</entry>\r
  57                 </row>\r
  58 \r
  59 \r
  60             </tbody>\r
  61         </tgroup>\r
  62     </informaltable>\r
  63     \r
  64     <para>For internal links the hover tip text is generated automatically; for external links please include an xlink:title, otherwise the link hover text will be the name of the section or chapter where the link appears.</para>\r
  65 \r
  66 \r
  67 </chapter>\r