1<refentry id="{@id}">
2 <refnamediv>
3  <refname>inline {@}link}</refname>
4  <refpurpose>Display a link to a URL, or link to an element's documentation in the the flow of descriptive text</refpurpose>
5 </refnamediv>
6 <refsynopsisdiv>
7  <refsynopsisdivinfo>
8   <author>
9    Gregory Beaver
10    <authorblurb>Tag Documentation written by {@link mailto:cellog@php.net cellog@php.net}</authorblurb>
11   </author>
12   <copyright>Copyright 2002, Gregory Beaver</copyright>
13   <releaseinfo>phpDocumentor 0.4+</releaseinfo>
14  </refsynopsisdivinfo>
15  <cmdsynopsis>
16   <group>
17    <cmdsynopsis>
18     <command>{@}link</command>
19     <arg choice="req">URL</arg>
20     <arg choice="opt"><option>description</option></arg>
21	 <arg choice="plain">}</arg>
22	</cmdsynopsis>
23    <cmdsynopsis>
24     <command>{@}link</command>
25     <arg choice="req">element</arg>
26     <arg choice="opt"><option>description</option></arg>
27	 <arg choice="plain">}</arg>
28	</cmdsynopsis>
29   </group>
30  </cmdsynopsis>
31 </refsynopsisdiv>
32 <refsect1 id="{@id description}">
33  <title>Description</title>
34  <para>The inline {@}link} tag is used to document any element (page, global variable, include, class, function, define, method, variable).</para>
35  <para><emphasis>New in version 1.2:</emphasis> You can link to any defined function in the current php version using the function's name.  This linking is done using the standard php function {@link PHP_MANUAL#get_defined_functions()}, and so relies on the version of php that is used to execute phpDocumentor.  A benefit of this method is that the function highlighting will automatically upgrade with a php upgrade without any change to the underlying code.  You may also link directly to any portion of the php website using the fake package override PHP_MANUAL (as in PHP_MANUAL#get_defined_functions, or PHP_MANUAL#support.php).</para>
36  <caution>inline {@}link} displays links directly in the natural text flow of a DocBlock.  If you want to display links prominently after descriptive text, use {@tutorial tags.see.pkg} or {@tutorial tags.link.pkg}.</caution>
37  <para>For parameter information, see {@tutorial tags.see.pkg} or {@tutorial tags.link.pkg}.  The guidelines for giving the element name to inline @link are the same as outlined in the {@tutorial tags.see.pkg} manual page.</para>
38 </refsect1>
39 <refsect1 id="{@id example}">
40  <title>Example</title>
41  <para>The inline {@}link} differs from ordinary non-inline tags.  Inline tags parse and display their output directly in the documentation.  In other words, this DocBlock:</para>
42  <para>
43   <programlisting role="php">
44   <![CDATA[
45/**
46 * Text with a normal @see and @link tag
47 * (the parentheses in "element()" are only necessary
48 * because it is a function)
49 * @see element()
50 * @link http://www.example.com
51 */
52function element()
53{
54}
55   ]]>
56   </programlisting>
57  </para>
58  <para>Parses as (with -o HTML:frames:default):</para>
59  <para>
60   <programlisting role="tutorial">
61   <![CDATA[
62<H3>element</H3>
63<P><B>element ( )</B></P>
64<!-- ========== Info from phpDoc block ========= -->
65<b></b>
66<pre>
67Text with a normal @see and @link tag (the parentheses in "element()" are only necessary because it is a function)
68</pre>
69<DL>
70	<DT>Function Parameters:</DT>
71
72
73	<DT>Function Info:</DT>
74	<DD><b>See</b> - <CODE><a href="../default/_fake_page_php.html#element">element()</a></CODE></DD>
75	<DD><b>Link</b> - <CODE><a href="www.example.com">www.example.com</a></CODE></DD>
76
77</DL>
78
79<HR>
80   ]]>
81   </programlisting>
82  </para>
83  <para>
84   <programlisting role="php">
85   <![CDATA[
86/**
87 * Text with an {@}link http://www.example.com Inline Link to a Hyperlink} and an inline
88 * link to {@}link element()} displays without a break in the flow
89 * (again, the parentheses in "element()" are only necessary
90 * because it is a function)
91 */
92function element()
93{
94}
95   ]]>
96   </programlisting>
97  </para>
98  <para>Parses as (with -o HTML:frames:default):</para>
99  <para>
100   <programlisting role="tutorial">
101   <![CDATA[
102<H3>element</H3>
103<P><B>element ( )</B></P>
104<!-- ========== Info from phpDoc block ========= -->
105<b></b>
106<pre>
107Text with an <a href="http://www.example.com">Inline Link to a Hyperlink</a> and
108an inline link to <a href="../default/_fake_page_php.html#element">element()</a>
109displays without a break in the flow (again, the parentheses in "element()" are only necessary
110because it is a function)
111</pre>
112<DL>
113	<DT>Function Parameters:</DT>
114
115
116	<DT>Function Info:</DT>
117
118</DL>
119
120<HR>
121   ]]>
122   </programlisting>
123  </para>
124 </refsect1>
125</refentry>