                             Quickstart for Tofu
                  Plain (stupid) text-based todo(s) manager



This document aims to give you a concrete approach of tofu, once you installed
this one (see the README file, which is related to this subject). At the end of
it, you should have a good overview of the concepts of the software.


    Table of contents:

        1) Make a playground
        2) The wonderful world of selectors
        3) Yes, the selectors are wonderful, but not equal
        4) Back to the real life


1) Make a playground

    The first thing you should do in order to test tofu, is to use the
    'playground.pl' script, which is at the root of the sources (or should be
    in the "doc/" directory attached to your package):

        $ perl playground.pl -tutorial

    This will initialize your ~/.tofu directory and create inside a 'play' named
    10 tasks-filled stack. For the rest of this tutorial, we will use this name,
    but you can choose another one if this one is not convenient for you, you
    just have to add it on the command line. In all of the cases, be careful to
    not use the name of a stack which already exists because this one will be
    ENTIRELY REMOVED.

    Note: as playground.pl is primarily a development tool, it can also generate
          random-filled, stacks. Don't use this mode if you want to be sure that
          the results of the commands shown here match with the content of the
          stack (playground.pl should specify "tutorial mode" during the
          generation).
    
    Once you created the stack, we will first ensure that all is right with it:

        $ tofu /

    Tofu will the print a report about the list of the present stacks. Our stack
    should be described as follow:

       Stack name               |  Cur./Tot.       |  Composition (HWC)
       -------------------------+------------------+--------------------------
       play                     |  10/10           |  2, 3, 5 


2) The wonderful world of selectors

    The selectors allow you to define a certain list of tasks. In this section
    we will just take a look on each available one. Let's begin with a command
    you will use very often:

        $ tofu play

    As you can see, it selects and prints a list of all the tasks in the stack,
    sorted by decreasing order of priority first, then by increasing order of
    id. Print such a list is what tofu does by default. Each task is listed
    under this form:

        9        (COOL)     [one]
                 Have a lot of fun in the playground

    The first number on the left of the first line is the id of the task
    (which is hence a mere number). On the right of this one are given the
    priority of the task (nested in parenthesis) and the markers set on it
    (nested in brackets and separated with periods). On the second line is
    reported the title of the task.

    We will play with each of these elements. Let's start with the id, and
    enter this:

        $ tofu play 2 10

    Wow! tofu printed only the tasks 2 and 10! We can also easily reverse this
    selection by making negative the id of tasks, which means "all of the
    tasks but not these ones":

        $ tofu play -2 -10

    As expected we get all of the tasks in the stack except the 2 and the 10
    ones. Good, now let's play with priorities:

        $ tofu play pr=cool,hot

    No suprise, here we get just the tasks with a COOL or a HOT level of
    priority. Let's continue and try this:

        $ tofu play pr=5

    Hey! we get the same thing as above, what the big deal? It's quite simple,
    you can specify priorities to match in the alphabetic or in the numerical
    mode. Numerical mode works like the octal mode for file permissions: cool
    is equal to 1, warm to 2 and hot to 4. Hence, to have the cool and the hot
    tasks we do 4+1 = 5. Still here? Well, let's have a glance on the markers:

        $ tofu play wi=one

    As expected, We get only the tasks bearing the "one" marker. So, let's try
    something less trivial:

        $ tofu play wi=two,one

    Now we get the tasks bearing the marker "one", or the "two" one, or both.
    Great, but what about matching only the tasks that bears both markers? No
    problem, we have another selector to do that:

        $ tofu play wil=two,one

    We have even two selectors that match the tasks that don't bear the given
    markers and work according to the same rules. Try the two examples above,
    replacing "wi=" with "wo=" and "wil=" with "wol=".

    There is also a very handful selector on the stacks that become a little bit
    too big:

        $ tofu max=3

    As you can see, here are printed only the three first tasks in the stack. If
    you want to retrieve just the very first task in the stack, you can also use
    the "top" selector, which has moreover the advantage to be arbitrary
    redefinable by the "crown" action, so that you can easy access trough it to
    the task you are currently working on (see the next section):

        $ tofu top

    All of the selectors exposed above aren't very difficult to apprehend. But
    one's still missing, which is a little more curious but essential:

        $ tofu play next

    Did you unterstand what happened? Tofu simply added a new task (the next
    which had to come) in the stack. That's the way used by tofu to create new
    tasks. Doing this, you will althought certainly get a warning from tofu,
    because by default it doesn't let you add empty tasks (you will see it's a
    useful behaviour, but you can disabled it in the .tofurc file). Answer "no"
    to the asken question (or "yes", here it doesn't matter).

    The problem with this way is that you don't know the id of the task you
    added. So, if you want to retrieve immediately after its creation you have
    to list the whole stack to get its id. Happily, fix that is precisely
    the purpose of the next selector to introduce:

        $ tofu play last

    As you can see, "last" just refer to the latest task added to the stack. It
    will certainly be useful in the (very common) case where you forget
    something in the definition of a new task.

3) Yes, the selectors are wonderful, but not equal

    In the previous section, we had an overview of the available selectors. Of
    course these ones can be mixed (only one occurence of each on the command
    line -- the last -- is kept, though) to obtain elaborated selections. Let's
    try:

        $ tofu play wi=two,one wil=two,one

    As you can see, we get the same thing as if we only used the "wil="
    selector. That's a rule we have to keep in mind: the kept selection
    is always the more restrictive one. Let's continue:

        $ tofu play wi=one wo=one

    Here, we are answered that there is no task in the selection, why?
    Reflect... this is the same principle of above: "wo=" exclude tasks, hence
    it's a restrictive marker, hence it's stronger than "wi=" (or even than
    "wil="). Now what's about:

        $ tofu play wo=one wol=one,two

    Same thing again, "wo=" has a more restrictive scope, so it's applied
    despite of "wol=". Look if you have understood, consider that and
    determine before executing this if all the tasks will be diplayed:

        $ tofu play pr=7 wo=one,two

    The answer is "no", because here "pr=" is less restrictive than "wo=".
    But... wait a minute, what's happen in that case:

        $ tofu play pr=1 wi=one,two

    Always the same thing, the more restrictive selection is kept: we haven't
    got the cool tasks that doesn't bear the "one" or the "two"  markers nor
    the tasks that aren't cool. All right! in fact it's very trivial to
    understand, come on for a more little tricky example, guess what will
    happen:

        $ tofu play pr=7 1 2 3

    "Huh? it's not consistent here, is it?" You're absolutly right, if our
    sweet rule was strictly applied, we should get only the tasks 1, 2, and 3.
    But we don't, because you get here the exception which confirms the rule:
    a task explicitely called (ie. by its id or selector as "last") in the
    selection is always kept in it, unless it is explicitely deselected on the
    same line (which is stupid). It allows you to insert exceptions in the
    selection, for example:

        $ tofu play 9 pr=2

    Here you ask to tofu to select all of the warm tasks, and the task 9
    whatever its priority. You will certainly find it useful in the future. Note
    althougt that our "The more restrictive win" rule is still apply when the
    selection in entirely made with explicit selectors:

        $ tofu play 9 8

    Or with absolutely limited with the "max=" defined limit:

        $ tofu play 9 10 5 max=2

    In this latest case, tofu will just try to fill the selection with
    explicitely called tasks as much as it can.

        
