text:
7 Common Survival Tactics ( that Will Get You Killed)
Most of us like to think we'd make it through many life-threatening situations just fine. After all, you've seen the Discovery channel, you've watched disaster movies and you've got a good logical head on our shoulders. You should be just fine, right?
But that's like thinking you'll be good in a fight because you've watched a Jackie Chan movie; whatever "techniques" you think you've learned are more likely to get your dumb ass killed.
#7. In Case of Shark, Punch in Nose
For whatever reason–plane crash, riptide, sailing misadventure, a bad case of Ocean Fury–you find yourself in the middle of the sea with nothing but miles of water around you. And, to your horror, here comes that heavy string music and a circling fin slicing through the water.
Luckily, from multiple websites and news stories about shark survival you remember the Shark's Achilles Heel: Punches to the face. Specifically, the tender nose area. You wind up to belt that fishy bastard in the schnoz, and make your testicles proud.
The Result:
First let's look at a shark. Can you find his nose? Yep, it's that incredibly narrow point in front that drops precipitously into a slimy, downward sloping ramp right into his 5,000,000-toothed mouth.
Take into account the fact that you're bobbing around in the water like a buoy full of meat, facing off against a lightning-quick predator with several million years of practice in eating things that punch it in the nose, and you'll see that chances are your fist will just deflect down into that aforementioned gaping hole of teeth like Boba Fett into a Sarlacc Pit. Now if your plan to defeat the shark is too feed yourself to him until he grows tired of the taste of you, you're off to a great start.
But experts say that even if you hit the shark-nose punching lottery, you won't have scared him off, just dazed him, giving you a minute or so tops. Now, if this particular shark is suffering from ADD, then great: You're in the clear now. He's off to chase a shiny thing or update his twitter feed 82 times an hour. But if not, all you've done is managed to piss the shark off and give him a minute to ponder how revenge is a dish best served in a blood-filled bag resembling you.
#6. In Case of Earthquake, Get in the Doorway
It's 3 O'clock in the morning, and you're sleeping off a bender that would wound the pride of Bukowski. Suddenly you wake with a start when the house begins to rumble. Your pants feel moist and warm with urine, (though you can't remember if you peed yourself before or after the earthquake began). No time to ponder urine-based philosophical questions, man, you need to survive! You scramble for the nearest doorway, congratulating yourself both on your level-headedness in a stressful situation as well as the foresight to pass out so close to a doorway.
Other people aren't so lucky
The Result:
It's true; doorways can be lifesavers in an earthquake… if you own a 150-year-old adobe home. You don't? You live in a late-model cookie cutter bungalow? Too bad, had you possessed more discerning taste you wouldn't be sucking on hellfire now, Sparky. Because of the particular construction style on old adobe homes, the doorways are substantially stronger. This fact became apparent when locals noticed that the only thing left standing in the rubble of these buildings after an earthquake was the doorways. In any other home you may as well stand beneath an anvil with a coyote cutting the rope. Most doorways are just as weak – if not more so – than any other point in the house.
Except for this safest doorway ever. Which has no bothersome home attached.
So, what should you do? Diving under a table is your best bet. Of course, that's again assuming a strong, well-built table. If you live in the modern age you probably bought your table at IKEA, which means it's still sitting in an unassembled pile in the closet because they gave you the wrong Urgnblott and they can't order any replacements because there was a strike back in Trrnlbord at the Fyjrnwuld plant where they make them. You make a silent pledge to donate some god damn vowels to the Swedes, right before you kick their balls to death. You are then crushed while contemplating Swedish balls. It is not a good way to go.
#5. In Case of Lightning, Lie Down Flat on the Ground
It's a beautiful and serene day in the Pacific Northwest, which of course means it's pissing down freezing-cold rain, the kind with those fat droplets that hit you like a personal insult. And oh, did you hear that? Thunder. Awesome. Seeing no immediate shelter, you lay down as flat as you can, knowing that this makes you less likely a target for the lightning. You close your eyes, and think of California.
This guy had the right idea. We were the fools all along.
The Result:
Despite the sound of it, when lightning strikes the ground it isn't actually "grounded" (you win again, words!); rather, lightning that strikes the Earth radiates in circles from the point of impact. By lying down, you offer these lightning ripples the maximum amount of contact with your body, which leads to burned internal organs, and cardiac arrest.
What you should do is run for lower ground like your ass is on fire (which it may soon be) and then scrunch into a tiny ball with just your feet touching the ground. The running improves your chances, because lightning has trouble hitting a moving target (even that bitch Mother Nature has to aim), while the scrunching minimizes your size as a target and offers the least body to ground contact. It also allows for maximum ease of transition to fetal position crying if you do make it out alive.
#4. In Case of Snake Bite, Suck out Poison
Ahh, nature! The earthy vistas, the painterly landscapes, the chirping of the birds, the snakes biting your groin – oh. That last one is not so good. That looks to be a pretty vicious snake bite, in fact. Not willing to die stupidly like an animal in the forest (you prefer to do your dying smartly and in the city, like Oscar Wilde) you point to the wound in your intimate place and ask your friend politely to "suck it out." You somehow manage to refrain from appending the words "hard" or "whore" to that statement, so your friend obliges.
The Result:
If your hiking buddy happens to have any kind of open sore in or around his mouth, he too will get a nice dose of poison and the two of you can then die together, just like a frightened, gay, boot-wearing Romeo and Juliet! If your friend doesn't have a bunch of open sores (and really, you probably shouldn't be running around the woods with people who have frequent open mouth sores) and if he doesn't accidentally swallow some venom, he might take a little poison away from you but he'll be giving back a lot more in the form of bacteria. The inside of your mouth is hands down the dirtiest part of your body. Especially yours, pervert.
To side step all this unpleasantness you could instead: Keep calm (a speeding heart rate speeds the venom through your body); use a suction device if one is handy (what you and your buddy are doing in the forest with an unexplained "suction device" is between you two); see if the wound discolors and/or swells-that's your sign the snake is venomous; get medical help and take the snake with you. The genus of snake informs doctors which anti-venom to use. Don't risk your life to capture the snake, though; a snake can still bite an hour after its death.
Damn, snakes are assholes.
Team DIYSL.
DIY Survival Life


text:
Guitar Tabs Player
.. with Fretboard, Piano and Drums display
- Music score player with fretboard, piano and drumset views Plays: Guitar-pro, MIDI ASCII and MusicXML
- Share Guitar-pro or MIDI (MIDI to gp5 converter)
Online MIDI to Guitar Tabs Online Converter (Before uploading check if the MIDI has guitar tracks)
- Auto play and bookmarks
- [NEW!]Multiple tracks rendering, Check mixer/tracks pane [NEW!]
- View Score/Tabs, Slow/Fast, Loop, Repeat
- Local Sounds from sf2 files
- Change tunning / Change pitch (gpx), Print
- ghitara.com has 193107 scores and tabs
- tabs played today
- Online users: 1
- There were hundreds of hours of development making this site: Patreon me OR

subset: commoncrawl


text: by David Crane [email protected] Back in October, DefenseReview reported on the Cavalry Arms CAV-15 MKVII polymer lower receiver for AR-15/M16 rifles. Well, Calvalry Arms Corporation also makes AR15 buttstock adapter systems/M1913 Picatinny rail optics mounting platforms for the Remington 870 shotgun (pump-action) and Mossberg 590 shotgun (pump-action) that allow the operator to attach an AR-15/M16/M4/M4A1/CAR-15 telescoping/retractable stock. The adapter system …Read More »


text:
CHRIS TOMLINSON, Associated Press
AUSTIN, Texas (AP) — Early voting is underway on whether to tap the state's rainy day fund to create a $2 billion water infrastructure fund, but while the constitutional amendment enjoys widespread support, there is vocal conservative opposition that could derail it in a low-turnout election.
Listed on the ballot as Proposition 6, the measure would allow the state to use the money to buy down the cost of bond financing for massive water development projects. The Texas Water Development Board says the state's share of developing new water resources over the next 50 years is $27 billion and Proposition 6 will supply the seed money to meet that need. Local authorities would borrow from the fund and repay it with interest, allowing the fund to be used repeatedly to lower borrowing costs.
Gov. Rick Perry, House Speaker Joe Straus, and dozens of business and environmental groups support creating the State Water Infrastructure Fund. The current drought spurred the Legislature into action after decades of failing to adequately fund water projects needed to keep up with population and business growth.
"The water crisis impacts every part of our great state, from our growing cities and industries to our farming and ranching communities," Straus said. "By casting a yes vote today for Proposition 6, Texans can help address this crisis and ensure our state has an adequate supply of water for the next 50 years."
Yet one of the most vocal conservative groups in the state — Empower Texans — oppose the measure because they feel it would "incentivize new local-government debt without providing sufficient protections." Fiscal conservatives have raised concerns about local governments piling up large amounts of bond debt and this could add to that.
Longview Rep. David Simpson, a top tea party leader in the Legislature, is urging voters to oppose Proposition 6 because he believes the money will be used to distort the bond market.
"Intervention in the market by the state will no doubt favor some at the expense of others, such as East Texans," he said in a statement. "Because East Texas is blessed with more water resources than other parts of the state, it is likely those resources will be sought after by others and this proposal jeopardizes the ability for East Texas to protect its resources."
Conservative opposition to tapping the rainy day fund led lawmakers to give voters the choice of whether to withdraw the cash. The Republican-controlled Legislature ignored Democrats and less conservative Republicans who thought the Legislature should have used its authority to spend the money rather than rely on a referendum.
The main concern is the low turnout for constitutional amendment elections. Without candidates campaigning, most people don't even know there is a vote on Nov. 5. Houston is the one exception, because of the mayoral race and a referendum to turn the Astrodome into a convention center.
In 2011, only 695,052 people cast ballots out of 12.8 million registered voters. That means a small number of activists on one side of an issue can make the difference.
Out of 10 propositions on the 2011 ballot, three failed to pass and all had fiscal implications. Statewide voters denied El Paso County permission to issue bonds for parks and recreation facilities, rejected allowing counties to issue bonds for redevelopment of blighted areas and refused to allow land set aside for water conservation to be taxed at a rate lower than the market value.
That last item dealt a serious blow to water conservation efforts and is one reason both supporters and opponents of Proposition 6 want to turnout voters. Only about 100,000 people, though, had cast early ballots at the end of last week.
If Proposition 6 fails to pass, it will put lawmakers in a difficult position during the 2015 legislative session, forced to decide whether to spend the money themselves or wait for a water crisis to develop that will give them the political cover to spend state revenues.


