cmc/cleberg.net

  1#+date:        [2024-08-11 Sun 12:48:00]
  2#+title:       Org Mode Features: What I Actually Use
  3#+description: The Org Mode features I actually reach for, and how I use them.
  4#+slug:        org-mode-features
  5#+filetags:    :emacs:
  6
  7* Cycling (Folding)
  8
  9#+begin_quote
 10[[https://github.com/ccleberg/cleberg.net/blob/main/content/blog/2024-08-11-org-mode-features.org#L7][View this section]] in org-mode.
 11#+end_quote
 12
 13My absolute top-used feature is [[https://orgmode.org/manual/Global-and-local-cycling.html][global and local cycling]] and it's not even
 14close. Being able to hit =S-TAB= and collapse all headings when opening a file
 15or needing to see a file's headings is an under appreciated trait.
 16
 17** Local Cycling
 18
 19When focused on a heading, you can press =TAB= (=org-cycle=) to cycle that
 20subtree among the states =folded=, =children=, and =subtree=.
 21
 22#+begin_src txt
 23,-> FOLDED -> CHILDREN -> SUBTREE --.
 24'-----------------------------------'
 25#+end_src
 26
 27** Global Cycling
 28
 29If you're looking to cycle more than one subtree or heading at a time, you can
 30press =S-TAB= or =C-u TAB= to cycle the entire buffer among the states
 31=overview=, =contents=, and =show all=.
 32
 33#+begin_src txt
 34,-> OVERVIEW -> CONTENTS -> SHOW ALL --.
 35'--------------------------------------'
 36#+end_src
 37
 38** Default Views
 39
 40If you need to set a default view for a certain file, you can run =C-u C-u TAB=
 41to set the =org-set-startup-visibility=. Alternatively, just put the following
 42at the top of the buffer:
 43
 44#+begin_src org
 45#+STARTUP: overview
 46#+STARTUP: content
 47#+STARTUP: showall
 48#+STARTUP: show2levels
 49#+STARTUP: show3levels
 50#+STARTUP: show4levels
 51#+STARTUP: show5levels
 52#+STARTUP: showeverything
 53#+end_src
 54
 55* TODO Lists
 56
 57#+begin_quote
 58[[https://github.com/ccleberg/cleberg.net/blob/main/content/blog/2024-08-11-org-mode-features.org#L55][View this section]] in org-mode.
 59#+end_quote
 60
 61Next up on in this post are [[https://orgmode.org/manual/TODO-Items.html][TODO Lists]]. Being able to combine note taking and
 62reminders was the primary reason I switched to org-mode in the first place.
 63
 64TODO lists are more than just the Markdown equivalent of =- [ ] Task=. Instead,
 65you can utilize org-mode's native functionality to dynamically create TODO
 66items, have fast access to TODO states, log progress on tasks, clocking work
 67time, prioritization, breaking down tasks into subtasks, and even using checkbox
 68formatting as well.
 69
 70** Prioritizing Tasks
 71
 72One of my favorite ways to separate my tasks are to assign priorities. You can
 73do this by placing a priority cookie into the headline of a TODO item.
 74
 75#+begin_src org
 76,*** TODO [#A] My Task
 77,*** TODO [#C] My Other Task
 78#+end_src
 79
 80You can quickly shift priorities with =S-UP= and =S-DOWN=, as well as set the
 81allowed priorities for a buffer with the following syntax:
 82
 83#+begin_src org
 84#+PRIORITIES: A C B
 85#+PRIORITIES: 1 10 5
 86#+end_src
 87
 88** Deadlines
 89
 90Plans can be set per task by settings special keywords with a date. You can set
 91a =DEADLINE= to note when the task will appear in the agenda or set the
 92=SCHEDULED= variable to note when you plan to start working on the task.
 93
 94#+begin_src org
 95,* TODO My Task
 96DEADLINE: <2004-02-29 Sun>
 97
 98,* My Other Task
 99SCHEDULED: <2004-12-25 Sat>
100#+end_src
101
102As a side note, I use [[https://www.beorgapp.com/][Beorg]] on iOS to sync and edit my org-mode files on the go.
103Within this app, I use the =SCHEDULED= variable by default and rely heavily on
104that variable to alert me of tasks with iOS native notifications.
105
106* Time Stamping
107
108#+begin_quote
109[[https://github.com/ccleberg/cleberg.net/blob/main/content/blog/2024-08-11-org-mode-features.org#L106][View this section]] in org-mode.
110#+end_quote
111
112Another great feature are the [[https://orgmode.org/manual/Dates-and-Times.html][dates and times]] functionalities within org-mode.
113Timestamps follow this format in org-mode:
114
115#+begin_src org
116,* An active timestamp
117<2006-11-01 Wed 19:15>
118
119,* An inactive timestamp
120[2006-11-01 Wed 19:15>
121
122,* Repeated timestamps
123<2006-11-01 Wed 19:15 +1m>
124
125,* Time range
126<2006-11-02 Thu 10:00-12:00>
127
128,* Date range
129<2004-08-23 Mon>--<2004-08-26 Thu>
130#+end_src
131
132In addition to the deadlines mentioned above, you can insert timestamps into any
133marker within the buffer with =C-c .= for an active timestamp and =C-c != for an
134inactive timestamp. You can read more on [[https://orgmode.org/manual/Creating-Timestamps.html][creating timestamps]] to figure out the
135different options available when creating timestamps.
136
137* Tags
138
139#+begin_quote
140[[https://github.com/ccleberg/cleberg.net/blob/main/content/blog/2024-08-11-org-mode-features.org#L137][View this section]] in org-mode.
141#+end_quote
142
143Next up are [[https://orgmode.org/manual/Tags.html][Tags]], which provide a way to document contexts within and across
144buffers and files.
145
146You can assign tags directly to headlines or at the file level and can contain
147letters, numbers, underscores, and the =@= symbol.
148
149#+begin_src org
150,
151,* Pick fruits off the trees      :work:
152,** Start with the orange grove   :orange:tree:
153,*** TODO Pick bananas last       :banana:
154#+end_src
155
156** Filtering and Searching by Tag
157
158You can search for tags with =C-c \= or open the org-agenda with =M-x org-agenda
159m= and search for a tag of your choosing.
160
161* Tables
162
163#+begin_quote
164[[https://github.com/ccleberg/cleberg.net/blob/main/content/blog/2024-08-11-org-mode-features.org#L161][View this section]] in org-mode.
165#+end_quote
166
167One of the most inconvenient parts of writing in Markdown was dealing with
168tables. In org-mode, [[https://orgmode.org/manual/Tables.html][Tables]] are a breeze due to Emacs's built-in table editor
169and formatter.
170
171** Built-In Table Editor
172
173With the built-in table editor, press =C-c |= to convert the active region to a
174table or create an empty table.
175
176When focused on a table, press =TAB= to re-align the table. There are more
177commands available to re-align, traverse, and edit cells and regions within
178tables in Emacs.
179
180For example, refer to the following table. This table uses the =TBLFM= variable
181to define functions that will apply to the cells within the table. When I press
182=C-c C-c=, the table cells updated to their resulting values.
183
184| N | N^2 | N^3 | N^4 |   sqrt(n) | sqrt[4](N) |
185|---+-----+-----+-----+-----------+------------|
186| / |   < |     |   > |         < |          > |
187| 1 |   1 |   1 |   1 |         1 |          1 |
188| 2 |   4 |   8 |  16 | 1.4142136 |  1.1892071 |
189| 3 |   9 |  27 |  81 | 1.7320508 |  1.3160740 |
190|---+-----+-----+-----+-----------+------------|
191#+TBLFM: $2=$1^2::$3=$1^3::$4=$1^4::$5=sqrt($1)::$6=sqrt(sqrt(($1)))
192
193** Spreadsheet
194
195If you spend a lot of time in spreadsheets, you'll appreciate the Emacs Calc
196package, which Emacs uses to implement spreadsheet-like capabilities within
197org-mode tables.
198
199Read through the [[https://orgmode.org/manual/The-Spreadsheet.html][spreadsheet]] documentation to learn more about field references
200(=@ROW$COLUMN=), range references (=$1..$3=), coordinates, formulas, and more.
201
202For example, refer to the following table. Here is a table that computes the
203Taylor series of degree n at location x for a couple of functions. You can clear
204the values out of the =Result= column for each row, press =C-c C-c=, and watch
205as the table re-calculates the results for each.
206
207|---+-------------+---+-----+--------------------------------------|
208|   | Func        | n | x   | Result                               |
209|---+-------------+---+-----+--------------------------------------|
210| # | exp(x)      | 1 | x   | 1 + x                                |
211| # | exp(x)      | 2 | x   | 1 + x + x^2 / 2                      |
212| # | exp(x)      | 3 | x   | 1 + x + x^2 / 2 + x^3 / 6            |
213| # | x^2+sqrt(x) | 2 | x=0 | x*(0.5 / 0) + x^2 (2 - 0.25 / 0) / 2 |
214| # | x^2+sqrt(x) | 2 | x=1 | 2 + 2.5 x - 2.5 + 0.875 (x - 1)^2    |
215| * | tan(x)      | 3 | x   | x pi / 180 + 5.72e-8 x^3 pi^3        |
216|---+-------------+---+-----+--------------------------------------|
217#+TBLFM: $5=taylor($2,$4,$3);n3
218
219Alternatively, you can also refer to the following table. This table will update
220to different values based on the =TBLFM= I select when I'm pressing =C-c C-c=.
221The results are =[1,2]= when focused on the first line and =[2,4]= when focused
222on the second line.
223
224| x | y |
225|---+---|
226| 1 | 2 |
227| 2 | 4 |
228#+TBLFM: $2=$1*1
229#+TBLFM: $2=$1*2
230
231* Source Code Blocks
232
233#+begin_quote
234[[https://github.com/ccleberg/cleberg.net/blob/main/content/blog/2024-08-11-org-mode-features.org#L231][View this section]] in org-mode.
235#+end_quote
236
237** Introduction to Source Code Blocks
238
239If you run a technical blog, write code frequently, or like to take notes with
240source code examples, you will appreciate the [[https://orgmode.org/manual/Working-with-Source-Code.html][source code]] functionality of
241org-mode.
242
243With this feature, org-mode can manage the source code you define with features
244such as editing, formatting, extracting, exporting, and publishing.
245Additionally, you can compile and execute source code dynamically within the
246org-mode file or buffer.
247
248A full source code block uses the following structure:
249
250#+begin_src org
251,#+NAME: <name>
252,#+BEGIN_SRC <language> <switches> <header arguments>
253  <body>
254,#+END_SRC
255#+end_src
256
257You can also use inline blocks:
258
259#+begin_src org
260src_<language>[<header arguments>]{<body>}
261#+end_src
262
263** Editing Source Code Blocks
264
265When focused on a code block, press =C-c'= to edit the code block in a special
266editor. Press =C-x C-x= to save the buffer and =C-c '= again to close the
267buffer.
268
269** Syntax Highlighting and Formatting
270
271Emacs provides syntax highlighting by default within org-mode's source code
272blocks. Org-mode will copy the text to a temporary buffer, highlight it using
273the major mode relevant to the language (e.g., [[https://www.gnu.org/software/emacs/manual/html_mono/ccmode.html][CC Mode]]), and then return the
274resulting highlighted text.
275
276** Buffer Evaluation
277
278By default, org-mode will only evaluate Emacs Lisp code blocks. You will need to
279enable other [[https://orgmode.org/manual/Languages.html][languages]] in order to evaluate code blocks written in languages
280other than elisp.
281
282When focused on a code block, you can execute the block with =C-c C-c=. The
283results of the evaluation will appear below the code block in a =RESULTS= block.
284
285For example, here is a code block in elisp that I have written and evaluated with
286org-mode inside this blog post. I will press =C-c C-c= and you will see the
287results below the code block.
288
289#+begin_src elisp
290(defun greet-me ()
291  (message "Hello, world!"))
292
293(greet-me)
294#+end_src
295
296#+begin_src org
297,#+RESULTS:
298: Hello, world!
299#+end_src
300
301* Exporting and Publishing
302
303#+begin_quote
304[[https://github.com/ccleberg/cleberg.net/blob/main/content/blog/2024-08-11-org-mode-features.org#L301][View this section]] in org-mode.
305#+end_quote
306
307I would be remiss if I did not mention the native [[https://orgmode.org/manual/Exporting.html][exporting and publishing]]
308functionality within Emacs and org-mode.
309
310** Built-In Publishing
311
312This functionality allows you to translate Org to the following formats
313(additional formats may be available via external packages):
314
315- ascii (ASCII format)
316- beamer (LaTeX Beamer format)
317- html (HTML format)
318- icalendar (iCalendar format)
319- latex (LaTeX format)
320- md (Markdown format)
321- odt (OpenDocument Text format)
322- org (Org format)
323- texinfo (Texinfo format)
324- man (Man page format)
325
326  You can export with =C-c C-h= and then select your preferred destination
327  format. For example, an export from org to HTML as a file would use =C-c C-e h
328  h=.
329
330** External Publishing Tools
331
332If the native functionality isn't useful enough for you, there are a myriad of
333external [[https://orgmode.org/tools.html][tools]], including [[https://orgmode.org/worg/org-blog-wiki.html][blogs and wikis]], that work with org-mode.
334
335* Agenda
336
337#+begin_quote
338[[https://github.com/ccleberg/cleberg.net/blob/main/content/blog/2024-08-11-org-mode-features.org#L335][View this section]] in org-mode.
339#+end_quote
340
341Last, but not least, are [[https://orgmode.org/manual/Agenda-Views.html][Agenda Views]]. With agenda views, you can easily view
342your agenda of TODO items, scheduled items, projects, etc. across your
343collection of org-mode files.
344
345Org-mode will extract all of this information from your org files
346(=org-agenda-files=) and display it within the agenda buffer.
347
348You can open the agenda with =M-x org-agenda=. Once inside the buffer, you can
349use shortcuts in the [[https://orgmode.org/manual/Agenda-Dispatcher.html][Agenda Dispatcher]] to quickly view calendars, TODOs, create
350items, filter items, and more.