4) Back to the real life
    
    We saw in the previous section how to get a selection of tasks. Here we
    will see what we can do with it. If you understood well the selectors
    topic, you shouldn't have problem to understand the actions one. That's
    why we won't detail each one. To have an overview, of these ones, just
    execute tofu without argument and look at the actions section:

        $ tofu

    Quite trivial, isn't it? so, in the rest of this section we will just
    expose some common and useful combinaisons of actions and selectors.

    Actions are executed each one after the other, in the order you give them
    on the command-line (but only one occurrence of it -- the last -- is kept).
    That is the only rule to keep about the action. So, let's play! :)

    First, see how to add a plenty defined new task in your stack:

        $ tofu play stamp=one,four hset next edit

    Here, we rename the "one" marker as "five", then print our new stack:

        $ tofu play erase=one stamp=five print wi=one

    Now, let's see how to easily have an overview of bugs (task stamped as
    "bug") to fix:

        $ tofu play wi=bug read

    Bellow, we set to hot all of the warm tasks that bear the "next" marker
    (this is a convenient way to preselect the tasks that will became hot when
    the current hot selection will be empty):

        $ tofu play wi=next erase=next hset pr=3

    With this command, we can interactively strip the ten oldest cool tasks,
    removing those that refer to a deprecated state of our project, then
    printing the list of those that were kept:

        $ tofu play delete pr=cool max=10 print

    Here is a good way to add a new task (for example a little idea to put in a
    corner), keeping the last task you are working on (for example, the precise
    specification of a huge project) on the top of the stack:

        $ tofu play last crown next feed="A cute little idea" 
    
    Now, let's see how to split the task 25 (particulary effiscient if your editor
    support the "global-edition" option but you can do it with mouse selection, see
    the CONFIGURATION section of tofu.1 for further informations).

        $ tofu play 25 next

    This is another example, where you can see how to reset the characteristics of
    the selected tasks (which here bear the "todo" marker) before moving them in
    another stack.

        $ tofu play wi=todo wset clean stamp=six,seven move=another

    Other interesting issue, if you plan to use tofu to manage the public
    ToDo/Roadmap of your projects, you can use "printf" to generate an HTML digest of
    your stack:

        $ echo <ul>
        $ tofu play printf='\0%4 <li class="%p"><b>%i</b>%t</li>\n'
        $ echo </ul>

    Last, we give bellow a tip to reset your stack if you find the ids of their tasks
    too much long to be easily manipulated.

        $ mkdir ~/.tofu/tmp             # first, you create an empty "tmp" stack;
        $ tofu play move=tmp            # then you transfer all of your tasks into it;
        $ rm -fr ~/.tofu/play           # you remove your now empty source stack;
        $ mv  ~/.tofu/tmp ~/.tofu/play  # you finally give to "tmp" the name of your
                                        # source stack.

    In this way, your tasks will be renamed from "1" to the total number of tasks.


We reached the end of this quickstart. Theorically (in all cases I hope), you should
now be able to use tofu effisciently. Further informations are waiting for you in the
tofu.1 manual, if you want to complete what you get here.

Have thousands of gorgeous tofu meals! :^)