text:
Brian Clement, Ph.D. - Food Is Medicine: The Scientific Evidence - Offstage Interview - 2019
The Real Truth About Health
Did you know that what you eat could be making you sick? It's true. Some foods such as poultry, beef, and dairy clog your body with energy-depleting fats, toxins, and chemicals. Where can you find the optimum nourishment your body needs to stay strong, healthy, and vigorous? For millions of people, the answer is in the health and healing properties of living foods—foods that are eaten raw and produced without dangerous, nutrient-robbing chemicals or additives.
For more than forty years, Brian Clement has been teaching people how to cleanse and heal their bodies with naturally potent living foods. Brian explains why living foods are vital to good health.
Connect with The Real Truth About Health
Passionate believers in whole food plant based diets, no chemicals, minimal pharmaceutical drugs, no GMO's. Fighting to stop climate change and extinction.


text:
Salafists in GermanyHeading for ''Urban Terrorism''?
Until recently, German public perception of the Salafist movement was of a phenomenon primarily taking place abroad. The fundamentalists with the long beards and cropped trousers captured some 20 per cent of the Egyptian vote. Now they aim to impose Sharia law on the nation and induce society to live by the example of the Prophet and his disciples.
They also made negative press in Tunisia, with verbal attacks on Jews and anyone challenging their rigid world view. But in Germany? For sure, police and intelligence agencies have long had the German Salafists on their radar, and they warn of the potential dangers posed by this ideology. Members of what was known as the "Sauerland cell", who planned attacks on US installations in 2007 and were sentenced to serve long jail terms, came from this milieu.
Radicalisation of the Salafist scene
The general public only became aware of the Salafists in recent weeks, beginning with news of the apparently harmless distribution of copies of the Koran, through to violent clashes at demonstrations against the showing of cartoons depicting Mohammed. But how dangerous are the Salafists really? And what makes them so attractive in a society that views individual self-realization as a valuable asset?
Following a range of interviews with Islam specialists working within the police force and intelligence service, all of whom wanted to remain anonymous in view of the sensitive nature of the issue, it is evident that a radicalization has taken place in the Salafist scene in recent months. One intelligence service official even expressed the fear that this could downslide into what he described as "urban terrorism".
On the other hand, it is not the case that all Salafists are ready to take up violence. In the view of one Islam expert in the police force, it would be fatal to tar the entire scene with the same brush, as this would also force peaceful Salafists into a corner and incite them to side with the militants.
The key figure of Pierre Vogel
The best-known face among German Salafists is the convert Pierre Vogel, who until last autumn toured the nation canvassing for the one and only true faith in his seminars on Islam. Some media described the former boxer, who speaks fluent Arabic with a Cologne-region accent, as a "hate preacher".
But that's only accurate to a certain extent. After all, Pierre Vogel is among those preachers who conduct themselves within the confines of the law and warn their followers against the use of violence. He is no jihadist. This sets him apart from other preachers who have consolidated their influence in recent months and who expressly advocated the attacks on police in Solingen and Bonn.
The dividing line between peaceful and potentially violent Salafists is however hazy; many of those seeking to inject new meaning into their lives and who initially attended Pierre Vogel's seminars later came to the attention of security authorities for openly declaring their allegiance to the jihad. The Salafist world view, one shared by Pierre Vogel, makes a stringent distinction between good and evil, between the faithful destined for paradise and the infidels destined for eternal hell fire – a fact that evidently facilitates the downslide into extremism.
A former associate of Pierre Vogel, Ibrahim Abou Nagie from Cologne, is of a different stamp. While not expressly viewed by security experts as a jihadist, he evidently advocates violence against "infidels". The two preachers went separate ways several years ago.
While Pierre Vogel is concerned with mobilizing the masses and wants to avoid affronting non-Muslims, Ibrahim Abou Nagie makes no verbal compromises. He calls non-Muslims "kuffar" – infidels – and makes no secret of his contempt for them. "Pierre Vogel fills the venues, while Ibrahim Abou Nagie occasionally pulls in the reins," is the view held by one Islam specialist advising the police. He talks about a kind of "division of labour" between the two, even though they are clearly no longer in contact with one another. In any case, Pierre Vogel is currently pursuing his studies in Egypt.
An unequivocal jihadist is however the Austrian Abu Usama al-Gharib, previously an Al Qaeda representative of sorts in his home country, which sentenced him to four years in prison because of his associations with the terrorist network. Following his release in September 2011, he initially moved to Berlin, then to Solingen, where he preached for several months at the Millatu Ibrahim Mosque. He later moved to Hessen, from where he was expelled in late April. He now lives in Egypt.
Solingen – centre of Salafist Jihadism
Unlike Pierre Vogel and Ibrahim Abou Nagie, al-Gharib and his associates openly declare their allegiance to the jihad. Security experts are now saying that Solingen has become a centre of Salafist Jihadism in Germany. "Abu Usama al-Gharib has succeeded in uniting the radical Salafists," says one Islam specialist at Germany's intelligence agency.
It had been Ibrahim Abou Nagie's idea to distribute more than 20 million editions of the Koran in German cities. What initially sounded like a harmless endeavour leaves a decidedly problematic aftertaste in view of the people responsible for organizing it. Usama Abu Gharin also declared his support for the campaign and offered to protect the stands from possible attacks.
"They view themselves as a protection squad for Islam," says one intelligence agency official. The idea of distributing the Koran was not just aimed at winning potential converts, but also to unite the Salafist scene. This has broadly speaking been a success, and apart from a few Salafist preachers who criticised the distribution of the holy book as contrary to the conduct of the Prophet himself, the initiative was met with broad approval. "It has boosted the self-confidence of the Salafist scene," says one intelligence official.
Opinions were however divided again over the violent demonstrations against the display of Mohammed cartoons just a few weeks later, on 5 May, when Salafist protesters attacked police with truncheons and knives. While Abu Usama spurred on his followers from Egypt to defend the honour of the prophet by violent means if necessary, Pierre Vogel appealed for calm.
The demonstrations represented a clear escalation, as up to this point the Salafists had not appeared in such a form. One intelligence agency officer says that many Salafists – but by no means all – have a criminal background and were able to reactivate their "street experience" from the period previous to their conversion.
His assessment of the situation is that for those who have so far failed to make anything of their lives Salafism offers an attractive counter-model: Giving them support, warmth and a sense of brotherhood, and persuading them that they have the "truth" on their side. There should be no objections to this in principle – if it didn't go hand in hand with the willingness to use violence against those of other faiths and beliefs.
Albrecht Metzger
© Qantara.de 2012
Editors: Arian Fariborz, Lewis Gropp/Qantara.de


text:
Labor Day Skate!Monday September 4th!
1:00 p.m. - 6:00 p.m.
$10 Adm. $4 Rental
The Rollercade dates from the 1950s and was originally called Northporte Rollercade. Its name was shortened in 1984. The iconic sign out front, designed by Lionel Sosa in 1958, sports five huge brightly lit neon circles spelling "SKATE", leaving no doubt what activities take place beneath them. The Rollercade has provided generations of families with roller-skating, thumping music, and plenty of bruised knees. San Antonio's premiere roller skating facility seems to be frozen in time in a heavy 70s roller disco theme, complete with neon lights and trippy magic-carpet day-glo swirls. Besides offering public skating, the Rollercade also provides private lessons and parties for young and old alike.
Facility Details
- Family owned and operated since 1959
(Landmark of San Antonio)
- Original hardwood floors
- 20,000 square feet of family fun
- Arcade games with various games including pool
- Free WIFI
- Friendliest staff
- State of the art light show
(Glow skates held during all public sessions)
- Skate Mates available for $10 for up to 3 hours of use


