├── README.md └── Specification.md /README.md: -------------------------------------------------------------------------------- 1 |

2 | [x]it! 3 |

4 | 5 | # [x]it! 6 | 7 | A plain-text file format for todos and check lists. 8 | 9 | - 👉 [**Learn how [x]it! works**](https://xit.jotaen.net) 10 | - 💡 [Read the file specification](Specification.md) 11 | - 💬 [Discuss ideas and questions](https://github.com/jotaen/xit/discussions) 12 | - 🛠 [Share an [x]it! tool you made](https://github.com/jotaen/xit/discussions/categories/show-tell) 13 | -------------------------------------------------------------------------------- /Specification.md: -------------------------------------------------------------------------------- 1 | # [x]it! Specification 2 | 3 | **Version 1.1** 4 | 5 | [x]it! is a plain-text file format for todos and check lists. 6 | 7 | The name is supposed to be pronounced like the English word “exit”. 8 | 9 | ## License 10 | 11 | Per [Creative Commons CC0 1.0 Universal](http://creativecommons.org/publicdomain/zero/1.0/), 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](https://www.openwebfoundation.org/the-agreements/the-owf-1-0-agreements-granted-claims/owfa-1-0). 12 | 13 | ## Preface 14 | 15 | The keywords “MUST”, “MUST NOT”, “SHOULD”, “SHOULD NOT”, and “MAY” 16 | in this document are to be interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119). 17 | 18 | ## File Format 19 | 20 | The file extension SHOULD be `.xit`. 21 | 22 | The file encoding MUST be UTF-8. 23 | 24 | Newlines MUST be encoded with either `\n` or `\r\n`. 25 | The newline style SHOULD be consistent within a file. 26 | 27 | There SHOULD be a newline at the end of the file. 28 | 29 | ### Item 30 | 31 | An *item* is an entry in the file. 32 | 33 | It MUST start at the beginning of a line with a *checkbox*. 34 | There MAY follow a *priority* and/or a *description*, 35 | which MUST appear in this order. 36 | 37 | *Checkbox*, *priority*, and *description* MUST be separated by one space character (` `) from each other. 38 | (Additional space characters MAY appear.) 39 | 40 | The *item* MUST NOT contain any blank lines. 41 | 42 | ### Checkbox 43 | 44 | A *checkbox* represents the *status* of the *item*. 45 | 46 | It MUST be a sequence of 3 characters, 47 | where the first character MUST be an opening square bracket (`[`), 48 | and the third character MUST be a closing square bracket (`]`). 49 | 50 | The second character determines the *status* of the *item*. 51 | It MUST be either of: 52 | 53 | - ` ` (space) for *open* 54 | - `x` (the letter x) for *checked* 55 | - `@` (at) for *ongoing* 56 | - `~` (tilde) for *obsolete* 57 | - `?` (question mark) for *in question* 58 | 59 | > #### Example 60 | > 61 | > ``` 62 | > [ ] This is an open item 63 | > [x] This is a checked item 64 | > [@] This is an ongoing item 65 | > [~] This is an obsolete item 66 | > [?] This is an item in question 67 | > ``` 68 | 69 | ### Priority 70 | 71 | The *priority* indicates how important the *item* is. 72 | 73 | It MUST contain any number of exclamation marks (`!`) and dots (`.`). 74 | The dots MUST appear either before or after the exclamation mark(s). 75 | (So they can neither appear in between nor on both sides.) 76 | 77 | The number of exclamation marks MUST be interpreted as equivalent to the level of importance of the *item*. 78 | 79 | The dots are only for visual padding and MUST NOT be attributed any meaning to. 80 | 81 | > #### Example 82 | > 83 | > ``` 84 | > [ ] ! This is important 85 | > [ ] !! This is more important 86 | > 87 | > [ ] ..! This is important 88 | > [ ] !!. This is more important 89 | > ``` 90 | 91 | ### Description 92 | 93 | The *description* is user-provided text that gives meaning to the *item*. 94 | 95 | It MUST start on the same line that the *item* starts on. 96 | It MAY be continued on the subsequent line(s), 97 | where each of them MUST be indented (preceded) by a sequence of four space characters (` `). 98 | 99 | The *description* MAY contain any number of *tags*, and/or one *due date*. 100 | (Any additional *due dates* MUST be disregarded.) 101 | 102 | > #### Example 103 | > 104 | > ``` 105 | > [ ] This description is one line 106 | > [ ] This description continues ... 107 | > ... on the next line 108 | > ``` 109 | 110 | ### Due Date 111 | 112 | A *due date* determines how timely an *item* is. 113 | 114 | It MUST be commenced with the character sequence `-> ` 115 | (a hypen, a greater-than sign, and a space), 116 | and then followed by a date pattern. 117 | 118 | The date pattern MUST be either of: 119 | 120 | - `yyyy-mm-dd` or `yyyy/mm/dd` to reference a calendar day 121 | - `yyyy-mm` or `yyyy/mm` to reference a month period 122 | - `yyyy` to reference a year period 123 | - `yyyy-Www` or `yyyy/Www` to reference a week period 124 | - `yyyy-Qq` or `yyyy/Qq` to reference a quarter period 125 | 126 | `y` MUST be a digit that denotes the year; 127 | `m` the month; 128 | `d` the day; 129 | `w` the week number (according to ISO8601); 130 | `q` the quarter number. 131 | `W` and `Q` MUST appear literally. 132 | 133 | The periodic patterns MUST be treated as equivalent 134 | to the last calendar day within the respective time frame. 135 | 136 | The *due date* value MUST be representable by the gregorian calendar. 137 | 138 | > #### Example 139 | > 140 | > ``` 141 | > [ ] This shall be done until -> 2022-03-31 142 | > [ ] -> 2022-03 Do this throughout March 143 | > [ ] Do this -> 2022-Q2 within the second quarter 144 | > ``` 145 | 146 | ### Tag 147 | 148 | *Tags* are annotations for categorising or filtering the data. 149 | 150 | A *tag* MUST consist of a *tag name*, 151 | which MUST be preceded by a single `#` character. 152 | The *tag name* MAY be followed by a `=` character and a *tag value*. 153 | 154 | The *tag name* MUST only contain letters, digits, or the characters `_` or `-`. 155 | It MUST be treated as case-insensitive. 156 | 157 | The *tag value* MAY be surrounded by a pair of matching quotes, 158 | which MUST either be `"` (RECOMMENDED) or `'`. 159 | - If the *tag value* is quoted, it MAY contain any character 160 | except for the respective quote character itself, or a newline. 161 | In case no matching closing quote appears on the same line, 162 | the *tag value* MUST be treated as absent. 163 | - If the *tag value* is not quoted, it MUST only contain 164 | letters, digits, or the characters `_` or `-`. 165 | 166 | The *tag value* MUST be treated as case-sensitive. 167 | 168 | An empty *tag value* (e.g. `#tag=` or `#tag=""`) 169 | MUST be treated the same as an absent *tag value* (e.g. `#tag`). 170 | 171 | > #### Example 172 | > 173 | > ``` 174 | > [ ] This item has a #tag 175 | > [ ] This #item has #multiple #tags! 176 | > [ ] Tags can #have=values 177 | > [ ] Values #can="be quoted" 178 | > ``` 179 | 180 | ### Group 181 | 182 | A *group* is any consecutive number of *items* 183 | (without blank line in between), 184 | that MAY be preceded by one *title*. 185 | 186 | > #### Example 187 | > 188 | > ``` 189 | > [ ] This item and the next one ... 190 | > [ ] ... are grouped 191 | > 192 | > [ ] This item is its own group 193 | > ``` 194 | 195 | ### Title 196 | 197 | The *title* is a single line of text 198 | that MUST NOT start with a blank character 199 | or the opening square bracket character `[`. 200 | 201 | > #### Example 202 | > 203 | > ``` 204 | > My TODO list 205 | > [ ] Item 1 206 | > [ ] Item 2 207 | > ``` 208 | 209 | ## Appendix 210 | 211 | ### Glossary 212 | 213 | - Blank character: a character from the Unicode Space Separator category (Zs) 214 | - Blank line: a line that is either empty, or that exclusively consists of blank characters 215 | - Digit: `0`, `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, or `9` 216 | - Letter: a character from the Unicode Letter category (L) 217 | - Newline: `\n` or `\r\n` 218 | - Punctuation: a character from the Unicode Punctuation category (P) 219 | 220 | ### Changelog 221 | 222 | #### Version 1.1 223 | 224 | - Add new checkbox status “in question”: `[?]` 225 | --------------------------------------------------------------------------------