Skip to content

Latest commit

 

History

History
224 lines (161 loc) · 6.25 KB

Specification.md

File metadata and controls

224 lines (161 loc) · 6.25 KB
Raw

[x]it! Specification

Version 1.1

[x]it! is a plain-text file format for todos and check lists.

The name is supposed to be pronounced like the English word “exit”.

License

Per Creative Commons CC0 1.0 Universal, to the extent possible under law, the editors have waived all copyright and related or neighbouring rights to this work. In addition, as of March 2022, the editors have made this specification available under the Open Web Foundation Agreement 1.0.

Preface

The keywords “MUST”, “MUST NOT”, “SHOULD”, “SHOULD NOT”, and “MAY” in this document are to be interpreted as described in RFC 2119.

File Format

The file extension SHOULD be .xit.

The file encoding MUST be UTF-8.

Newlines MUST be encoded with either \n or \r\n. The newline style SHOULD be consistent within a file.

There SHOULD be a newline at the end of the file.

Item

An item is an entry in the file.

It MUST start at the beginning of a line with a checkbox. There MAY follow a priority and/or a description, which MUST appear in this order.

Checkbox, priority, and description MUST be separated by one space character ( ) from each other. (Additional space characters MAY appear.)

The item MUST NOT contain any blank lines.

Checkbox

A checkbox represents the status of the item.

It MUST be a sequence of 3 characters, where the first character MUST be an opening square bracket ([), and the third character MUST be a closing square bracket (]).

The second character determines the status of the item. It MUST be either of:

  •  (space) for open
  • x (the letter x) for checked
  • @ (at) for ongoing
  • ~ (tilde) for obsolete
  • ? (question mark) for in question

Example

[ ] This is an open item
[x] This is a checked item
[@] This is an ongoing item
[~] This is an obsolete item
[?] This is an item in question

Priority

The priority indicates how important the item is.

It MUST contain any number of exclamation marks (!) and dots (.). The dots MUST appear either before or after the exclamation mark(s). (So they can neither appear in between nor on both sides.)

The number of exclamation marks MUST be interpreted as equivalent to the level of importance of the item.

The dots are only for visual padding and MUST NOT be attributed any meaning to.

Example

[ ] ! This is important
[ ] !! This is more important

[ ] ..! This is important
[ ] !!. This is more important

Description

The description is user-provided text that gives meaning to the item.

It MUST start on the same line that the item starts on. It MAY be continued on the subsequent line(s), where each of them MUST be indented (preceded) by a sequence of four space characters ( ).

The description MAY contain any number of tags, and/or one due date. (Any additional due dates MUST be disregarded.)

Example

[ ] This description is one line
[ ] This description continues ...
    ... on the next line

Due Date

A due date determines how timely an item is.

It MUST be commenced with the character sequence -> (a hypen, a greater-than sign, and a space), and then followed by a date pattern.

The date pattern MUST be either of:

  • yyyy-mm-dd or yyyy/mm/dd to reference a calendar day
  • yyyy-mm or yyyy/mm to reference a month period
  • yyyy to reference a year period
  • yyyy-Www or yyyy/Www to reference a week period
  • yyyy-Qq or yyyy/Qq to reference a quarter period

y MUST be a digit that denotes the year; m the month; d the day; w the week number (according to ISO8601); q the quarter number. W and Q MUST appear literally.

The periodic patterns MUST be treated as equivalent to the last calendar day within the respective time frame.

The due date value MUST be representable by the gregorian calendar.

Example

[ ] This shall be done until -> 2022-03-31
[ ] -> 2022-03 Do this throughout March
[ ] Do this -> 2022-Q2 within the second quarter

Tag

Tags are annotations for categorising or filtering the data.

A tag MUST consist of a tag name, which MUST be preceded by a single # character. The tag name MAY be followed by a = character and a tag value.

The tag name MUST only contain letters, digits, or the characters _ or -. It MUST be treated as case-insensitive.

The tag value MAY be surrounded by a pair of matching quotes, which MUST either be " (RECOMMENDED) or '.

  • If the tag value is quoted, it MAY contain any character except for the respective quote character itself, or a newline. In case no matching closing quote appears on the same line, the tag value MUST be treated as absent.
  • If the tag value is not quoted, it MUST only contain letters, digits, or the characters _ or -.

The tag value MUST be treated as case-sensitive.

An empty tag value (e.g. #tag= or #tag="") MUST be treated the same as an absent tag value (e.g. #tag).

Example

[ ] This item has a #tag
[ ] This #item has #multiple #tags!
[ ] Tags can #have=values
[ ] Values #can="be quoted"

Group

A group is any consecutive number of items (without blank line in between), that MAY be preceded by one title.

Example

[ ] This item and the next one ...
[ ] ... are grouped

[ ] This item is its own group

Title

The title is a single line of text that MUST NOT start with a blank character or the opening square bracket character [.

Example

My TODO list
[ ] Item 1
[ ] Item 2

Appendix

Glossary

  • Blank character: a character from the Unicode Space Separator category (Zs)
  • Blank line: a line that is either empty, or that exclusively consists of blank characters
  • Digit: 0, 1, 2, 3, 4, 5, 6, 7, 8, or 9
  • Letter: a character from the Unicode Letter category (L)
  • Newline: \n or \r\n
  • Punctuation: a character from the Unicode Punctuation category (P)

Changelog

Version 1.1

  • Add new checkbox status “in question”: [?]