The pick line works like drawing numbers in a lottery. That means it randomly picks one line out of a number of lines. It is equally likely for each line to be picked.
Pick affects all kinds of lines, such as paragraphs, links, shuffle lines etc.
The randomize line is the pick line's older brother. It can do everything the pick line can. But the pick line makes it easier to achieve the kind of randomization that works like a lottery.
A simple pick line starts with a :PICK: tag followed by a number. The number points out from how many lines below the pick line can choose one.
"We all should be a little more like pizza," Francesca declares solemnly.
"Why is that?"
"Because pizza is social. It advocates sharing and brings people together."
"Because pizza cares. It's there for you even when the world has turned its back on you."
"Because pizza is tolerant. It does not judge you for your decisions on the extras."
In this example a pick line is defined with a single number: 3. Effectively, that means: "Pick 1 of the 3 following lines."
Practice tip: Change the pick line to :PICK: 4, write your own manifesto below, hit update and see what happens.
Sometimes you want to pick a group of lines rather than a single line. In these cases you can specify the number of lines in each group.
"What will you have?" Alfonso asks.
:PICK: 2 2 1
"I'll have a pizza aglio, because it makes me more attractive."
:LINK: Alfonso bursts out laughing.|vampire|append,sticky
"How about the pizza piccante? I once saw someone burst into tears, because it was so delicious."
:LINK: Alfonso winks at you giggling.|burning desire|append,sticky
"Today I'd like to try something exotic: the pizza salami."
"Not if your crush is a vampire!"
:CARD: burning desire
"Or maybe it was because they felt a burning desire for more..."
Here, the pick line is defined with three numbers: 2 2 1. Each number represents a group of lines:
- Lines 4 and 5 are the first group and represented by the first 2.
- Lines 6 and 7 are the second group and represented by the second 2.
- Line 8 is the third group and represented by the 1.
Pick chooses one group out of the three with equal probability and displays its lines.
Practice tip: Remember the example in the first section? Like the one in this section it can be written as groups: :PICK: 1 1 1. However, if each group has only one line, you can use the shorter version above.
Pick something or nothing
There might be situations where you want 'nothing' to be a valid option to pick. You achieve that by defining a group with 0 lines.
You order: "The same as usual, please."
:PICK: 1 1 0
"Your usual is our today's special. You get an extra stamp on your coupon card," says Francesca.
"Here's one that didn't get picked up. If you want it, I'll heat it up and sell it to you for half the price," Francesca offers.
You sit down and start munching: "That's good pizza right there."
In this pick line three groups are defined. The first two groups have one line each.
The third group as zero lines. Consider it an empty group. Consequently, when it gets picked no text gets displayed.
Practice tip: Hit update a few times to see how this pick line sometimes displays text and sometimes it doesn't.
Return to a pick line
In non-linear texts it is likely for readers to make decisions that will lead them back to a card they visited previously.
If a pick line happens to be inside such a card, it will choose again.
Keep or lose a chosen line
Imagine the following situation: Numbers are drawn for a lottery. Each number is equally likely to come up. Once a number has been drawn it is no longer in the pool, so it can not be drawn again.
A pick line works in the same way. If it chooses more than once, previously chosen options are no longer available.
In order to change this behavior, the pick line knows a special keyword: keep.
"I'm here to pick up my order," you let Alfonso know.
"Here you go." He hands over the delicious pie. "And be sure to get something from the cookie jar. But one piece only."
:PICK: 1 1 1 1|keep
A chocolate chip cookie. Great! You save it for later.
A milk cookie just like grandma used to make. Nice.
Yes! It's one of those caramel cookies. You sink your teeth into the delicious dough right on the spot.
It's that cookie with white nougat sprinkles you don't like. You put it back.
:LINK: Fast forward to the next day|cookie jar
There are four cookies left in Alfonso's cookie jar. You pick one. If it's that cookie you don't like, you put it back. As you return, the cookies vanish until, ultimately, there's only the one left that you always put back.
In this example the pick line has four groups defined, each has one line. The first three groups are discarded once they have been picked. They cannot be picked again.
Group 4, on the other hand, has the keep keyword. This line will always be available when the pick line chooses. Once the other options have been picked, this remains the only option. It will come up each time.
Workflow tip: Groups 1, 2, and 3 also have a keyword, but it is implicit: lose. Hence, you could write the pick line above like this :PICK: 1|lose 1|lose 1|lose 1|keep and it would work the same way. Use this option to make your source text easier to understand.
Workflow tip: In this example, the keep keyword is used with a group notation. However, it can also be used in the line notation like in the first section above: :PICK: 3|keep. In that case the keep keyword is applied to each line.
Restart after exhausting a choice
If no group has the keep keyword, each group can only be chosen once. Eventually, that will lead to a situation where all groups have been picked and none are left.
In that case the pick line simply starts over. All options become available again.
"I've put tomato sauce, salami and cheese on your pizza. :LINK:What else do you want?"|what-else|append:: Francesca asks.
:CARD: what else
:LINK: "More salami, please."|what else|append,sticky
:LINK: "Some peppers, please."|what else|append,sticky
:LINK: "A handful of olives, please."|what else|append,sticky
When you click on the links the pick line can choose from you will encounter all three in random order. After each link has been displayed once, they all become available again.
Stop after exhausting a choice
In some situations it might not make any sense to start over when all options have been chosen once. Rather, something should suggest that there are no more options left.
For that you can define a group in your pick line that has a special keyword: after.
"I've put tomato sauce, salami and cheese on your pizza. :LINK:What else do you want?|what else|append::" Alfonso asks.
:CARD: what else
:PICK: 1 1 1 2|after
:LINK: "More salami, please."|what else|append,sticky
:LINK: "This pizza could really use more salami."|what else|append,sticky
:LINK: "I got a fever and the only prescription is more salami."|what else|append,sticky
"I think that's enough salami now," Alfonso says firmly.
:LINK: "No, I'd really like some extra salami, please."|what else|append,sticky
In this example you can ask for more salami in three different ways. Once you have clicked all three there are no further options. Instead, Alfonso insists that you've had enough extra salami.
This pick line is defined with four groups. The first three are the actual choices. Each gets discarded after being picked once. Consequently, after picking three times, there are no choices left.
The fourth group is different: It has the after keyword. It does not get picked like the first three groups. But as soon as the first three groups are discarded this group gets displayed each time.
Workflow tip: If the after group has 0 lines, pick will not display anything after it has run out of options.