style_guide/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 DIG glossary page</link> ]]></entry>\r
  43                     <entry><link linkend="style-glossary">The DIG 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="http://evergreen-ils.org/" xlink:title="Link hover text goes here">http://evergreen-ils.org/</link> ]]></entry>\r
  49                     <entry><link xlink:href="http://evergreen-ils.org/" xlink:title="Link hover text goes here">http://evergreen-ils.org/</link></entry>\r
  50                     <entry><emphasis>xlink:href</emphasis> is the target URL. It is good practice to show full URL so users can see it in PDF or copy and paste from pages displayed in the staff client (to open in a separate browser)</entry>\r
  51                 </row>\r
  52 \r
  53 \r
  54             </tbody>\r
  55         </tgroup>\r
  56     </informaltable>\r
  57     \r
  58     <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
  59 \r
  60 \r
  61 </chapter>\r