This is a project that I decided to undertake one day and which is only semi-serious. It exists mostly due to both my recent curiosity with Parsing Expression Grammars, and a stubborn refusal to give up on a blatantly terrible idea. Oh, and a love for John Gruber's Markdown and the principles behind its design.


Sometimes, a simple message is not a sufficiently productive way of communicating with someone. After a small number of back and forth emails, someone will decide to pick up the phone or meet in person to have a face-to-face conversation. This way, the feedback loop is shorter and each question can be devised based on the previous answer received in order to exchange the necessary information between participants.

Face to face conversations are not always possible, however. And waiting for someone to become available for such a discussion can mean that the original reason for the discussions gets forgotten about. Sometimes one can end up trying to ask relevant questions in a message such as an email, by anticipating the answers the recipient might give and formulating a kind of if-else tree structure in the message. For example:

Hey Alice

Did you get the file server up and running yet? If so, do you know what port it's listening on? Or if not, do you know roughly when it'll be ready? And could you set it up to listen on port 4444?

Thanks, Bob

Here Bob provides two different further questions based on the anticipated answers to his original question. A single level of if-else branch is about as far as one can go before grammar starts to get in the way and the message becomes confusing:

Hey Alice

Are you in charge of setting up the new file server? If so, did you get it up and running yet? If you did, is there a password set up for it already? If there is, could you leave it with Chris on Tuesday, please. If there isn't a password, please could you leave it like that for the time being and I will set one. If the server isn't ready yet, please could you hand that job over to Dianne, assuming she isn't busy. If she is busy, please could give it to Ed instead. When you've handed that over, could you let me know: are we still waiting on that hard disk from the supplier? If we are, please could you give them a call and ask them what's taking so long. If we're not, let me know what the problem is. If you're not in charge of the file server, and it's Frank instead, tell him to pop in for a chat with me when he's around tomorrow. Or if it's George, and he's still on holiday, please could you take over. If he's not on holiday, have him contact me. Otherwise if it's neither of them, let me know who is in charge of the damn file server.

Thanks, Bob

The decision tree that this message describes looks like this:

In charge of file server?
  |-- YES 
  |    '-- Is it up and running yet?
  |         |-- YES
  |         |    '-- Is there a password?
  |         |         |-- YES 
  |         |         |    '-- Leave with Chris on Tues
  |         |         '-- NO
  |         |              '-- Leave as is, I will set
  |         '-- NO
  |              |-- Is Dianne busy?
  |              |    |-- YES
  |              |    |    '-- Hand file server to Ed
  |              |    '-- NO
  |              |         '-- Hand file server to Dianne
  |              '-- Waiting on hard disk?
  |                   |-- YES
  |                   |    '-- Ask what's taking so long
  |                   '-- NO
  |                        '-- Let me know what problem is
  '-- NO
       '-- Is Frank in charge?
            |-- YES
            |    '-- Tell him to pop in tomorrow
            '-- NO
                 '-- Is George in charge?
                      |-- YES
                      |    '-- Is he on holiday?
                      |         |-- YES
                      |         |    '-- You take over
                      |         '-- NO
                      |              '-- Have him contact me
                      '-- NO
                           '-- Tell me who's in charge

Which gets a little difficult to express in a plain text email, for example.

Hrbrt Format

I propose a file format to make this kind of multiple-choice message easier for the writer to express and easier for the recipient to understand. Introducing Hrbrt: Human-Readable BRanching Text.

The goals for Hrbrt are as follows:

  • It should be as easy to author as regular email - i.e. it should require nothing more than a plain text editor.
  • It should be possible to machine parse the format, so that its content can be read using a more sophisticated viewing tool.
  • It should, however, still be adequately readable in its raw text format, taking inspiration from Markdown's philosophy. Thus no special tools are required of the recipient.
  • It should be clear to the recipient how to respond to the file.
  • The recipient's response should also be machine-parsable so, that the sender too can view the response using a more sophisticated viewing tool.
  • The sender should be able to express a branching graph of multiple-choice questions.
  • The recipient should be able to follow the trail of relevant questions based on their answers.
  • The sender should be able to insert sequences of text and questions for each decision branch in the graph.
  • The recipient should be able to read all of the conversation branches if they wish.
  • The recipient should be able to go back and change their mind about their responses.
  • The recipient should be able add feedback to clarify their choices and provide additional information to the sender.