text:
|Damian Conway
|9 Apr 2005
|Last Modified:
|25 Jul 2014
Pod is an evolution of Perl 5's Plain Ol' Documentation (POD) markup. Compared to POD, Perl 6's Pod is much more uniform, somewhat more compact, and considerably more expressive. The Pod dialect also differs in that it is a purely descriptive mark-up notation, with no presentational components.
Pod documents are specified using
Every directive starts either with an equals sign (
=) followed immediately by an identifier [1], or with a
#= or
#| followed immediately by whitespace or an opening bracket.
Directives that start with
= can be indented like the code they interleave, but their initial
= must still be the first non-whitespace character on their line. Directives that start with
#= or
#| can be placed anywhere that a Perl 6 comment can appear, though they are meaningful only in a subset of those places; see Declarator blocks.
An indented Pod block is considered to have a virtual left margin, determined by the indentation of its opening delimiter.
In other words, if a directive is indented from the left margin, the column at which the first character of its opening delimiter appears is thereafter considered the first column of the entire block's contents.
As with Perl 6 heredocs, the virtual margin treats leading tabs as aligning to tabstops spaced every
($?TABSTOP // 8) characters.
The content of a document is specified within one or more
delimited style, paragraph style, abbreviated style, or declarator style. The first three forms are all equivalent; the fourth is distinct.
Anything in a document that is neither a Pod directive nor contained within a Pod block is treated as "ambient" material. Typically this would be the source code of the program that the Pod is documenting. Pod parsers still parse this text into the internal representation of the file, representing it as a
Pod::Block::Ambient block. Renderers will usually ignore such blocks, but see Aliases.
In Perl 5's POD format, once a POD directive is encountered, the parser considers everything that follows to be POD, until an explicit
=cut directive is encountered, at which point the parser flips back to parsing ambient source code. The Perl 6 Pod format is different. All Pod directives have a defined terminator and the Pod parser always reverts to "ambient" at the end of each Pod directive or block. To cause the parser to remain in Pod mode, you must enclose the desired Pod region in a
pod block:
=begin pod =head1 A heading This is Pod too. Specifically, this is a simple C<para> block $this = pod('also'); # Specifically, a code block =end pod
Delimited blocks are bounded by
=begin and
=end markers, both of which are followed by a valid Perl 6 identifier, which is the
=begin head1) or entirely uppercase (for example:
=begin SYNOPSIS) are reserved.
After the typename, the rest of the
=begin marker line is treated as configuration information for the block. This information is used in different ways by different types of blocks, but is always specified using Perl6-ish option pairs. That is, any of:
|Value is...
|Specify with...
|Or with...
|Or with...
|Boolean (true)
|C«key => 1»
|Boolean (false)
|C«key => 0»
|C«key => 'str'»
|C«:key<1 2 3>»
|C«key => [1,2,3]»
|C«:key{a=>1, b=>2}»
|C«key => {a=>1, b=>2}»
All option keys and values must, of course, be constants since Pod is a specification language, not a programming language. Specifically, option values cannot be closures. See Synopsis 2 for details of the various Perl 6 pair notations.
The configuration section may be extended over subsequent lines by starting those lines with an
= in the first (virtual) column followed by a whitespace character.
The lines following the opening delimiter and configuration are the data or contents of the block, which continue until the block's matching
=end marker line. For most block types, these contents may be indented if you wish, without them being treated as code blocks. Unlike Perl 5, indented text is only treated as code within
=code, and semantic blocks.
The general syntax is:
=begin BLOCK_TYPE OPTIONAL CONFIG INFO = OPTIONAL EXTRA CONFIG INFO BLOCK CONTENTS =end BLOCK_TYPE
For example:
=begin table :caption<Table of Contents> Constants 1 Variables 10 Subroutines 33 Everything else 57 =end table =begin Name :required = :width(50) The applicant's full name =end Name =begin Contact :optional The applicant's contact details =end Contact
Note that no blank lines are required around the directives; blank lines within the contents are always treated as part of the contents. This is a universal feature of Pod.
Note also that in the following specifications, a "blank line" is a line that is either empty or that contains only whitespace characters. That is, a blank line matches the Perl 6 pattern:
/^^ \h* $$/. Pod uses blank lines as delimiters, rather than empty lines, to minimize unpleasant surprises when stray spaces or tabs mysteriously turn up in hitherto empty lines.
Paragraph blocks are introduced by a
=for marker and terminated by the next Pod directive or the first blank line (which is not considered to be part of the block's contents). The
=for marker is followed by the name of the block and optional configuration information. The general syntax is:
=for BLOCK_TYPE OPTIONAL CONFIG INFO = OPTIONAL EXTRA CONFIG INFO BLOCK DATA
For example:
=for table :caption<Table of Contents> Constants 1 Variables 10 Subroutines 33 Everything else 57 =for Name :required = :width(50) The applicant's full name =for Contact :optional The applicant's contact details
Abbreviated blocks are introduced by an
'=' sign in the first column, which is followed immediately by the typename of the block. The rest of the line is treated as block data, rather than as configuration. The content terminates at the next Pod directive or the first blank line (which is not part of the block data). The general syntax is:
For example:
=table Constants 1 Variables 10 Subroutines 33 Everything else 57 =Name The applicant's full name =Contact The applicant's contact details
Note that abbreviated blocks cannot specify configuration information. If configuration is required, use a
=for or
=end instead.
The fourth form of Pod block differs from the first three in that it does not specify an explicit typename. Instead, it obtains its identity and purpose from the Perl 6 source code to which it is attached; specifically, from some nearby declarator.
Declarator blocks are introduced by a special Perl comment: either
#= or
#|, which must be immediately followed by either by a space or an opening bracket. If followed by a space, the block is terminated by the end of line; if followed by one or more opening brackets, the block is terminated by the matching sequence of closing brackets.
That is, declarator Pod blocks are syntactically like ordinary Perl 6 single-line comments and embedded comments. The general syntax is:
except that the bracketed forms may use any valid Perl 6 bracket delimiter (including repeated opening brackets), as described in Synopsis 2.
Declarator Pod blocks must either precede or immediately follow a valid Perl 6 declarator, and are then said to be "attached" to it. They are primarily intended to simplify the documentation of code interfaces.
Declarator blocks that start with
#| attach to the declarator immediately after them (separated only by whitespace). Declarator blocks that start with
#= attach to the declarator declared at the start of the line immediately before them. In all other respects they act just like comments (i.e. they are themselves whitespace as far as ambient source code is concerned). This means multiple declarator blocks can be specified in a row and will all attach to the same declarator.
For example:
#| Base class for comms necromancy hierarchy class Magic::Necrotelecomnicon { has $.elemental; #= Source of all power has $!true_name; # Source of all self-protection (not documented) method cast(#|{ A spell } Spell $s) #= Initiate a specified spell normally #= (do not use for class 7 spells) { do_raw_magic($s); } method kast( #= Initiate a specified spell abnormally Spell $s #= The spell to be abnormally initiated ) { do_raw_magic($s, :alternative); } #| This subroutine does the real work sub do_raw_magic ( Spell $s, #= Which spell to invoke *%options #= How to invoke it ) {...} } sub fu (Any $bar) #=[ This text stored in C<&fu.WHY>, not in C<$bar.WHY>, (because C<sub fu> is the declarator at the I<start> of the preceding line) ] multi sub baz(Int $count, Str $name) #=[ This text stored in C<&baz:(Int,Str).WHY> (i.e. the C<.WHY> of the variant, not of the entire multisub) ] #| Attaches to the specific parameterized role, rather than the role group itself role R[::T] {} role R {}
A declarator can have multiple leading and/or trailing Pod comments, in which case they are concatenated with an intermediate newline when their object's
.WHY return value is stringified:
#| This is a special chainsaw #| (Why, you ask?) my SwissArmy $chainsaw #= (It has a rocket launcher!) say $chainsaw.WHY; # prints: This is a special chainsaw # (Why, you ask?) # (It has a rocket launcher!)
The individual leading and trailing Pod comments can be retrieved via the returned Pod object's
.leading and
.trailing methods:
say $chainsaw.WHY.leading; # prints: This is a special chainsaw (Why, you ask?) say $chainsaw.WHY.trailing; # prints: (It has a rocket launcher!)
The Pod object representing each Declarator block is still appended to the current surrounding Pod object (e.g. to
$=pod at the top level). Each such block representation is an object of class
Pod::Block::Declarator, and has a
.WHEREFORE method that returns the code object or metaobject created by the declarator to which the documentation is attached.
In other words,
.WHY and
.WHEREFORE are inverse operations:
.WHY ---------------------------- | | | v ----------------- ----------------- | Declared code | | Documentation | | object | | object | ----------------- ----------------- ^ | | | ---------------------------- .WHEREFORE
When the default
DOC INIT block renders these Pod objects, it automatically includes information about the declarator as well. For instance, the earlier Necrotelecomnicon example might produce something like:
Name: Magic::Necrotelecomnicon: Desc: Base class for comms necromancy hierarchy Attrs: .elemental : Source of all power Methods: .cast(Spell $s) : Initiate a specified spell normally .kast(Spell $s) : Initiate a specified spell abnormally Subroutines: do_raw_magic( : This subroutine does the real work Spell $s, : Which spell to invoke *%options : How to invoke it )
Note, however, that the exact rendering used for declarator blocks is implementation dependent, and may also be pre-empted explicitly by some
DOC configuration statement within the document, such as:
DOC use Pod::Markovian;
DOC INIT { use Pod::Eiffelish::Long; say eiffelish_long($=pod); exit; }
The first three block specifications (delimited, paragraph, and abbreviated) are treated identically by the underlying documentation model, so you can use whichever form is most convenient for a particular documentation task. In the descriptions that follow, the abbreviated form will generally be used, but should be read as standing for all three forms equally.
For example, although Headings shows only:
=head1 Top Level Heading
this automatically implies that you could also write that block as:
=for head1 Top Level Heading
=begin head1 Top Level Heading =end head1
Declarator blocks are distinct from these three forms. They do not have typenames of their own, but rather take their meaning and identity from the declared object or type to which they are attached. In general, they are used specifically to describe that declarand.
Pod predefines a small number of standard configuration options that can be applied uniformly to any built-in block type. These include:
This option specifies that the block is to be nested within its current context. For example, nesting might be applied to block quotes, to textual examples, or to commentaries. In addition the L<C<=code>|#Code blocks>, L<C<=item>|#Lists>, L<C<=input>|#I/O blocks>, and L<C<=output>|#I/O blocks> blocks all have implicit nesting.
Nesting of blocks is usually rendered by adding extra indentation to the block contents, but may also be indicated in other ways: by boxing the contents, by changing the font or size of the nested text, or even by folding the text (so long as a visible placeholder is provided).
Occasionally it is desirable to nest content by more than one level: =begin code =begin para :nested =begin para :nested =begin para :nested "We're going deep, deep, I<deep> undercover!" =end para =end para =end para =end code This can be simplified by giving the C<:nested> option a positive integer value: =begin code :allow<B> =begin para B<:nested(3)> "We're going deep, deep, I<deep> undercover!" =end para =end code You can also give the option a value of zero, to defeat any implicit nesting that might normally be applied to a paragraph. For example, to specify a block of code that should appear I<without> its usual nesting: =begin code :allow<B V> =comment Don't nest this code block in the usual way... B<=begin code :nested(0)>
1 2 3 4 5 6 123456789012345678901234567890123456789012345678901234567890 |------|-----------------------|---------------------------| line instruction comments number code
V<=end code> =end code Note that C<:!nested> could also be used for this purpose: =begin code =Z<>begin code :!nested =end code
This option specifies that the block is to be numbered. The most common use of this option is to create L<numbered headings|#Numbered headings> and L<ordered lists|#Ordered lists>, but it can be applied to any block.
The numbering conventions for headings and lists are specified in those sections, but it is up to individual renderers to decide how to display any numbering associated with other types of blocks.
Note that numbering is never explicit; it is always implied by context.
This option specifies that the contents of the block should be treated as if they had one or more L<formatting codes|#Formatting codes> placed around them.
For example, instead of: =begin code =for comment The next para is both important and fundamental, so doubly emphasize it...
=begin para B<I< Warning: Do not immerse in water. Do not expose to bright light. Do not feed after midnight. >> =end para =end code you can just write: =begin code :allow<B> =begin para B<:formatted<B I>> Warning: Do not immerse in water. Do not expose to bright light. Do not feed after midnight. =end para =end code The internal representations of these two versions are exactly the same, except that the second one retains the C<:formatted> option information as part of the resulting block object.
Like all formatting codes, codes applied via a C<:formatted> are inherently cumulative. For example, if the block itself is already inside a formatting code, that formatting code will still apply, in addition to the extra "basis" and "important" formatting specified by C<:formatted<B I>>.
This option specifies that a block or config has the same formatting properties as the type named by its value. This is useful for creating related L<configurations|#Block pre-configuration> or for making user-defined synonyms for existing types. For example: =begin code =config head2 :like<head1> :formatted<I>
=config Subhead :like<head2> =end code
This option expects a list of formatting codes that are to be recognized within any C<V<>> codes that appear in (or are implicitly applied to) the current block. The option is most often used on C<=code> blocks to allow mark-up within those otherwise verbatim blocks, though it can be used in I<any> block that contains verbatim text. See L<#Formatting within code blocks>.
This option specifies a character that indicates the left margin of the contents of the block. Normally this left margin is determined by the column at which the C<=> of the opening block-delimiter occurs. For example: =begin code =head1 Indenting Pod blocks
=begin para This text is flush with the (virtual) left margin of the Pod block because that margin is implicitly specified by the C<=> of the C<=begin> =end para =end code However, by using the C<:margin> option it is possible to specify a character that acts like an explicit margin when it occurs as the first non-whitespace character on any line within the block. For example: =begin code =head1 Indenting Pod blocks
=begin para :margin<|> |This text is flush with the (virtual) left margin of |the Pod block because that margin is explicitly marked |by the C<|>, as specified by the block's C<:margin<|>> option. =end para =end code The virtual margin can even be to the left of the opening delimiter, which can be convenient to guide subsequent indentations. For example: =begin code sub foo {
V<=begin> pod :margin<|> |=head1 Hey Look: Indented Pod! | |You can indent Pod in Perl 6 |which makes code look cleaner |when documentation is interspersed | | my $this is Code; | |=end pod
... } =end code When a C<:margin> option is used, each subsequent line (until the corresponding closing delimiter is encountered) simply has any text matching C</^^ \s* $margin_char/> automatically removed. This may include a line that then becomes the closing delimiter, as in the above example.
Any line from which such a margin marker is removed automatically resets the implicit margin for subsequent lines of the block, setting it to the length of the "marginalized" indent that was just removed. This implicit margin is then used until the next line with an explicit margin marker is encountered, or the block terminates.
Pod offers notations for specifying a wide range of standard block types...
Pod provides an unlimited number of levels of heading, specified by the
=headN block marker. For example:
=head1 A Top Level Heading =head2 A Second Level Heading =head3 A third level heading =head86 A "Missed it by I<that> much!" heading
While Pod parsers are required to recognize and distinguish all levels of heading, Pod renderers are only required to provide distinct renderings of the first four levels of heading (though they may, of course, provide more than that). Headings at levels without distinct renderings would typically be rendered like the lowest distinctly rendered level.
You can specify that a heading is numbered using the
:numbered option. For example:
=for head1 :numbered The Problem =for head1 :numbered The Solution =for head2 :numbered Analysis =for head3 Overview =for head3 Details =for head2 :numbered Design =for head1 :numbered The Implementation
which would produce:
1. The Problem
2. The Solution
2.1. Analysis
2.2: Design
3. The Implementation
It is usually better to preset a numbering scheme for each heading level, in a series of configuration blocks:
=config head1 :numbered =config head2 :numbered =config head3 :!numbered =head1 The Problem =head1 The Solution =head2 Analysis =head3 Overview =head3 Details =head2 Design =head1 The Implementation
Alternatively, as a short-hand, if the first whitespace-delimited word in a heading consists of a single literal
# character, the
# is removed and the heading is treated as if it had a
:numbered option:
=head1 # The Problem =head1 # The Solution =head2 # Analysis =head3 Overview =head3 Details =head2 # Design =head1 # The Implementation
Note that, even though renderers are not required to distinctly render more than the first four levels of heading, they are required to correctly honour arbitrarily nested numberings. That is:
=head6 # The Rescue of the Kobayashi Maru
should produce something like:
126.96.36.199.1.9. The Rescue of the Kobayashi Maru
Ordinary paragraph blocks consist of text that is to be formatted into a document at the current level of nesting, with whitespace squeezed, lines filled, and any special inline mark-up applied.
Ordinary paragraphs consist of one or more consecutive lines of text, each of which starts with a non-whitespace character at (virtual) column 1. The paragraph is terminated by the first blank line or block directive. For example:
=head1 This is a heading block This is an ordinary paragraph. Its text will be squeezed and short lines filled. It is terminated by the first blank line. This is another ordinary paragraph. Its text will also be squeezed and short lines filled. It is terminated by the trailing directive on the next line. =head2 This is another heading block This is yet another ordinary paragraph, at the first virtual column set by the previous directive
Within a
=finish, or semantic block, ordinary paragraphs do not require an explicit marker or delimiters, but there is also an explicit
para marker (which may be used anywhere):
=para This is an ordinary paragraph. Its text will be squeezed and short lines filled.
and likewise the longer
=for and
=end forms. For example:
=begin para This is an ordinary paragraph. Its text will be squeezed and short lines filled. This is I<still> part of the same paragraph, which continues until an... =end para
As the previous example implies, when any form of explicit
para block is used, any whitespace at the start of each line is removed during rendering. In addition, within a delimited
=begin para/
=end para block, any blank lines are preserved.
Code blocks are used to specify pre-formatted text (typically source code), which should be rendered without rejustification, without whitespace-squeezing, and without recognizing any inline formatting codes. Code blocks also have an implicit nesting associated with them. Typically these blocks are used to show examples of code, mark-up, or other textual specifications, and are rendered using a fixed-width font.
A code block may be implicitly specified as one or more lines of text, each of which starts with a whitespace character at the block's virtual left margin. The implicit code block is then terminated by a blank line. For example:
This ordinary paragraph introduces a code block: $this = 1 * code('block'); $which.is_specified(:by<indenting>);
Implicit code blocks may only be used within
=finish, or semantic blocks.
There is also an explicit
=code block (which can be specified within any other block type, not just
=item, etc.):
The C<loud_update()> subroutine adds feedback: =begin code sub loud_update ($who, $status) { say "$who -> $status"; silent_update($who, $status); } =end code
As the previous example demonstrates, within an explicit
=code block the code can start at the (virtual) left margin. Furthermore, lines that start with whitespace characters after that margin have subsequent whitespace preserved exactly (in addition to the implicit nesting of the code). Explicit
=code blocks may also contain empty lines.
=code blocks automatically disregard all formatting codes, occasionally you may still need to specify some formatting within a code block. For example, you may wish to emphasize a particular keyword in an example (using a
B<> code). Or you may want to indicate that part of the example is metasyntactic (using the
R<> code). Or you might need to insert a non-ASCII character (using the
E<> code).
You can specify a list of formatting codes that should still be recognized within a code block using the
:allow option. The value of the
:allow option must be a list of the (single-letter) names of one or more formatting codes. Those codes will then remain active inside the code block. For example:
=begin code :allow< B R > sub demo { B<say> 'Hello R<name>'; } =end code
would be rendered:
sub demo { say 'Hello name'; }
Note that the use of the
:allow option also makes it possible for verbatim formatting codes (such as
C<> and
V<>) to contain other codes as well.
Pod also provides blocks for specifying the input and output of programs.
=input block is used to specify pre-formatted keyboard input, which should be rendered without rejustification or squeezing of whitespace.
=output block is used to specify pre-formatted terminal or file output which should also be rendered without rejustification or whitespace-squeezing.
Note that, like
=code blocks, both
=input and
=output blocks have an implicit level of nesting. They are also like
=code blocks in that they are typically rendered in a fixed-width font, though ideally all three blocks would be rendered in distinct font/weight combinations (for example: regular serifed for code, bold sans-serif for input, and regular sans-serif for output).
=code blocks, both
=input and
=output blocks honour any nested formatting codes. This is particularly useful since a sample of input will often include prompts (which are, of course, output). Likewise a sample of output may contain the occasional interactive component. Pod provides special formatting codes (
K<> and
T<>) to indicate embedded input or output, so you can use the block type that indicates the overall purpose of the sample (i.e. is it demonstrating an input operation or an output sequence?) and then use the "contrasting" formatting code within the block.
For example, to include a small amount of input in a sample of output you could use the
K<> formatting code:
=begin output Name: Baracus, B.A. Rank: Sgt Serial: 1PTDF007 Do you want additional personnel details? K<y> Height: 180cm/5'11" Weight: 104kg/230lb Age: 49 Print? K<n> =end output
Lists in Pod are specified as a series of contiguous
=item blocks. No special "container" directives or other delimiters are required to enclose the entire list. For example:
The seven suspects are: =item Happy =item Dopey =item Sleepy =item Bashful =item Sneezy =item Grumpy =item Keyser Soze
List items have one implicit level of nesting:
The seven suspects are:
Keyser Soze
Lists may be multi-level, with items at each level specified using the
=item3, etc. blocks. Note that
=item is just an abbreviation for
=item1. For example:
=item1 Animal =item2 Vertebrate =item2 Invertebrate =item1 Phase =item2 Solid =item2 Liquid =item2 Gas =item2 Chocolate
which would be rendered something like:
• Animal
– Vertebrate
– Invertebrate
• Phase
– Solid
– Liquid
– Gas
– Chocolate
Pod parsers must issue a warning if a "level-N+1"
=item block (e.g. an
=item3, etc.) appears anywhere except where there is a preceding "level-N"
=item in the same surrounding block. That is, an
=item3 should only be specified if an
=item2 appears somewhere before it, and that
=item2 should itself only appear if there is a preceding
Note that item blocks within the same list are not physically nested. That is, lower-level items should not be specified inside higher-level items:
=comment WRONG... =begin item1 -------------- The choices are: | =item2 Liberty ==< Level 2 |==< Level 1 =item2 Death ==< Level 2 | =item2 Beer ==< Level 2 | =end item1 --------------
=comment CORRECT... =begin item1 --------------- The choices are: |==< Level 1 =end item1 --------------- =item2 Liberty ==================< Level 2 =item2 Death ==================< Level 2 =item2 Beer ==================< Level 2
An item is part of an ordered list if the item has a
:numbered configuration option:
=for item1 :numbered Visito =for item2 :numbered Veni =for item2 :numbered Vidi =for item2 :numbered Vici
This would produce something like:
1. Visito
1.1. Veni
1.2. Vidi
1.3. Vici
although the numbering scheme is entirely at the discretion of the renderer, so it might equally well be rendered:
1. Visito
1a. Veni
1b. Vidi
1c. Vici
or even:
A: Visito
(i) Veni
(ii) Vidi
(iii) Vici
Alternatively, if the first word of the item consists of a single
# character, the item is treated as having a
:numbered option:
=item1 # Visito =item2 # Veni =item2 # Vidi =item2 # Vici
To specify an unnumbered list item that starts with a literal
#, either make the octothorpe verbatim:
=item V<#> introduces a comment
or explicitly mark the item itself as being unnumbered:
=for item :!numbered # introduces a comment
The numbering of successive
=item1 list items increments automatically, but is reset to 1 whenever any other kind of non-ambient Pod block appears between two
=item1 blocks. For example:
The options are: =item1 # Liberty =item1 # Death =item1 # Beer The tools are: =item1 # Revolution =item1 # Deep-fried peanut butter sandwich =item1 # Keg
would produce:
The options are:
1. Liberty
2. Death
3. Beer
The tools are:
1. Revolution
2. Deep-fried peanut butter sandwich
3. Keg
The numbering of nested items (
=item3, etc.) only resets (to 1) when the higher-level item's numbering either resets or increments.
To prevent a numbered
=item1 from resetting after a non-item block, you can specify the
:continued option:
=for item1 # Retreat to remote Himalayan monastery =for item1 # Learn the hidden mysteries of space and time I<????> =for item1 :continued # Prophet!
which produces:
1. Retreat to remote Himalayan monastery
2. Learn the hidden mysteries of space and time
3. Prophet!
List items that are not
:numbered are treated as defining unordered lists. Typically, such lists are rendered with bullets. For example:
=item1 Reading =item2 Writing =item3 'Rithmetic
might be rendered:
• Reading
— Writing
¤ 'Rithmetic
As with numbering styles, the bulletting strategy used for different levels within a nested list is entirely up to the renderer.
Use the delimited form of the
=item block to specify items that contain multiple paragraphs. For example:
Let's consider two common proverbs: =begin item :numbered I<The rain in Spain falls mainly on the plain.> This is a common myth and an unconscionable slur on the Spanish people, the majority of whom are extremely attractive. =end item =begin item :numbered I<The early bird gets the worm.> In deciding whether to become an early riser, it is worth considering whether you would actually enjoy annelids for breakfast. =end item As you can see, folk wisdom is often of dubious value.
which produces:
Let's consider two common proverbs:
The rain in Spain falls mainly on the plain.
This is a common myth and an unconscionable slur on the Spanish people, the majority of whom are extremely attractive.
The early bird gets the worm.
In deciding whether to become an early riser, it is worth considering whether you would actually enjoy annelids for breakfast.
As you can see, folk wisdom is often of dubious value.
To create term/definition lists, use a
=defn block. This is similar in effect to an
=item block, in that a series of
=defn blocks implicitly defines a list (but which might then be rendered into HTML using
<DL>...</DL> tags, rather than
<UL>...</UL> tags)
The first non-blank line of content is treated as a term being defined, and the remaining content is treated as the definition for the term. For example:
=defn MAD Affected with a high degree of intellectual independence. =defn MEEKNESS Uncommon patience in planning a revenge that is worth while. =defn MORAL Conforming to a local and mutable standard of right. Having the quality of general expediency.
Like other kinds of list items, definitions can be numbered, using either an option or a leading
=for defn :numbered SELFISH Devoid of consideration for the selfishness of others. =defn # SUCCESS The one unpardonable sin against one's fellows.
Any block can be nested by specifying a
:nested option on it:
=begin para :nested We are all of us in the gutter,E<NL> but some of us are looking at the stars! =end para
However, qualifying each nested paragraph individually quickly becomes tedious if there are many in a sequence, or if multiple levels of nesting are required:
=begin para :nested We are all of us in the gutter,E<NL> but some of us are looking at the stars! =end para =begin para :nested(2) -- Oscar Wilde =end para
So Pod provides a
=nested block that marks all its contents as being nested:
=begin nested We are all of us in the gutter,E<NL> but some of us are looking at the stars! =begin nested -- Oscar Wilde =end nested =end nested
Nesting blocks can contain any other kind of block, including implicit paragraph and code blocks. Note that the relative physical indentation of the blocks plays no role in determining their ultimate nesting. The preceding example could equally have been specified:
=begin nested We are all of us in the gutter,E<NL> but some of us are looking at the stars! =begin nested -- Oscar Wilde =end nested =end nested
Simple tables can be specified in Pod using a
=table block. The table may be given an associated description or title using the
:caption option.
Columns are separated by two or more consecutive whitespace characters (double-space), or by a vertical line (
|) or a border intersection (
+), either of which must be separated from any content by at least one whitespace character. Note that only one column separator type is allowed in a single line, but different lines are allowed to use different visible column separator types (that style is not recommended). Using a mixture of visible and non-visible column separator types in a table is an error.
Rows can be specified in one of two ways: either one row per line, with no separators; or multiple lines per row with explicit horizontal separators (whitespace, intersections (
+), or horizontal lines:
_) between every row. Either style can also have an explicitly separated header row at the top. If rows are using the two-whitespace-character separator, the row cells should be carefully aligned to ensure the table is interpreted as the user intended.
Each individual table cell is separately formatted, as if it were a nested
=para. Note that table rows are expected to have the same number of cells.
This means you can create tables compactly, line-by-line:
=table The Shoveller Eddie Stevens King Arthur's singing shovel Blue Raja Geoffrey Smith Master of cutlery Mr Furious Roy Orson Ticking time bomb of fury The Bowler Carol Pinnsler Haunted bowling ball
or line-by-line with multi-line headers:
=table Superhero | Secret | | Identity | Superpower ==============|=================|================================ The Shoveller | Eddie Stevens | King Arthur's singing shovel Blue Raja | Geoffrey Smith | Master of cutlery Mr Furious | Roy Orson | Ticking time bomb of fury The Bowler | Carol Pinnsler | Haunted bowling ball
or with multi-line headers and multi-line data:
=begin table :caption('The Other Guys') Secret Superhero Identity Superpower ============= =============== =================== The Shoveller Eddie Stevens King Arthur's singing shovel Blue Raja Geoffrey Smith Master of cutlery Mr Furious Roy Orson Ticking time bomb of fury The Bowler Carol Pinnsler Haunted bowling ball =end table
Blocks whose names contain at least one uppercase and one lowercase letter are assumed to be destined for specialized renderers or parser plug-ins. For example:
=begin Xhtml <object type="video/quicktime" data="onion.mov"> =end Xhtml
=Image http://www.perlfoundation.org/images/perl_logo_32x104.png
Named blocks are converted by the Pod parser to block objects; specifically, to objects of a subclass of the standard
Pod::Block::Named class.
For example, the blocks of the previous example would be converted to objects of the classes
Pod::Block::Named::Xhtml and
Pod::Block::Named::Image respectively. Both of those classes would be automatically created as subclasses of the
Pod::Block::Named class (unless they were already defined in a module loaded via some prior
DOC use.
The resulting object's
.typename method retrieves the short name of the block type:
'Image', etc. The object's
.config method retrieves the list of configuration options (if any). The object's
.contents method retrieves a list of the block's verbatim contents.
Named blocks for which no explicit class has been defined or loaded are usually not rendered by the standard renderers.
Note that all block names consisting entirely of lowercase or entirely of uppercase letters are reserved. See Semantic blocks.
All Pod blocks are intrinsically Perl 6 comments, but
$=pod variable within a Perl 6 program.
Comments are useful for meta-documentation (documenting the documentation):
=comment Add more here about the algorithm
and for temporarily removing parts of a document:
=item # Retreat to remote Himalayan monastery =item # Learn the hidden mysteries of space and time =item # Achieve enlightenment =begin comment =item # Prophet! =end comment
Note that, since the Perl interpreter never executes embedded Pod blocks,
comment blocks can also be used as an alternative form of nestable block comments in Perl 6:
=begin comment for @files -> $file { shell("rm -rf $file"); } =end comment
=finish block
=finish block is special in that all three of its forms (delimited, paragraph, and abbreviated) are terminated only by the end of the current file. That is, neither
=finish nor
=for finish are terminated by the next blank line, and
=end finish has no effect within a
=begin finish block. A warning is issued if an explicit
=end finish appears within a document.
=finish block indicates the end-point of any ambient material within the document. This means that the parser will treat all the remaining text in the file as Pod, even if it is not inside an explicit block. In other words, apart from its special end-of-file termination behaviour, an
=finish block is in all other respects identical to a
=pod block.
Named Pod blocks whose typename is
data are the Perl 6 equivalent of the Perl 5
__DATA__ section. The difference is that
=data blocks are just regular Pod blocks and may appear anywhere within a source file, and as many times as required.
There is a corresponding variable,
$=data, from which each
=data block can be retrieved.
$=data holds an object that does both the Associative and Positional roles.
=data block can be given a
:key option, to name it. The contents of any
=data block with a key are accessible (as a single string) via the Associative aspect of
$=data object. For example:
=begin data :key<Virtues> Laziness Impatience Hubris =end data say 'The three virtues are:'; say $=data<Virtues>;
The contents of any
=data block that does not have a
:key are accessible (as a single string) via the Positional aspect of
$=data. Unkeyed
=data blocks are stored in the same order they appear in the file. For example:
say 'The second anti_Virtue is: ', $=data[1]; =data Industry =data Patience =data Humility
Note that, as the preceding example illustrates, because Pod is a compile-time phenomenon, it is possible to specify
=data blocks after the point in the source where their contents will be used (provided they're not being used in a
BEGIN, of course).
$=data itself is stringified, it returns the concatenation of all the unkeyed
=data blocks the parser has seen.
=data blocks are never rendered by the standard Pod renderers.
All uppercase block typenames are reserved for specifying standard documentation, publishing, source components, or meta-information of a compunit it needs to be able to be selected for loading. In particular, all the standard components found in Perl and manpage documentation have reserved uppercase typenames.
Standard semantic blocks include:
The plural forms of each of these keywords are also reserved, and are aliases for the singular forms.
Most of these blocks would typically be used in their full delimited forms:
=begin SYNOPSIS use Magic::Parser; my Magic::Parser $parser .= new(); my $tree = $parser.parse($fh); =end SYNOPSIS
Semantic blocks can be considered to be variants of the
=head1 block in most respects (and most renderers will treat them as such). The main difference is that, in a
=head1 block, the heading is the contents of the block; whereas, in a semantic block, the heading is derived from the typename of the block itself and the block contents are instead treated as the
=para or
=code block(s) belonging to the heading.
The use of these special blocks is not required; you can still just write:
=head1 SYNOPSIS =begin code use Magic::Parser my Magic::Parser $parser .= new(); my $tree = $parser.parse($fh); =end code
However, using the keywords adds semantic information to the documentation, which may assist various renderers, summarizers, coverage tools, document refactorers, and other utilities. This is because a semantic block encloses the text it controls (unlike a
=head1, which merely precedes its corresponding text), so using semantic blocks produces a more explicitly structured document.
Note that there is no requirement that semantic blocks be rendered in a particular way (or at all). Specifically, it is not necessary to preserve the capitalization of the keyword. For example, the
=SYNOPSIS block of the preceding example might be rendered like so:
3. Synopsis
use Perl6::Magic::Parser; my $rep = Perl6::Magic::Parser.parse($fh, :all_pod);
Formatting codes provide a way to add inline mark-up to a piece of text within the contents of (most types of) Pod block (including all declarator blocks). Formatting codes are themselves a type of block, and may nest other formatting codes. other type of block (most often, other formatting codes). In particular, you can nest comment blocks in the middle of a formatting code:
B<I shall say this loudly Z<and repeatedly> and with emphasis.>
All Pod formatting codes consist of a single capital letter followed immediately by a set of angle brackets. The brackets contain the text or data to which the formatting code applies. You can use a set of single angles (
<...>), a set of double angles (
«...»), or multiple single-angles (
Within angle delimiters, you cannot use sequences of the same angle characters that are longer than the delimiters:
=comment These are errors... C< $foo<<bar>> > The Perl 5 heredoc syntax was: C< <<END_MARKER >
You can use sequences of angles that are the same length as the delimiters, but they must be balanced. For example:
C< $foo<bar> > C<< $foo<<bar>> >>
If you need an unbalanced angle, either use different delimiters:
C«$foo < $bar» The Perl 5 heredoc syntax was: C« <<END_MARKER »
or delimiters with more consecutive angles than your text contains:
C<<$foo < $bar>> The Perl 5 heredoc syntax was: C<<< <<END_MARKER >>>
A formatting code ends at the matching closing angle bracket(s), or at the end of the enclosing block or formatting code in which the opening angle bracket was specified, whichever comes first (this includes paragraph and abbreviated blocks, ending with blank a line). Pod parsers are required to issue a warning whenever a formatting code is terminated by the end of an outer block rather than by its own delimiter (unless the user explicitly disables the warning).
Pod provides three formatting codes that flag their contents with increasing levels of significance:
U<> formatting code specifies that the contained text is unusual or distinctive; that it is of minor significance. Typically such content would be rendered in an underlined style.
I<> formatting code specifies that the contained text is important; that it is of major significance. Such content would typically be rendered in italics or in
<em>...</em> tags
B<> formatting code specifies that the contained text is the basis or focus of the surrounding text; that it is of fundamental significance. Such content would typically be rendered in a bold style or in
<strong>...</strong> tags.
D<> formatting code indicates that the contained text is a definition, introducing a term that the adjacent text elucidates. It is the inline equivalent of a
=defn block. For example:
There ensued a terrible moment of D<coyotus interruptus>: a brief suspension of the effects of gravity, accompanied by a sudden to-the-camera realization of imminent downwards acceleration.
A definition may be given synonyms, which are specified after a vertical bar and separated by semicolons:
A D<formatting code|formatting codes;formatters> provides a way to add inline mark-up to a piece of text.
A definition would typically be rendered in italics or
<dfn>...</dfn> tags and will often be used as a link target for subsequent instances of the term (or any of its specified synonyms) within a hypertext.
Pod provides formatting codes for specifying inline examples of input, output, code, and metasyntax:
T<> formatting code specifies that the contained text is terminal output; that is: something that a program might print out. Such content would typically be rendered in a fixed-width font or with
<samp>...</samp> tags. The contents of a
T<> code are always space-preserved (as if they had an implicit
S<...> around them). The
T<> code is the inline equivalent of the
=output block.
K<> formatting code specifies that the contained text is keyboard input; that is: something that a user might type in. Such content would typically be rendered in a fixed-width font (preferably a different font from that used for the
T<> formatting code) or with
<kbd>...</kbd> tags. The contents of a
K<> code are always space-preserved. The
K<> code is the inline equivalent of the
=input block.
C<> formatting code specifies that the contained text is code; that is, something that might appear in a program or specification. Such content would typically be rendered in a
fixed-width font (preferably a different font from that used for the
T<> or
K<> formatting codes) or with
<code>...</code> tags. The contents of a
C<> code are space-preserved and verbatim. The
C<> code is the inline equivalent of the
=code block.
To include other formatting codes in a
C<> code, you can lexically reconfigure it:
=begin para =config C<> :allow<E I> Perl 6 makes extensive use of the C<E<laquo>> and C<E<raquo>> characters, for example, in a hash look-up: C<%hashI<E<laquo>>keyI<E<raquo>>> =end para
To enable entities in every
C<...> put a
=config C<> :allow<E> at the top of the document
R<> formatting code specifies that the contained text is a replaceable item, a placeholder, or a metasyntactic variable. It is used to indicate a component of a syntax or specification that should eventually be replaced by an actual value. For example:
The basic C<ln> command is: C<ln> R<source_file> R<target_file>
Then enter your details at the prompt: =for input Name: R<your surname> ID: R<your employee number> Pass: R<your 36-letter password>
Typically replaceables would be rendered in fixed-width italics or with
<var>...</var> tags. The font used should be the same as that used for the
C<> code, unless the
R<> is inside a
K<> or
T<> code (or the equivalent
=input or
=output blocks), in which case their respective fonts should be used.
V<> formatting code treats its entire contents as being verbatim, disregarding every apparent formatting code within it. For example:
The B<V< V<> >> formatting code disarms other codes such as V< I<>, C<>, B<>, and M<> >.
Note, however that the
V<> code only changes the way its contents are parsed, not the way they are rendered. That is, the contents are still wrapped and formatted like plain text, and the effects of any formatting codes surrounding the
V<> code are still applied to its contents. For example the previous example is rendered:
The V<> formatting code disarms other codes such as I<>, C<>, B<>, and M<> .
You can prespecify formatting codes that remain active within a
V<> code, using the
:allow option.
Z<> formatting code indicates that its contents constitute a zero-width comment, which should not be rendered by any renderer. For example:
The "exeunt" command Z<Think about renaming this command?> is used to quit all applications.
In Perl 5 POD, the
Z<> code was widely used to break up text that would otherwise be considered mark-up:
In Perl 5 POD, the ZZ<><> code was widely used to break up text that would otherwise be considered mark-up.
That technique still works, but it's now easier to accomplish the same goal using a verbatim formatting code:
In Perl 5 POD, the V<V<Z<>>> code was widely used to break up text that would otherwise be considered mark-up.
Moreover, the
C<> code automatically treats its contents as being verbatim, which often eliminates the need for the
V<> as well:
In Perl 5 POD, the V<C<Z<>>> code was widely used to break up text that would otherwise be considered mark-up.
Z<> formatting code is the inline equivalent of a
=comment block.
Most Pod renderers will provide a mechanism that allows particular Pod blocks to be explicitly excluded or included if they match a particular pattern. For example, a renderer might be instructed to omit any block that contains the pattern
/CONFIDENTIAL/. Corresponding "invisibility markers" can then be placed inside
Z<> comments within any block that should not normally be displayed. For example:
class Widget is Bauble { has $.things; #= a collection of other stuff #={ Z<CONFIDENTIAL> This variable needs to be replaced for political reasons } }
L<> code is used to specify all kinds of links, filenames, citations, and cross-references (both internal and external).
A link specification consists of a scheme specifier terminated by a colon, followed by an external address (in the scheme's preferred syntax), followed by an internal address (again, in the scheme's syntax). All three components are optional, though at least one must be present in any link specification.
Usually, in schemes where an internal address makes sense, it will be separated from the preceding external address by a
#, unless the particular addressing scheme requires some other syntax. When new addressing schemes are created specifically for Pod it is strongly recommended that
# be used to mark the start of internal addresses.
Standard schemes include:
A standard web URL. For example: =begin code :allow<B> This module needs the LAME library (available from L<B<http://www.mp3dev.org/mp3/>>) =end code If the link does not start with C<//> it is treated as being relative to the location of the current document: =begin code :allow<B> See also: L<B<http:tutorial/faq.html>> and L<B<http:../examples/index.html>> =end code
A filename on the local system. For example: =begin code :allow<B> Next, edit the global config file (that is, either L<B<file:/usr/local/lib/.configrc>> or L<B<file:~/.configrc>>). =end code Filenames that don't begin with a C</> or a C<~> are relative to the current document's location: =begin code :allow<B> Then, edit the local config file (that is, either L<B<file:.configrc>> or L<B<file:CONFIG/.configrc>>. =end code
An email address. Typically, activating this type of link invokes a mailer. For example: =begin code :allow<B> Please forward bug reports to L<B<mailto:[email protected]>> =end code
A link to the system manpages. For example: =begin code :allow<B> This module implements the standard Unix L<B<man:find(1)>> facilities. =end code
A link to some other documentation, typically a module or part of the core documentation; things that would normally be read with C<perl --doc>. For example: =begin code :allow<B> You may wish to use L<B<doc:Data::Dumper>> to view the results. See also: L<B<doc:perldata>>. =end code
A link to the L<block-form|#Definition lists> or L<inline|#Definitions> definition of the specified term within the current document. For example: =begin code :allow<B> He was highly prone to B<D<lexiphania>>: an unfortunate proclivity for employing grandiloquisms (for example, words such as "proclivity", "grandiloquism", and indeed "lexiphania").
B<=defn glossoligation> Restraint of the tongue (voluntary or otherwise) =end code and later, to link back to the definition =begin code :allow<B> To treat his chronic L<B<defn:lexiphania>> the doctor prescribed an immediate L<B<defn:glossoligation>> or, if that proved ineffective, a complete cephalectomy. =end code
The International Standard Book Number or International Standard Serial Number for a publication. For example: =begin code :allow<B> The Perl Journal was a registered serial publication (L<B<issn:1087-903X>>) =end code
To refer to a specific section within a webpage, manpage, or Pod document, add the name of that section after the main link, separated by a
#. For example:
Also see: L<man:bash(1)#Compound Commands>, L<doc:perlsyn#For Loops>, and L<http://dev.perl.org/perl6/syn/S04.html#The_for_statement>
To refer to a section of the current document, omit the external address:
This mechanism is described under L<doc:#Special Features> below.
The scheme name may also be omitted in that case:
This mechanism is described under L<#Special Features> below.
Normally a link is presented as some rendered version of the link specification itself. However, you can specify an alternate presentation by prefixing the link with the desired text and a vertical bar. Whitespace is not significant on either side of the bar. For example:
This module needs the L<LAME library|http://www.mp3dev.org/mp3/>. You could also write the code L<in Latin | doc:Lingua::Romana::Perligata> His L<lexiphanic|defn:lexiphania>> tendencies were, alas, incurable.
A second kind of link—the
P<> or placement link—works in the opposite direction. Instead of directing focus out to another document, it allows you to assimilate the contents of another document into your own.
In other words, the
P<> formatting code takes a URI and (where possible) inserts the contents of the corresponding document inline in place of the code itself.
P<> codes are handy for breaking out standard elements of your documentation set into reusable components that can then be incorporated directly into multiple documents. For example:
might produce:
This document is copyright (c) MegaGigaTeraPetaCorp, 2006. All rights reserved.
If a renderer cannot find or access the external data source for a placement link, it must issue a warning and render the URI directly in some form, possibly as an outwards link. For example:
See: std_copyright.pod
You can use any of the following URI forms (see Links) in a placement link:
http: and
toc: form is a special pseudo-scheme that inserts a table of contents in place of the
P<> code. After the colon, list the block types that you wish to include in the table of contents. For example, to place a table of contents listing only top- and second-level headings:
P<toc: head1 head2>
To place a table of contents that lists the top four levels of headings, as well as any tables:
P<toc: head1 head2 head3 head4 table>
To place a table of diagrams (assuming a user-defined
Diagram block):
P<toc: Diagram>
Note also that, for
P<toc:...>, all semantic blocks are treated as equivalent to
head1 headings, and the
=item equivalence is preserved.
A document may have as many
P<toc:...> placements as necessary.
A variation on placement codes is the
A<> code, which is replaced by the contents of the named alias or object specified within its delimiters. For example:
=alias PROGNAME Earl Irradiatem Eventually =alias VENDOR 4D Kingdoms =alias TERMS_URL L<http://www.4dk.com/eie> The use of A<PROGNAME> is subject to the terms and conditions laid out by A<VENDOR>, as specified at A<TERMS_URL>.
Any compile-time Perl 6 object that starts with a sigil is automatically available within an alias placement as well. Unless the object is already a string type, it is converted to a string during document-generation by implicitly calling
.perl on it.
So, for example, a document can refer to its own filename (as
A<$?FILE>), or to the subroutine inside which the specific Pod is nested (as
A<&?ROUTINE>), or to the current class (as
A<$?CLASS>). Similarly, the value of any program constants defined with sigils can be easily reproduced in documentation:
# Actual code... constant Num $GROWTH_RATE = 1.6; =pod =head4 Standard Growth Rate The standard growth rate is assumed to be A<$GROWTH_RATE>.
Non-mutating method calls on these objects are also allowed, so a document can reproduce the surrounding subroutine's signature (
A<&?ROUTINE.signature>) or the type of a constant (
See Aliases for further details of the aliasing macro mechanism.
Any text enclosed in an
S<> code is formatted normally, except that every whitespace character in it—including any newline—is preserved. These characters are also treated as being non-breaking (except for the newlines, of course). For example:
The emergency signal is: S< dot dot dot dash dash dash dot dot dot>.
would be formatted like so:
The emergency signal is: dot dot dot dash dash dash dot dot dot.
rather than:
The emergency signal is: dot dot dot dash dash dash dot dot dot.
To include Unicode code points or HTML5 character references in a Pod document, specify the required
E<> code.
If the
E<> contains a number, that number is treated as the decimal Unicode value for the desired code point. For example:
Perl 6 makes considerable use of E<171> and E<187>.
You can also use explicit binary, octal, decimal, or hexadecimal numbers (using the Perl 6 notations for explicitly based numbers):
Perl 6 makes considerable use of E<0b10101011> and E<0b10111011>. Perl 6 makes considerable use of E<0o253> and E<0o273>. Perl 6 makes considerable use of E<0d171> and E<0d187>. Perl 6 makes considerable use of E<0xAB> and E<0xBB>.
If the
E<> contains anything that is not a number, the contents are interpreted as a Unicode character name (which is always uppercase), or else as an HTML5 named character reference. For example:
Perl 6 makes considerable use of E<LEFT DOUBLE ANGLE BRACKET> and E<RIGHT DOUBLE ANGLE BRACKET>.
or, equivalently:
Perl 6 makes considerable use of E<laquo> and E<raquo>.
Multiple consecutive entities (in any format) can be specified in a single
E<> code, separated by semicolons:
Perl 6 makes considerable use of E<LEFT DOUBLE ANGLE BRACKET;hellip;0xBB>.
Anything enclosed in an
X<> code is an index entry. The contents of the code are both formatted into the document and used as the (case-insensitive) index entry:
An X<array> is an ordered list of scalars indexed by number, starting with 0. A X<hash> is an unordered collection of scalar values indexed by their associated string key.
You can specify an index entry in which the indexed text and the index entry are different, by separating the two with a vertical bar:
An X<array|arrays> is an ordered list of scalars indexed by number, starting with 0. A X<hash|hashes> is an unordered collection of scalar values indexed by their associated string key.
In the two-part form, the index entry comes after the bar and is case-sensitive.
You can specify hierarchical index entries by separating indexing levels with commas:
An X<array|arrays, definition of> is an ordered list of scalars indexed by number, starting with 0. A X<hash|hashes, definition of> is an unordered collection of scalar values indexed by their associated string key.
You can specify two or more entries for a single indexed text, by separating the entries with semicolons:
A X<hash|hashes, definition of; associative arrays> is an unordered collection of scalar values indexed by their associated string key.
The indexed text can be empty, creating a "zero-width" index entry:
X<|puns, deliberate>This is called the "Orcish Manoeuvre" because you "OR" the "cache".
Anything enclosed in an
N<> code is an inline note. For example:
Use a C<for> loop instead.N<The Perl 6 C<for> loop is far more powerful than its Perl 5 predecessor.> Preferably with an explicit iterator variable.
Renderers may render such annotations in a variety of ways: as footnotes, as endnotes, as sidebars, as pop-ups, as tooltips, as expandable tags, etc. They are never, however, rendered as unmarked inline text. So the previous example might be rendered as:
Use a
for loop instead.† Preferably with an explicit iterator variable.
and later:
† The Perl 6
for loop is far more powerful than its Perl 5 predecessor.
Modules loaded with a
DOC use can define classes that implement new formatting codes, which can then be specified using the
M<> code. An
M<> code must start with a colon-terminated scheme specifier. The rest of the enclosed text is treated as the (verbatim) contents of the formatting code. For example:
DOC use Pod::TT; =head1 Overview of the M<TT: $CLASSNAME > class (version M<TT: $VERSION>) M<TT: get_description($CLASSNAME) >
M<> formatting code is the inline equivalent of a named block.
Internally an
M<> code is converted to an object derived from the
Pod::FormattingCode::Named class. The name of the scheme becomes the final component of the object's classname. For instance, the
M<> code in the previous example would be converted to a
Pod::FormattingCode::Named::TT object, whose
.typename method retrieves the string
"TT" and whose
.contents method retrieves a list of the formatting code's (verbatim, unformatted) contents.
If the formatting code is unrecognized, the contents of the code (i.e. everything after the first colon) would normally be rendered as ordinary text.
By default, Pod assumes that documents are Unicode, encoded in one of the three common schemes (UTF-8, UTF-16, or UTF-32). The particular scheme a document uses is autodiscovered by examination of the first few bytes of the file (where possible). If the autodiscovery fails, UTF-8 is assumed, and parsers may treat any non-UTF-8 bytes later in the document as fatal errors.
At any point in a document, you can explicitly set or change the encoding of its content using the
=encoding directive:
=encoding ShiftJIS =encoding Macintosh =encoding KOI8-R
The specified encoding is used from the start of the next line in the document. If a second
=encoding directive is encountered, the current encoding changes again after that line. Note, however, that the second encoding directive must itself be encoded using the first encoding scheme.
This requirement also applies to an
=encoding directive at the very beginning of the file. That is, it must itself be encoded in the default UTF-8, -16, or -32. However, as a special case, the autodiscovery mechanism will (as far as possible) also attempt to recognize "self-encoded"
=encoding directives that begin at the first byte of the file. For example, at the start of a ShiftJIS-encoded file you can specify
=encoding ShiftJIS in the ShiftJIS encoding.
=encoding directive affects any ambient code between the Pod as well. That is, Perl 6 uses
=encoding directives to determine the encoding of its source code as well as that of any documentation.
Note that
=encoding is a fundamental Pod directive, like
=begin or
=for; it is not an instance of an abbreviated block. Hence there is no paragraph or delimited form of the
=encoding directive (just as there is no paragraph or delimited form of
=config directive allows you to prespecify standard configuration information that is applied to every block of a particular type.
For example, to specify particular formatting for different levels of heading, you could preconfigure all the heading blocks with appropriate formatting schemes:
=config head1 :formatted<B U> :numbered =config head2 :like<head1> :formatted<I> =config head3 :formatted<U> =config head4 :like<head3> :formatted<I>
The general syntax for configuration directives is:
=config BLOCK_TYPE CONFIG OPTIONS = OPTIONAL EXTRA CONFIG OPTIONS
=encoding, a
=config is a directive, not a block. Hence, there is no paragraph or delimited form of the
=config directive. Each
=config specification is lexically scoped to the surrounding block in which it is specified.
Note that, if a particular block later explicitly specifies a configuration option with the same key, that option overrides the pre-configured option. For example, given the heading configurations in the previous example, to specify a non-basic second-level heading:
=for head2 :formatted<I U> Details
:like option causes the current formatting options for the named block type to be (lexically) replaced by the complete formatting information of the block type specified as the
:like's value. That other block type must already have been preconfigured. Any additional formatting specifications are subsequently added to that config. For example:
=comment In the current scope make =head2 an "important" variant of =head1 =config head2 :like<head1> :formatted<I>
Incidentally, this also means you can arrange for an explicit
:formatted option to augment an existing
=config, rather than replacing it. Like so:
=comment Mark this =head3 (but only this one) as being important (in addition to the normal formatting)... =head3 :like<head3> :formatted<I>
You can also lexically preconfigure a formatting code, by naming it with a pair of angles as a suffix. For example:
=comment Always allow E<> codes in any (implicit or explicit) V<> code... =config V<> :allow<E>
=comment All inline code to be marked as important... =config C<> :formatted<I>
Note that, even though the formatting code is named using single-angles, the preconfiguration applies regardless of the actual delimiters used on subsequent instances of the code.
=alias directive provides a way to define lexically scoped synonyms for longer Pod sequences, (meta)object declarators from the code, or even entire chunks of ambient source. These synonyms can then be inserted into subsequent Pod using the
A<> formatting code.
Note that
=alias is a fundamental Pod directive, like
=begin or
=for; there are no equivalent paragraph or delimited forms.
There are two forms of
=alias directive: macro aliases and contextual aliases. Both forms are lexically scoped to the surrounding Pod block.
The simplest form of alias takes two arguments. The first is an identifier (which is usually specified in uppercase, though this is certainly not mandatory). The second argument consists of one or more lines of replacement text.
This creates a lexically scoped Perl 6 macro that can be invoked during document generation by placing the identifier (i.e. the first argument of the alias) in an
A<> formatting code. This formatting code is then replaced by the text returned by new macro.
The replacement text returned by the alias macro begins at the first non-whitespace character after the alias's identifier, and continues to the end of the line. You can extend the replacement text over multiple lines by starting the following line(s) with an
= (at the same level of indentation as the
=alias directive itself) followed by at least one whitespace. Each addition line of replacement text uses the original line's (virtual) left margin, as specified by the indentation of the replacement text on the
=alias line.
For example:
=alias PROGNAME Earl Irradiatem Evermore =alias VENDOR 4D Kingdoms =alias TERMS_URLS =item L<http://www.4dk.com/eie> = =item L<http://www.4dk.co.uk/eie.io/> = =item L<http://www.fordecay.ch/canttouchthis> The use of A<PROGNAME> is subject to the terms and conditions laid out by A<VENDOR>, as specified at: A<TERMS_URL>
would produce:
The use of Earl Irradiatem Evermore is subject to the terms and conditions laid out by 4D Kingdoms Inc, as specified at:
The advantage of using aliases is, obviously, that the same alias can be reused in multiple places in the documentation. Then, if the replacement text ever has to be changed, it need only be modified in a single place:
=alias PROGNAME Count Krunchem Constantly =alias VENDOR Last Chance Receivers Intl =alias TERMS_URLS L<http://www.c11.com/generic_conditions>
If the
=alias directive is specified with only a single argument (that is, with only its identifier), a
=alias directive must be followed immediately (on the next non-blank line) by ambient code.
The single argument is then used as the name of the alias being created, and some portion of the following code is used as the value returned by the alias macro.
Note that the code block following the
=alias line is still treated as real code by the Perl 6 parser, but its contents are also used to create the replacement macro of the alias. This allows the developer to reproduce chunks of actual source code directly in the documentation, without having to copy it.
If the code following the one-argument
=alias directive begins with a sequence of one or more repetitions of any opening bracket character, the replacement macro returns a string containing everything from the end of that opening sequence to just before the corresponding closing bracket sequence. For example:
# This is actual code... sub hash_function ($key) =alias HASHCODE { my $hash = 0; for $key.split("") -> $char { $hash = $hash*33 + $char.ord; } return $hash; } =begin pod An ancient (but fast) hashing algorithm is used: =begin code :allow<A> A<HASHCODE> =end code =end pod
This would produce:
An ancient (but fast) hashing algorithm is used:
my $hash = 0; for $key.split("") -> $char { $hash *= 33; $hash += $char.ord; } return $hash;
Alternatively, if the
=alias directive is not followed by an opening bracket, it must be followed by a declarator (such as
sub, etc.) The declared object then becomes the (read-only) return value of the alias. For example:
=alias CLASSNAME class Database::Handle { =alias ATTR has IO $!handle; =alias OPEN my Bool method open ($filename?) {...} =alias DEFNAME constant Str DEFAULT_FILENAME = 'db.log'; =for para Note that the A<OPEN.name> method of class A<CLASSNAME> stores the resulting low-level database handle in its private A<ATTR.name> attribute. By default, handles are opened to the file "A<DEFNAME>". }
This would produce:
Note that the
open method of class
Database::Handle stores the resulting low-level database handle in its private
$!handle attribute. By default, handles are opened to the file "
Pod is just a collection of specialized forms of Perl 6 comment. Every Perl 6 implementation must provide a special command-line flag that locates, parses, and processes Pod to produce documentation. That flag is --doc.
Hence, to read Pod documentation you would type things like:
perl --doc perlrun perl --doc DBI::DBD::Metadata perl --doc ./lib/My/Module.pm
When the Perl 6 interpreter is run in this mode, it sets the compiler hint
$?DOC to true. If the --doc flag is given a value, that value (with a
but true added) is placed in
$?DOC. This can be used to specify, for example, the output format desired:
perl --doc=HTML perldelta > perldelta.html
Under --doc, the interpreter runs in a special mode, parsing the source code (including the Pod, as it always does) during compilation and building the program's syntax tree. However, during parsing and initialization under --doc, the interpreter executes any
CHECK, and
INIT blocks (and equivalents, such as
use statements and subroutine declarations) that are preceded by the special prefix:
When the --doc is not specified on the commandline, blocks and statements that are preceded by the
DOC prefix are not executed at all.
By default, once the
DOC INIT phase is complete, the interpreter then calls a special default
DOC INIT block that walks the AST and generates the documentation, guided by the content of the
$?DOC hint, the
$=pod tree, and any
DOC blocks that have loaded Pod-related handler code.
Because the conversion of documentation is just a variation on the standard Perl 6 compilation process, the processing of any given file of Pod can be modified from within that file itself by the appropriate insertion of
DOC blocks. For example:
DOC use Pod::Markovian;
DOC BEGIN { use Pod::Literate; if ($?DOC ~~ /short/) { literate_sequence(< NAME AUTHOR SYNOPSIS COPYRIGHT WARRANTY DESCRIPTION INTERFACE DIAGNOSTICS >); } else { literate_sequence(:default); }
You can even replace the standard Pod processor with your own, so long as you remember to exit before the default
DOC INIT can run:
DOC INIT { use My::Pod::To::Text; pod_to_text( $=pod ); exit(0); }
The idea is that developers will be able to add their own documentation mechanisms simply by loading a module (via a
DOC use) to augment or override the default documentation behaviour. Such mechanisms can then be built using code written in standard Perl 6 that accesses
$=pod, as well as using the
.WHY and
.WHEREFORE introspection methods of any constructs that have attached Pod blocks.
Note also that this mechanism means that, on many systems, you can create a self-converting documentation file like so:
#! /usr/bin/perl6 --doc =begin pod =head1 A document that can write itself Executing this document from the commandline will automatically convert it to a readable text representation. =head2 Et cetera ... =end pod
|Start of an explicitly terminated block
|Lexical modifications to a block or formatting code
|Encoding scheme for subsequent text
|Explicit termination of a C<=begin> block
|Start of an implicitly (blank-line) terminated block
|Define a Pod macro
|Block typename
|Verbatim pre-formatted sample source code
|Content to be ignored by all renderers
|Definition of a term
|I<N>th-level heading
|Pre-formatted sample input
|First-level list item
|I<N>th-level list item
|Nest block contents within the current context
|Pre-formatted sample output
|Ordinary paragraph
|No "ambient" blocks inside
|Simple rectangular table
|Perl 6 data section
|No ambient blocks after this point
|Semantic blocks (C<=SYNOPSIS>, C<=BUGS>, etc.)
|User-defined block
|Formatting code Specifies
|C<A<...>> Replaced by contents of specified macro/object
|C<B<...>> Basis/focus of sentence (typically rendered bold)
|C<C<...>> Code (typically rendered fixed-width)
|C<D<...|...;...>> Definition (C<D<R<defined term>|R<synonym>;R<synonym>;...>>)
|C<E<...;...>> Entity names or numeric codepoints (C<E<R<entity1>;R<entity2>;...>>)
|C<I<...>> Important (typically rendered in italics)
|C<K<...>> Keyboard input (typically rendered fixed-width)
|C<L<...|...>> Link (C<L<R<display text>|R<destination URI>>>)
|C<M<...:...>> Module-defined code (C<M<R<scheme>:R<contents>>>)
|C<N<...>> Note (not rendered inline)
|C<P<...>> Placement link
|C<V<R><...>> Replaceable component or metasyntax
|C<S<...>> Space characters to be preserved
|C<T<...>> Terminal output (typically rendered fixed-width)
|C<U<...>> Unusual (typically rendered with underlining)
|C<V<V><...>> Verbatim (internal formatting codes ignored)
|C<X<...|..,..;...>> Index entry (C<X<R<display text>|R<entry>,R<subentry>;...>>)
|C<> Zero-width comment (contents never rendered)
Damian Conway <
[email protected]>


text:
Bridging the Gap Between Digital, Mobile and In-Store Experiences
This post originally appeared in our January '13 issue of "Live Report from the Future of Marketing," our monthly Post-Advertising newsletter. Subscribe for free here.
In the mid-'90s I was a teenager just entering high school. I loved computers, and the emergence of the Internet simply astounded me. I would spend hours on Prodigy, then AOL, chatting away and browsing every corner of the emerging web.
My big prediction was that there would come a day when we'd go to the mall online. We'd walk a character through the mall, entering shops where we could buy real items. Turns out it wasn't that bold a prediction, as I wasn't far off.
Today e-commerce has become a formidable challenger to brick-and-mortar stores, which rely on customers getting dressed (it's harder than you think), leaving their houses, driving to the store, finding parking and dealing with store employees who are too eager or absent to be of any assistance, only to realize the item is out of stock. But in the early days of the web, it wasn't clear that anyone would ever buy anything online. Who would you be buying from? How would you pay, and would it be safe? Did you need that item now, or could you wait six to 10 days for shipping? Why buy online when you could get everything at the mall (or so you thought) in one day? What if the items didn't fit? What if they never arrived?


text:
More excellent info from Barb Bowman about the new Windows 7 Internet media streaming feature:
The more I use WMP secure Internet streaming, the more impressed I become. The empowering technology is obviously very slick and smart. I discovered that the bit rate for streaming is adaptive and adjusts to your connection speed. While I don't have any technical details or white papers that explain the inner workings, I sense that on the host end, the connection type and speed is auto detected and the bit rate set accordingly.
So far, I've determined that on a host that is hard wired to my home router, the bit rate is 2000 and if the host is wireless 802.11n, the rate is 1200. Note that I am streaming no DRM'd HD content recorded using a Digital Cable Tuner and a CableCard. The client was my ASUS EeePC netbook, connected via 802.11n wireless. This means that most broadband users should have a wonderful experience. Comcast's flagship speed is 12/2, so certainly the experience will be a good one for Comcast customers, especially considering that most will have standard definition Media Center recordings. (Disclaimer, I work for Comcast and this does not in any way represent any official statement or endorsement.). Given my own experience with these HD recordings, anyone streaming HD recordings or HD Videos will have a great experience as well. I'm not easily impressed, but this stuff is amazing.
More at the source....


text:
Photo: Rylan Schoen, Athlete: Adam Roberts, Location: North cascades Date: 03/11/14
Athlete: Adam Roberts, Location: Mt Baker
Throwing up a large plume of powder, this skier is about to get a highly sought after "faceshot"
I love to capture textures that are too quick to see with the naked eye. Buried in fresh snow, the skier is about to explode out of the "white room"
Backcountry skiing in the Pacific Northwest. Here a skier sets a track toward the next objective.
North Cascades Backcountry skier takes some final turns for the day on the way home. Storm is brewing in, as forecast by the cloud cap on Mt. Baker in the background.
A backcountry skier launches off a 30 foot overhanging cornice. Cornices like these build up throughout the winter from wind whipping over the edge.
All photos copyright of photographer listed and may not be downloaded or reproduced without permission of photographer.