How do I use org-todo and org-agenda?

[codygman]

After figuring this out for myself, I'd be happy to add documentation to the org-mode layer so others will know in the future.

I see some great tutorials for using org-agenda, capture, and org-todo mode together like these:

• http://emacslife.com/baby-steps-org.html
• http://orgmode.org/worg/org-tutorials/orgtutorial_dto.html

Upon reading these, it seems the Spacemacs org mode layer makes more assumptions about how one would use org agenda to organize though and I'm not sure how to map these tutorials to spacemacs.

If anyone that uses org-agenda and it's todo lists with spacemacs could give a short list of steps to get started it would be a great help. I'm currently still trying to figure it out and will continue to do so, but will also monitor this issue.

Thanks!

[robbyoconnor]

#5013 is pending merge soonish and may address this...

[codygman]

@robbyoconnor Thanks that looks really awesome, but doesn't address my confusion for how the entire process should work.

When I press SPC C c for instance, a screen like this pops up:

How do I select either ort/todo or ort/check-todo-item?

Ah now when looking at the screen for SPC C I see that SPC C t and SPC C T can be used for ort/todo and ort/check-todo-item respectively. If someone comes from emacs and expects to go to org-capture like I did however they get to a useless screen where no a-z key except for q (which quits) will do anything.

I think I've found part of my answer by finding out that SPC C c takes me to a screen where all I can do by default is quit.

[robbyoconnor]

Yeah never learned how to use it myself :(

[codygman]

Alright, I've figured out that if you use ort/capture-todo (SPC C t) in a "project" (something with a git repo qualifies as a project) then any todo captured will be added to /path/to/project/TODO.org, otherwise it will get added to $HOME/TODO.org.

Now... what does org agenda show when inside of my project? org-agenda-list (SPC a o a) shows nothing. What about org-todo-list(SPC a o t)? Still nothing. This is confusing. I have a /myproject/TODO.org with a task in it yet both of these views show nothing (still nothing globally (outside of my project) as well). Perhaps because it isn't scheduled? I recall using org-todo-list before in vanilla emacs and it would show me all todo's so that I could refile or schedule them.

Maybe if I run org-todo-list or org-agenda list from inside of the TODO.org files? Nope...

[codygman]

Since org-agenda isn't showing any todo's, I'm guessing it's not set for the right files. I even scheduled some of the files and still don't see anything in org-agenda.

Alright, looking through the source code I found:

(defcustom org-agenda-files nil
  "The files to be used for agenda display.
Entries may be added to this list with \\[org-agenda-file-to-front] and removed with
\\[org-remove-file].  You can also use customize to edit the list.

I then tried running org-agenda-file-to-front from inside of my global TODO.org buffer, then running org-todo-list, and the files did show up.

That means as far as I can tell the process for using a global ~/org/TODO.org file would consist of adding ~/org/TODO.org to org-agenda-files. If you want to use it on a per project basis you'll have to add /path/to/project/TODO.org to org-agenda-files as well.

This is kind of confusing to me since early on it seemed like Spacemacs worked out of the box for org-agenda working on a per project basis.

[d12frosted]

Upon reading these, it seems the Spacemacs org mode layer makes more assumptions about how one would use org agenda to organize though

Haven't noticed anything like this. (Read further to see my point).

and I'm not sure how to map these tutorials to spacemacs.

Reading further your issues I wanted to read these articles you have linked and in the first one I found this:

First, we need to add your ~/todo.org to the list of files Org looks at when coming up with the agenda. Open your ~/todo.org and type C-c [ (org-agenda-file-to-front). This adds the current file to the list.

In the second article I also found several mentions to org-agenda-files. Which is really natural, because that's how agenda works - it must know what to use to construct itself.

(setq org-agenda-files (list "~/org/work.org"
                             "~/org/school.org" 
                             "~/org/home.org"))

(from that second article - under 'A taste of advanced features' section).

---

Back to updating documentation. I don't think that Spacemacs org layer documentation is the right place for things like this. There is already this huge tutorial on how to work with org.

Surely one might come with solution on automatically adding project todos to list of agenda files, but someone might not like it (for example me). Because generally everyone has different organisation of org files.

And again, I don't understand why you say that 'Spacemacs org mode layer makes more assumptions about how one would use org agenda to organize'. We could add some assumptions buy introducing following variables:

• list of org agenda directories (that are searched recursively or not depending on value of another variable)
• list of additional org agenda files (not the org-agenda-files, so user don't hurt himself)
• list of blacklisted directories
• list of blacklisted filenames

I already use very similar flow for constructing my org-agenda-files before calling org-agenda. But again, it's just me and I am not sure that everyone would like it. Though I believe that it can be improved to become much better and pretty good for almost everyone.

P. S. Yes, I do have some ideas on how to improve that - will send PR on next weekends.

P. P. S. #5013 is not addressing this issue though :)

[StreakyCobra]

P. P. P. S. #5013 has been merged 5 days ago @robbyoconnor ;-)

[oiwn]

Just about time =) I just started to use it and stucked a bit.

[codygman]

Will respond when at pc in full, but for now...

Surely one might come with solution on automatically adding project todos to list of agenda files, but someone might not like it (for example me). Because generally everyone has different organisation of org files.

Isn't this true for everything that spacemacs provides sensible defaults for? As for adding a tutorial or guide we don't have to add it to the org layer guide. Instead we could create a section in the wiki with a walkthrough for using org, org agenda, and org to-do.

You and I payed the startup costs to understanding this and figuring it out, but providing a sensible default and walkthrough coupled with information on customizing seems very aligned with the purpose of spacemacs.

[codygman]

So that others can just have that creature working out of the box plus an easy path to tailor it for their specific needs.

[d12frosted]

Instead we could create a section in the wiki with a walkthrough for using org, org agenda, and org to-do.

Who am I to stop someone from such burden? But honestly, I am against putting it into Spacemacs wiki. And since there are a lot of good tutorials, starting points, I think it's waste of human power to write and maintain such stuff. Better to document Spacemacs-only things and describe how they can help in completing everyday deeds.

Isn't this true for everything that spacemacs provides sensible defaults for?

Sure, someone can implement this and make such behaviour optional (with off by default). I am not agains it :)

You and I payed the startup costs to understanding this and figuring it out

No offence, but such tutorial will be pretty similar to those you linked. They will also say - you have to add file path to list of agenda files in order to see them in agenda.

plus an easy path to tailor it for their specific needs

Yeah, that's what I am going to add - helpers for setting up your agenda list. I agree that in most cases people use pretty similar solutions, so I would like to work on them and add to Spacemacs :) I hope you'll find them useful.

P. S. No offence - it's just am I in a little rush and wanted to answer your comment ;)

[flowersw]

@codygman A great reference for at least variables that you can put into you DOTFILE related to Org-mode customizations: http://orgmode.org/worg/org-configs/org-customization-guide.html

[Apromixately]

I think the appropriate thing to do here - from a UX point of view - is to alert people that the org agenda requires setup when they try to use it without having performed such a setup.

I'm not sure if there are other issues but at least org-agenda-files should be set.

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Please let us know if this issue is still valid!

[Apromixately]

I think this is still open.