Below is an example of Hrbrt syntax, using the same message described earlier:

:: Hi Alice,

%% Please put X in each box as appropriate and leave additional 
%  comments on separate lines (without a : at the start).  You 
%  can follow "GO TO <section>" instructions by searching for 
%  "== <section>"using ctl+f, for example.

:: Who's in charge of setting up the file server?

:: [] Me        -- GO TO me.
:  [] Frank     -- Tell him to pop in to have a chat with me when he's 
:                   in tomorrow. GO TO end.
:  [] George    -- GO TO george 
:  [] Other     -- Let me know who's in charge of the damn file server. 
:                   GO TO end.

== Me ==
:: Did you get it up and running yet?
:: [] Yes it's up and running   -- GO TO server running.
:  [] No it's not ready yet     -- GO TO server not running.

== George ==

:: Is he on holiday?
:: [] Yes   -- Please could you take over from him. GO TO end.
:  [] No    -- Have him to contact me. GO TO end.

== Server Running ==

:: OK that's great! Thanks for getting that set up.
:: Is there a password?
:: [] Yes a password has been set   -- Leave it with Chris 
:                                       on Tuesday GO TO end.
:  [] No, no password is set        -- Leave it like that and 
:                                       I will set one. GO TO end.

== Server Not Running ==
:: Is Dianne busy?

:: [] Yes she's occupied    -- Hand over the file server job to Ed
:  [] No she's not busy     -- Hand over the file server job to Dianne

:: Are we still waiting on that hard disk from the supplier?
:: [] Yes, still waiting    -- Call them and ask what's taking so long. GO TO end.
:  [] Not waiting           -- Let me know what the problem is. GO TO end.

== End ==

:: Thanks,
:  Bob.

I will briefly describe the various components of the language.


Sections serve to split up the document and provide reference points to which the user can be directed as they traverse the document.

A section begins with a named heading, for example:

=== My Section ===

Text and Recipient's Feedback

Blocks of regular text can be added to the document by starting the first line of the block with a double colon, and each subsequent line with a single colon.

Lines without the preceding colons are assumed to be part of the recipient's feedback.

For example:

:: This is part of the 
:  document text that
:  the sender wrote

But this is the 
recipient's feedback


Instruction blocks are not presented to the user when parsed by a program such as a visual Hrbrt reader. They are intended for providing instructions to users reading the raw file text only. The first line of an instruction block starts with a double percent sign, and each subsequent line with a single percent sign.


%% Please fill in this document 
%  and send it back as soon as 
%  possible


Blocks of choices are used to present the user with options from which they can make a single selection. Users reading the raw Hrbrt text indicate their selection by writing something inside the box beside it, such as an X.

The first choice starts with a double colon, and each subsequent choice starts with a single colon. Each option then consists of a pair of square brackets [] followed by the option description.


:: [] Animal
:  [] Some kind
:      of Mineral
:  [] Vegetable

Choice Responses

Each choice may optionally be followed by response text. This is separated from the choice description by a pair of hyphens --. The response text gives feedback and further instructions to the recipient on selection of that option.

A choice response may optionally be followed by a go-to statement. This consists of the words GO TO in uppercase, followed by a section name. The go-to statement instructs the recipient or viewing tool as to which section to jump to next.


:: [] Animal    -- Good choice! GO TO my section
:  [] Mineral   -- OK. GO TO some section.
:  [] Vegetable -- Not bad, but I 
:                  think you could
:                  have chosen better.
:                  GO TO end


All lines in the document may optionally be prefixed with > markers, as would typically be added by an email client. This allows recipients to reply directly to a document sent by email and it still be parsable.

Parser Implementation and More Info

I have implemented a basic Hrbrt parser and viewer in Python, which can be found on Github here, along with usage instructions:

A more detailed description of the language can also be found there.


OK, so maybe people aren't really going to start sending flowcharts to each other in place of regular email. Hrbrt does have other potential uses, however, including:

  • Questionnaires
  • Knowledge bases
  • Troubleshooters
  • Videogame dialogue trees

It was a fun project. I may expand upon it sometime.