tye 


Think about Loose Coupling
	PerlMonks

tye 

by tye  (Monk)

on Feb 01, 2002 at 20:03 UTC ( #142755=user: print w/replies, xml )

Need Help??

User since:	Feb 01, 2002 at 20:03 UTC (22 years ago)
Last here:	Jan 01, 2018 at 01:00 UTC (6 years ago)
Experience:	413
Level:	Monk (7)
Writeups:	none
Location:	n/a
User's localtime:	Dec 10, 2023 at 12:48 PST
Scratchpad:	View
Member of:	gods
For this user:	Search nodes

Only used for testing. See tye.

The following is not implemented.

[ This is where I've been testing things. I haven't had a chance to work on it in a while and ar0n's disappeared again. ]

Several shortcuts are available for linking to other documents. To link to:

Outside Sites:

Use [http://perl.com/] or with https:// or ftp:// (perl.com/ or ftp.perl.org/pub/CPAN/)
You can also use standard <a href=....> HTML tags.¹

Nodes:

By Title: [NODE_TITLE] (Code Catacombs)
By Title: [title://NODE_TITLE] (Newest Nodes)
By Node ID: [id://NODE_ID] ² (17316)
By Monk Name: [user://MONK_NAME] (grep)
A Monk's Scratch Pad: [pad://MONK_NAME] (MySQL on FreeBSD)
Simple Search results: [SEARCH TERMS]³ (grep or code review section)
Advanced PM links: [pm://PATH] (images/monk1sm.gif or ?op=message;message=/me read &lsb;id://43037&rsb;)

CPAN Modules:

Module searches at cpan.org: [cpan://XML::Parser] (XML::Parser)
Module searches on an alternate server: [kobes://XML::Parser]⁴ (XML::Parser)

Searches of the latest Perl documentation: [perldoc://SEARCH TERMS] (grep)
Google web searches:

Full search results: [google://SEARCH TERMS] (HTML quick reference)
Link directly to first matching site: [lucky://SEARCH TERMS] (HTML quick reference)

Books by ISBN number: [isbn://1565922840] ⁵ (1565922840)
Jargon File entries: [jargon://SEARCH TERMS] (foo)
English dictionary entries: [dict://TERM] (pedant or omphaloskepsis)
everything2.com/ searches: [e2://SEARCH TERMS] (bovine)
Internet Movie Database searches: [imdb://SEARCH TERMS] (rustlers' rhapsody)

For best results, be sure to test your links before posting them. Use Preview for links in nodes or /msg yourself for links to be posted in the Chatterbox.

Specifying Link Des‎crip‎tion

To specify the text shown for your link, enter the text (actually HTML) after a | (pipe) character in your []'s. For example, [http://perlmonks.org/|The <em>Perl</em> Monastery] is displayed as The Perl Monastery.

If you do not specify a des‎crip‎tion, your link's criteria is used. For example, [perldoc://perlfaq] is rendered as perlfaq and [http://www.perl.com/] as www.perl.com. Some link types (http://, https://, ftp://, and isbn://) include the link type in the default des‎crip‎tion. Exceptions include:

The [id://] tag display the node's title if you do not provide a des‎crip‎tion. For example, [id://42269] is displayed as 42269.
The [pad://] tag constructs a des‎crip‎tion if you do not provide one. For example: [pad://vroom] returns vroom.

Footnotes:

¹ - While you can use <a href=...> tags to link to pages within the Monastery, it's best to use different approaches for internal links. If you must use an <a href=...> tag, then be sure to use relative URL's (e.g. do not include the "http://www.permonks.(org|com)/index.pl". Otherwise, your link may appear to log people out. Instead start the URL simply with a question mark: <a href="?node_id=...">.

² - You can locate the ID of many nodes by opening them from Search results, Super Search results, Newest Nodes, or even the author's User Search results. Check the node's URL. If you see a node_id parameter, that's the value you need. If you don't see that parameter, search for the node and then open it. (It may help to include a nonsense word in your search, e.g. "plugh")

³ - This is the same as entering your search terms into the Search box at the top of most nodes.

⁴ - You can also use [kobe://XML::Parser] (no "s"). This was the original method and there are no plans to stop supporting it.

⁵ - For best results, verify the ISBN number using FatBrain's search facility, as ISBN number change in new editions. And, yes, the Monastery receives a small kickback if the book is purchased from the link. (If you like, you can provide kickbacks to the Monastery for books ordered from your own web pages).

Advanced options

These link shortcuts come in two forms: [TITLE|DESC] and [WORD://DATA;PARAMS|DESC]. Some special rules and processing apply to each part of a shortcut.

You can not have a literal [ nor ] in any of the parts.
|DESC and ;PARAMS are optional.
TITLE is interpretted as text except it cannot contain [, ], nor | and must not match m[^\w+://]. To link to a node that contains [, ], or | in the title, use [title://...] or [id://...].
DESC is interpretted as HTML except that &lsb; and &rsb; become [ and ] (respectively).
WORD must be one of the supported link types or else the entire [WORD://...] construct is simply displayed as a literal string. Upper- vs. lower-case is ignored in WORD.
DATA is a string that is processed to produce a URL based on WORD. There are several character sequences that you can use in DATA to represent metacharacters (see below).
PARAMS adds characters on the end of the URL generated from WORD://DATA.
[pm://...] is unusual in that it takes no DATA so you can do [pm://images/usermonkpics/ovidmonk.gif] or [pm://?op=message;...].

In DATA;PARAMS, the following special sequences are processed:

String	Result
;	In DATA, it ends DATA and starts PARAMS. In PARAMS, separates parameters.
& `m[&amp\b;?]i`	In DATA, it ends DATA and starts PARAMS. In PARAMS, separates parameters.
?	In DATA, it ends DATA and starts PARAMS (and is changed to ; if needed). In PARAMS, adds "?" to the string.
/	In DATA, it ends DATA and starts PARAMS. In PARAMS, adds "/" to the string.
#	Indicates that an anchor name is next which tells where in the linked-to page to jump to.
\|	Ends DATA and PARAMS, starts DESC.
=	In DATA, adds "=" to DATA (same as \= would). In PARAM, separates param name from value.
%XX `m[%([\da-f]{2})]i`	Adds `pack("C",hex($1))` to the string.
\\ \; \& \? \/ \# \\| \= \%	Adds the second (escaped) character to the string.
\* `m[\\(\W)]`	Adds `"\\$1"` to the string.
\A `m[\\(\w)]`	Adds `$1` to the string.
%	Is treated like \% if it isn't follow by two valid hex characters (it adds a "%" to the string).
< `m[&lt\b;?]i`	Adds '<' to the string.
> `m[&gt\b;?]i`	Adds '>' to the string.
" `m[&quot\b;?]i`	Adds '"' to the string.
&lsb; `m[&lsb\b;?]i`	Adds '[' to the string.
&rsb; `m[&rsb\b;?]i`	Adds ']' to the string.
[ `m[&#(\d+);?]`	Adds pack("C",$1) to the string.
&	Is treated like `&` if it doesn't start one of the above HTML escapes (ends DATA or separates parameters).

Examples

Here are some examples showing how the above (rather complex) rules are designed to be do-what-I-mean when constructing links:

[user://turnstep#Cplusplus|Chatterbox FAQ++] becomes Chatterbox FAQ++. Note how it jump down to the <a name="Cplusplus">Chatterbox FAQ++</a> point of turnstep's home node.
Note that [turnstep#Cplusplus] doesn't start with WORD:// and so # is not recognized as being special and so this tries to search for nodes having "turnstep#Cplusplus" in their title and so probably finds nothing: turnstep#Cplusplus.
[title://turnstep#Cplusplus] (probably) also works since we don't (shouldn't) have any nodes titled "turnstep" except for the user: turnstep#Cplusplus.
If you want to find a node with # in the title, you can use [Using # inside qw()] (Using # inside of qw()) or [title://Using \# inside qw()] (Using \# inside qw()). Note how the # has to be escaped as \# when using WORD:// links.
This is useful if you want to specify extra options in the link. For example [title://Using \# inside qw();displaytype=xml] (Using \# inside qw();displaytype=xml) will give you the XML version of that node.
Even better would be to not rely on the title of the node never changing and link to it via the node ID instead: [id://94698;displaytype=xml] (94698;displaytype=xml).
Similarly, you can't use [P(erl|ython)] to link to the node with that titles since it becomes ython) and there is no way to escape | if you aren't using the WORD:// type of link.
To link to that node use [title://P(erl\|ython)] (P(erl\|ython)), [title://P(erl\|ython)|cool obfu] (cool obfu), or [id://31015] (31015), etc.