sitefaqlet SiteDocClan siteusage  <h1>Shortcuts</h1> <h4>(See also: [id://29281]) [pmdev://43235|(handlelinks settings)|]</h4> Shortcuts are our shorthand way of creating links. You can use these in your writeups, and in public and private messages you send. Shortcuts all have the form <tt>[linkspec|link text]</tt>. The link text part is optional. If you omit it (and the vertical bar separator), default link text will be used. Each shortcut type, catalogued below, has specialized default link text. <a href="#usage">Jump down to see the shortcut usage instructions</a>. <hr/> <h2><a name="shortcuts"></a>Available Shortcut Types:</h2> <h3>To link to:</h3> <dl> <dt><a name="nodes">Nodes:</a></dt><dd> <li><a name="node_by_title"></a>By Title: <tt>[title terms]</tt> This does a Simple Search. If exactly one node matches, the user is taken directly to that node. Otherwise, a page of search results is displayed.1</li> <li><a name="node_by_id"></a>By Numeric Node ID: <tt>[id://nodeid]</tt> See [id://17441] for tips on how to get the ID of a node. With the number omitted, <tt>[id://]</tt> links to that FAQlet.</li>  </dd> <dt><a name="link_to_user">A User:</a></dt><dd> <tt>[username]</tt>. E.g. <tt>[vroom]</tt> ⇒ [vroom] In fact, this is just a case of linking to a node by title. For each user, there is a node with the same name (their "homenode"). Linking to a user this way is really just linking to their homenode. You can also link to a user's adjunct pages: <li><a name="pad"></a>Link to a user's [id://418988|scratchpad]: <tt>[pad://username]</tt> </li> <li><a name="my_pad"></a>Link to your own [id://418988|scratchpad]: <tt>[pad://]</tt> </li> <li><a name="writeups"></a>Link to the list of a user's [id://6364|writeups]: <tt>[by://username]</tt> </li> <li><a name="my_writeups"></a>Link to the list of your own [id://6364|writeups]: <tt>[by://]</tt> </li> </dd> <dt><a name="outbox">The [Message Outbox]:</a></dt><dd> You can write <pre> [msg://] </pre> which simply links to the Message Outbox. You can have your link pre-populate the "To:" field of Message Outbox by writing <pre> [msg://recipient] </pre> In either case, you can override the default link title text, as usual: <pre> [msg://|link title text] [msg://recipient|link title text] </pre> If you omit the title text but provide a recipient name, the recipient name will be used in formulating the link text. You can also pre-populate the message text ("Say:") field of the Message Outbox form, like so: <pre> [msg://recipient<message text|link title text] </pre> If you omit the title text but provide message text, the message text will be used in formulating the link text. All three arguments are optional. You can, for example, write <pre> [msg://<message text] </pre> If you provide message text but omit the recipient name and title text (as in the case above), the link text will be generated for you, and it will contain a <tt>?</tt> character in place of the username. (The "To:" field in the Message Outbox form will still be left blank, however.) </dd> <dt><a name="cpan">CPAN:</a></dt><dd> <li>Module documentation: <tt>[mod://XML::Parser]</tt></li> <li>A distribution on CPAN: <tt>[dist://XML-Parser]</tt> or <tt>[dist://XML-Parser-2.33]</tt></li> <li>General search for modules by name on: <tt>[cpan://XML::Parser]</tt> </li> <li>Module documentation on [https://metacpan.org|metacpan.org]: <tt>[metamod://XML::Parser]</tt></li> <li>A distribution on [https://metacpan.org|metacpan.org]: <tt>[metadist://XML-Parser]</tt></li> <li>General search for modules by name on [https://metacpan.org|metacpan.org]: <tt>[metacpan://XML::Parser]</tt> </li>  <li>A specific bug in CPAN's [rt://|RT] system: <tt>[rt://8138]</tt></li> <li>A distribution in [rt://|RT]: <tt>[rt://XML-Parser]</tt></li> <li>A search in [rt://|RT]: <tt>[rt://object serialization]</tt></li> <li>The [dist://|CPAN search page]: <tt>[dist://]</tt> or <tt>[mod://]</tt> (no args)</li> <li>The [cpan://|CPAN main page]: <tt>[cpan://]</tt> (no args)</li> <li>The [rt://|CPAN RT main page]: <tt>[rt://]</tt> (no args)</li> </dd> <dt><a name="doc">The [http://perldoc.perl.org/|Perl documentation]:</a></dt><dd> <li>Search the Perl docs: <tt>[perldoc://search terms]</tt></li> <li>Link directly to a the doc of a function or variable: <tt>[doc://name]</tt> e.g. <tt>[doc://-X|file test ops]</tt></li> <li>Link directly to a specific document by name: <tt>[doc://name]</tt> e.g. <tt>[doc://perlipc]</tt></li> <li>Link to a section internal to a doc: <tt>[doc://name#anchor]</tt> e.g. <tt>[doc://perlfaq2#Perl-Books]</tt> (Note, this replaces hyphens with spaces for the link text. Try it!)</li> <li>Link to standard module docs: <tt>[mod://name]</tt> e.g. <tt>[mod://File::Find]</tt>, <tt>[mod://strict]</tt> (Note that <tt>[module://</tt> is an alias for <tt>[mod://</tt>, for those who like to type more.)</li> <li>[doc://|Perl Online Documentation] site: <tt>[doc://]</tt> or <tt>[perldoc://]</tt> (no args)</li> See [id://370907] for more info. </dd> <dt><a name="apc">[apc://|Perl Source Code files/patches]:</a></dt><dd> <li> A file: <tt>[apc://file]</tt>, e.g. <tt>[apc://perl.c|[apc://perl.c]]</tt></li> <li> A patch: <tt>[apc://patchNum]</tt>, e.g. <tt>[apc://1575|[apc://1575]]</tt></li> <li> A file at a given patch number: <tt>[apc://file@patchNum]</tt>, e.g. <tt>[apc://perl.c@1575|[apc://perl.c@1575]]</tt></li> <li> The [apc://|perl code repo browse/search form]: <tt>[apc://]</tt> (no args)</li> Note: the scheme for this shortcut type is apc because it originally linked to the Archive of Perl Changes, hosted by ActiveState. </dd> <dt><a name="aes">[aes://|Official Raku (Perl 6) documentation]</a></dt> <dd> <li> A Synopsis (specification) by number: <tt>[aes://s06]</tt> ⇒ [aes://s06] </li> <li> An Apocalypse (justification) by number: <tt>[aes://a06]</tt> ⇒ [aes://a06] </li> <li> An Exegesis (explanation) by number: <tt>[aes://e06]</tt> ⇒ [aes://e06] </li> <li> Line number in a Synopsis: <tt>[aes://s06/52]</tt> ⇒ [aes://s06/52] </li> <li> Section in a Synopsis: <tt>[aes://s06/Named arguments]</tt> ⇒ [aes://s06/Named arguments] &#x2010 the section title is case sensitive, the letter <tt>s</tt> is not. </li> <li> [aes://|Index] of all Synopses, Apocalypses and Exegeses: <tt>[aes://]</tt> (no args) </li> </dd> <dt><a name="man">[man://|UNIX/Linux man pages]:</a> </dt><dd> <li>Search form: <tt>[man://]</tt> (no args) </li> <li>A specific function: <tt>[man://funcname]</tt> </li> Currently, you can link to either SuSE Linux versions of the man pages (the default) or to FreeBSD versions. — To link to FreeBSD instead of SuSE Linux: <tt>[man://funcname;freebsd]</tt> You can also specify the exact version you want, if you want something other than the default (which should be the latest and greatest): — To link to SuSE Linux v. 7.2 man pages : <tt>[man://funcname;suse 7.2]</tt> — To link to FreeBSD UNIX v. 7.2 man pages : <tt>[man://funcname;freebsd 7.2]</tt> If the page you want is ambiguous by the name, you can specify which section of the man you want: — To link to <tt>time(3)</tt> rather than <tt>time(1)</tt> : <tt>[man://time;3]</tt> — To link to <tt>time(3)</tt> rather than <tt>time(1)</tt>, FreeBSD specific : <tt>[man://time;3;freebsd]</tt> </dd> <dt><a name="ddg">[ddg://|DuckDuckGo] web searches:</a></dt><dd> <li> <tt>[ddg://search terms]</tt> (Note that <c>duckduckgo://</c> is an alias for <c>ddg://</c>, for those who like to type more.)</li> <li>The [ddg://|DDG search form]: <tt>[ddg://]</tt> (no args) </li> </dd> <dt><a name="google">[google://|Google] web searches:</a></dt><dd> <li>Full search results: <tt>[google://search terms]</tt> </li> <li>Link directly to first matching site: <tt>[lucky://search terms]</tt> </li> <li>The [google://|Google search form]: <tt>[google://]</tt> (no args) </li> See [http://www.google.com/intl/en/help/basics.html|Google Search Help] for tips. </dd> <dt><a name="dict">The Dictionary:</a></dt><dd> Currently we use [http://www.dict.org/|Dict.org], which searches a large number of on-line dictionaries and lexicons. <li> Look up a word: <tt>[dict://word]</tt> </li> <li> The [dict://|Dict.org search form]: <tt>[dict://]</tt> (no args) </li> </dd> <dt><a name="jargon">[http://www.catb.org/~esr/jargon/html/|Jargon File] Entries:</a></dt><dd> <li> Look up a term: <tt>[jargon://search terms]</tt> Currently this simply goes to [http://www.dict.org/|Dict.org], constraining the search to the Jargon File database. </li> <li> The [jargon://|Jargon File table of contents]: <tt>[jargon://]</tt> (no args) </li> </dd> <dt><a name="acronym">Acronym definitions:</a></dt><dd> <li> Search: <tt>[acronym://TIMTOWTDI]</tt> ⇒ [acronym://TIMTOWTDI] Keep in mind, almost any acronym has many possible expansions. </li> <li> The [acronym://|search form]: <tt>[acronym://]</tt> (no args) </li> </dd> <dt><a name="ud">[ud://|Urban Dictionary] entries:</a></dt> <dd> <li> Look up a slang term: <tt>[ud://hurrication]</tt> ⇒ [ud://hurrication] </li> <li> [ud://|Urban dictionary main page]: <tt>[ud://]</tt> (no args) </li> </dd> <dt><a name="wikipedia">A [http://www.wikipedia.com/|Wikipedia] entry or search:</a></dt><dd> <li> Search: <tt>[wp://terms]</tt> This invokes Wikipedia's search function, which is smart (like PerlMonks' Search box) in that it leads directly to the matching article if there's only one. (Note that <c>wikipedia://</c> is an alias for <c>wp://</c>, for those who like to type more.) </li> <li> The [wp://|Wikipedia main page]: <tt>[wp://]</tt> (no args) </li> </dd> <dt><a name="wiktionary">A [http://www.wiktionary.org/|Wiktionary] entry or search:</a></dt><dd> <li> Search: <tt>[wikt://word]</tt> </li> <li> The [wikt://|Wiktionary main page]: <tt>[wikt://]</tt> (no args) </li> </dd> <dt><a name="wikibooks">A [http://www.wikibooks.org/|Wikibooks] entry or search:</a></dt><dd> <li> Search: <tt>[wb://title terms]</tt> </li> <li> The [wb://|Wikibooks main page]: <tt>[wb://]</tt> (no args) </li> </dd> <dt><a name="wikiquote">A [http://www.wikiquote.org/|Wikiquote] entry or search:</a></dt><dd> <li> Search: <tt>[wq://title terms]</tt> </li> <li> The [wq://|Wikiquote main page]: <tt>[wq://]</tt> (no args) </li> </dd> <dt><a name="wikisource">A [http://www.wikisource.org/|Wikisource] entry or search:</a></dt><dd> <li> Search: <tt>[ws://title terms]</tt> </li> <li> The [ws://|Wikisource main page]: <tt>[ws://]</tt> (no args) </li> </dd> <dt><a name="c2">A page on the [http://www.c2.com/cgi/wiki?WikiWikiWeb|WikiWikiWeb] (aka The Wiki): </a></dt><dd> <tt>[c2://wiki words]</tt> The behavior of this shortcut depends on how many words are provided as "arguments". This is because Wiki page names must consist of at least two words. If two or more words are provided, then a wiki page title is constructed from them, and the shortcut links directly to that page. (It's up to you, the writer, to ensure it links to an existing page.) If only one word is given, then a Wiki title search is performed. This behavior reflects the capabilities provided by the Wiki site itself, which has extremely limited search capabilities. Note that you can be somewhat lax with spaces and capitalization. Any capitals provided will be respected; and otherwise, all "words" will be initial-capped. Note that because Wiki words can only consist of word characters (<c>\w</c>), all other characters will be treated as "space". Example: to refer to [http://www.c2.com/cgi/wiki?HigherOrderFunction|HigherOrderFunction], you can write <c> [c2://HigherOrderFunction]</c> <c> [c2://higher order function]</c> <c> [c2://Higher orderFunction]</c> <c> [c2://higher-order-function]</c> etc. To search Wiki page titles for a single term: <tt>[c2://term]</tt>, e.g. <tt>[c2://perl]</tt> ⇒ [c2://perl] To go to the Wiki's [c2://Front Page]: <tt>[c2://]</tt> (no args) </dd> <dt><a name="imdb">Info on [http://www.imdb.com/|IMDB], such as movies and actors:</a></dt><dd> <li> Search: <tt>[imdb://terms]</tt>, e.g. <tt>[imdb://Office Space]</tt> ⇒ [imdb://Office Space] </li> <li> The [imdb://|IMDB main page]: <tt>[imdb://]</tt> (no args) </li> </dd> <dt><a name="isbn">Books by [acronym://ISBN]:</a></dt><dd> <li> Look up by ISBN: <tt>[isbn://ISBN]</tt>, e.g. <tt>[isbn://0596000278]</tt> ⇒ [isbn://0596000278] For best results, we recommend verifying the ISBN using [http://www.BarnesAndNoble.com/|Barnes And Noble]'s search facility, since ISBNs change with each new edition. </li> <li> The [isbn://|ISBN search form]: <tt>[isbn://]</tt> (no args) </li> </dd> <dt><a name="lj">[http://www.livejournal.com/|LiveJournal]:</a></dt><dd> <li> Link to a LJ user: <tt>[lj://username]</tt>, e.g. <tt>[lj://theorb|theorbtwo]</tt> ⇒ [lj://theorb|theorbtwo] </li> <li> The [lj://|LiveJournal main page]: <tt>[lj://]</tt> (no args) </li> </dd> <dt><a name="e2">An [http://www.everything2.org/|Everything2] node:</a></dt><dd> <li> By title: <tt>[e2://perl]</tt> ⇒ [e2://perl] </li> <li> By ID: <tt>[e2://13372]</tt> ⇒ [e2://13372] </li> <li> The [e2://|Everything main page]: <tt>[e2://]</tt> (no args) </li> </dd> <dt><a name="mathworld">A page on [mathworld://|Mathworld]:</a></dt> <dd> <li> Search by title: <tt>[mathworld://unique factorization domain]</tt> ⇒ [mathworld://unique factorization domain] </li> <li> [mathworld://|Mathworld main page]: <tt>[mathworld://]</tt> (no args) </dd> <dt><a name="xkcd">Xkcd comic strips:</a></dt><dd> <li> By number: <tt>[xkcd://208]</tt> ⇒ [xkcd://208]</li> <li> Search strip using google, finding the most relevant: <tt>[xkcd://Bobby Tables]</tt> ⇒ [xkcd://Bobby Tables] <li> Latest strip (at the time the link is actually followed): <tt>[xkcd://]</tt> (no args) ⇒ [xkcd://] </li> </dd> <dt><a name="rfc">Internet RFCs:</a></dt><dd> <li> Search: <tt>[rfc://822|rfc-822]</tt> ⇒ [rfc://822|rfc-822] </li> <li> The [rfc://|main page]: <tt>[rfc://]</tt> (no args) </li> </dd> <dt><a name="web">Arbitrary external sites:</a></dt><dd> You can use <tt>http://</tt>, <tt>https://</tt>, and <tt>ftp://</tt>. With no arguments, <tt>[http://]</tt>, <tt>[https://]</tt>, and <tt>[ftp://]</tt> link to this usage documenation. </dd> <dt><a name="general">General-Purpose Linking</a></dt><dd> For situations where none of the above shortcuts can do what you need, and you think your only recourse is the explicit html <tt><a href="...">...</a></tt>, there is one more shortcut you can try: <tt>[href://...]</tt> You can use it to link to a named anchor within a document: <li> <c>[href://#notes|notes]</c> ⇒ [href://#notes|notes] in the current node </li> <li> <c>[href://?node_id=786921#titles|page titles]</c> ⇒ [href://?node_id=786921#titles|page titles] in another node. </li> You can use it to link to a node with additional CGI parameters: <li> <c>[href://?node_id=43037;displaytype=xml|this node xml]</c> ⇒ [href://?node_id=43037;displaytype=xml|this node xml] </li>  <tt>[href://]</tt> by itself (no args) links to this usage documentation. <tt>link</tt> is an alias for <tt>href</tt>. See [id://347710]. </dd> <dt><a name="localtime">Show the time!</a></dt><dd> One special shortcut type doesn't make links. The <c>[localtime://]</c> shortcut is really a "macro" which PerlMonks replaces with a formatted time, localized for the user. Each user will see the time you type in their timezone, as set in their [Timezone Settings]. This is similar to how most times (like posting times) are shown on the site. <li> The shortcut needs as argument a time in ISO 8601 order, that is, the first four digits are year, then two digits for months, two digits for days, two digits for hours, two digits for minutes, two digits for seconds (optional). Punctutation or separators like <c>T</c> are ignored. Usually you want to use a <c>UTC</c> suffix so the date is interpretted as UTC (Coordinated Universal Time, GMT); otherwise it's interpretted as server time which is not too useful. Other timezone designators or fancy formats like day of year or week of year are not allowed. For example <c>[localtime://20081201144400UTC]</c> means 1st December 2001, 14:44 UTC, which renders as [localtime://20081201144400UTC]; whereas <c>[localtime://20081201144400]</c> means 14:44 server time, and renders as [localtime://20081201144400].</li> <li> In the [Chatterbox], the time displayed for a <c>[localtime://]</c> without argument is fixed at the point in time when the user submitted the public message. </li> <li> In a node, the time for <c>[localtime://]</c> without argument is updated to the current time each time the node is rendered. </li> </dd> <dt><a name="abbr">Hover Text ("Abbreviations")</a></dt><dd> The <c>[abbr://]</c> shortcut lets you create <c><abbr title="balloon">text</abbr></c> easily, by writing <c>[abbr://balloon|text]</c>. (<c>[abbr://]</c> used to be an alias for <c>[acronym://]</c>.) </dd> </dl> <hr/> <a name="tips"></a> <h3><a name="usage">Using Shortcuts</a></h3> Please test your links before posting them. <blockquote>Rule #1: If you're writing a node, use the Preview button!</blockquote> There are several ways to try out a link before using it in a post or in the [id://17989|Chatterbox]: <ol> <li> [/msg] yourself </li> <li> Enter the full link (with or without the square brackets) in the Search box at the top of the page. This "executes" the link immediately, taking you to wherever the link would go if you were use it in a post or message. Note that this is only useful to test the target of a link, not the title or clickability. </li> </ol> Please avoid using the [id://17989|public chatterbox] to test links. It is very annoying to your fellow users. <h3><a name="relative_only"></a>All Links Within PerlMonks Should Be Relative</h3> Be sure to use a relative URL when linking to any location on the perlmonks web site. That is, do not include the <tt>http://www.perlmonks.org</tt> part!  If you include <tt>http://www.perlmonks.org</tt>, it creates a "logout link". This means that people who follow (click on) the link — including you! — might find themselves looking at your intended target node as a non-logged-in user (i.e. [Anonymous Monk]). This is A Bad Thing. Therefore, constructing a link like <c><a href="http://www.perlmonks.com/index.pl?node_id=43037">shortcuts</a></c> is not as good as <c>[http://www.perlmonks.com/index.pl?node_id=43037|shortcuts]</c> which is not as good as <c><a href="/index.pl?node_id=43037">shortcuts</a></c>. Best of all is to use <c>[id://43037|shortcuts]</c>. <h3><a name="titles"></a>Specifying Link Titles</h3> To specify the text to be displayed as the clickable part of your link (its "title"), enter the text after the "url", separated from it by a | (vertical bar, aka pipe) character within the <tt>[]</tt> (square bracket) delimiters. For example, <c>[http://www.perl.com|Perl.com]</c> is displayed as [http://www.perl.com|Perl.com]. In most cases, if you do not specify a title, your link's "target" (the part after the <tt>://</tt>) will be used as the link text. E.g., <c>[perldoc://perlfaq]</c> ⇒ [perldoc://perlfaq]. Exceptions include: <ul> <li> <c>[http://]</c> and kin use the entire URL. <c>[http://www.perl.org/]</c> ⇒ [http://www.perl.org/] </li> <li> <c>[isbn://]</c> prepends "ISBN". <c>[isbn://0596000278]</c> ⇒ [isbn://0596000278] </li> <li> <c>[id://]</c> uses the target node's title. <c>[id://483072]</c> ⇒ [id://483072] </li> <li> <c>[pad://]</c> makes a default title based on whose pad is being linked to. The <c>[pad://vroom]</c> ⇒ [pad://vroom]; the default title for <c>[pad://]</c> is <tt>my pad</tt>. </li> <li> <c>[localtime://]</c> always renders as a time string (not a clickable link), irrespective of any title text given. <c>[localtime://|When?]</c> ⇒ [localtime://|When?] </li> </ul> Most shortcut types provide useful default titles when no target arguments are specified. A full list of examples is available in the [id://567724|test cases for parameterless shortcuts]. See the second column. <hr/> <h3><a name="notes"></a>Notes:</h3> 1 - This is the same as entering your search terms into the Search box at the top of most nodes. Node titles aren't required to be unique on PerlMonks, so there's always a possibility for ambiguity when linking/searching by title. It's possible to disambiguate by node type (though this only helps if the conflicting nodes are of different types). To do so, use the <tt><a href="#general">href://</a></tt> style and add <tt>;type=type</tt> to the shortcut. Example: <c>[href://?node=message;type=dbtable|message (dbtable)]</c> ⇒ [href://?node=message;type=dbtable|message (dbtable)]. 2 - You can also use <tt>[kobe://XML::Parser]</tt> (no "s"). This is provided for backward compatibility only. It will always be supported, but the <tt>kobes</tt> form is considered "correct" and is recommended for all new links. <hr/>Back to the [PerlMonks FAQ]