!Meup.org!

If you never encountered these, you may throw the first stone.

• Ever started a project, left it aside and took it again weeks/month/years later without understandig what you did?
• Ever managed a big project on your one, the kind that involves a hundred pages of LaTeX and/or thousands of lines of code?
• Ever wondered where the hell that awesome info you found on the net was?

These are problems I have faced. I now do keep a track of the links I found using emacs'org-mode but the files where I put these where basically a mess. Furthermore, I didn't have the courage, when writing some file, to go to the org-one, write what I had to do, put a link to the file I was working on, go back to the file I was working on. Besides, the order I tried to put in my tasks by classifying them using headings and such was highly unstable: what I had to do was fixed but how I want to tackle it is not. None of these problems is a big deal but it is the kind of tiny things which get in the way and become even more annoying as they add up.

Meup.org is the solution I came up with. It is a sort of standard in the way I "work"¹ and it is based on three things.

• A simple way to document what I do and what is left to do intended to be as little cumbersome as possible; which implies having tools to automate annoying tasks.
• Having a schedule/subdivision of my tasks as flexible as possible; which also implies having tools to automate the update.
• A good software to manage todo lists and documentation with hyperlinks and that is good to take quick notes in plain-text. I use emacs'org-mode; I heard vimwiki is a nice substitute if you are that kind of person. I threw markdown in the mix because, well, why not?

To solve these problems, I came up with meuporg, aka !Meup.org!, aka !M!. While the choice of software to manage todo lists is left to you, meuporg is the software to find what's left and display it nicely.

It is a set of automatic tools to extract items from the content of any text files you want and which sorts and inserts them in your todo list regardless of the format you use².

It is assumed you have a unique file for each project at the root of its directory tree in which you will put your todo lists, knowledge base, etc. This file is called the main file. Personnaly, I now go back to the main file of my projects at least every 10-15min when I am working: it helps me know where I am going and I update it very regularly because of that³. Meuporg updates this file automatically by inserting links to the very lines I have to modify/where I have to write functions/whatever and putting these links in the relevant part of the main file.

A file like this, where everything in underlined blue is a clickable link to a task you need to do can be generated in no-time.

How can this be? you ask. Very simply, I shall answer. Right below, you will find instructions explaining how to install meuporg. Then, you will have more explanations about how it works and how it is intended to be used.

If you don't work with plain-text files; that is if you work with an office suite such that libreoffice.org, microsoft office or whatever, then no. If your projects are not scattered on many files and are of very small size, then probably not.

If you work on projects that are spread throughout several weeks/month/years due to their sizes or the amount of time you can spend on them and/or if the said projects consist in editing text files[],fn:8 then yes, you might want to give meup.org a try!

Just go here, download the archive, uncompress it and run the ./install.sh script (tested on ubuntu and mac OS). Advices are given: you might want to add this alias to your .bashrc

alias meuporg="python2.7 '$BASE_DIR'"'

(*/$BASE_DIR/ will be replaced by the value you should put when running the script) and, if you are wise enough to use emacs, adding this to your .emacs would be a good idea

(load "~/.emacs.d/meuporg.el")

(the meuporg.el file is automatically moved in your .emacs.d folder during installation).

Run the following command to "activate" your bash alias.

you@yourcomputer~$ . .bashrc

The main feature of meuporg is its ability to keep track of what is left to do from the content of your text files and put it in your todo list automatically. The principle is very simple: all you have to do is leave some particular snippets of text anywhere and meuporg will find them, sort them and add them to a file with links pointing to them.

The snippets of text you must put in your files ar called items. An item is something like the content of the comment at the beginning of the loop in this hypothetic file src/myfunction.c.

int foo(unsigned int bar)
{
        while (fuzzy_condition(bar))
                // !CHECK! The loop condition in foo may not work if
                // ! bar < 10.
        {
                process_bar();
        }
        return -4;
}

An item always has the following structure.

• It always starts with a word enclosed in exclamation marks; this word is the name of the item. Only numbers and letters are allowed, so no space, no underscores, etc.
• An item can be "in-code", in which case it contains no other information than its name because the data surrounding it is sufficient.⁴ It is the case if there is at least one alpha-numeric character on the same line before it.
• … Or it can have a description. The description of an item is what follows it on the same line. If you need more than one line, just start the next one with an exclamation mark.
• An item is also defined by its location, i.e. the file it is in an its line number. However, this is taken care of automatically.

In the example above, the item has these properties:

• name: CHECK
• description: "The loop condition in foo may not work if some bar == 0".
• location: ./src/myfunction.c, line 5.

The names of the items you can use are limitless: what defines and item is that its name is enclosed between exclamation marks, nothing else. Thus, if you want to have items called "ImThinkingOfDoingThatButPerhapsItsNotSuchABrightIdea1644934", meuporg can deal with it.

However, I suggest you use the following items:

• todo: When you need to start a new task: function to write, LaTeX table to insert, etc.
• continue: When you already started something but need to continue it.
• improve: When something is finished but could be improved.
• check: When something should work as is but could use a verification.
• fixme: When something does not work or is wrong.

I also use a specific item when I write LaTeX code called "FIXREF". I leave inside the text — i.e. it is not in a comment — as its context is all the information I need. This allows me to separate them from the other items in the main file (see file update).

One of the main features of meuporg is its ability to insert the items it found in a file: not only will they all be in the same place, you can also organize them easily in an arbitrarily complex way! See this page for (a lot) more details.

Meuporg can also be used from the command line. A description of its use is easily obtained by running it without any argument (or with "-h"), but more details are given on this page.

For those of you who use emacs⁵, and in particular org-mode, a minor-mode packed with functionnalities to easily insert items, fontify them, list them, interact with the main file and what not is included. More info here.