* Documentation wishlist items
@ 2009-09-15 21:21 Ethan
2009-09-15 23:56 ` Sean Sieger
` (3 more replies)
0 siblings, 4 replies; 26+ messages in thread
From: Ethan @ 2009-09-15 21:21 UTC (permalink / raw)
To: emacs-orgmode
[-- Attachment #1.1: Type: text/plain, Size: 3487 bytes --]
Hi guys,
I've been studying org-mode for a few months now, and I think I'm finally
getting the hang of it. It's really overwhelming, and I really appreciate
the efforts that must have gone into the manual and the worg project. But I
think it still needs work.
The fundamental problem is that org-mode isn't a planner, it isn't an
organizer. It's a toolkit full of tools which people use differently, in
lots of ways, to build their own planner/organizer. To understand org-mode,
you have to understand all of the tools available, and the options you have
for each, and the ways they interact with the other tools. In my opinion,
the documentation doesn't explore the interactions well enough, it doesn't
present the tools in an order that is conducive to learning, and it never
explains why you might choose one option of tool instead of another.
For example, let's take Archiving. The documentation I'm reading right now,
at http://orgmode.org/manual/Archiving.html#Archiving, puts archiving in
"Document Structure", section 2.6, before TODO keywords, tags, the agenda,
or anything else. There's one paragraph about what archiving means, then
five or six paragraphs about how a headline with the ARCHIVE tag behaves,
and then a section about moving trees and where you could move them. It
isn't clear what workflows you might use Archive Sibling in, or why C-u C-c
C-x C-s would archive *children* of the selected headline instead of the
headline itself.
Another good example is TODO keywords, categories, and tags. It isn't clear
what they all are, or why they are distinct, or what the differences are,
and it's easy to confuse them with similarly-named but completely distinct
concepts like properties.
In other words, to really understand the manual, you have to read it twice
-- once to hear about all the concepts, and once more to see how they
relate. And then to start using org-mode, you have to play with a bunch of
different possible arrangements of the concepts, see which things you like,
and finally settle on an arrangement that suits you a little bit, before
starting the endless path of tweakage.
Reading HOWTO's like Bernt Hansen's and Charles Cave's are really
interesting to see how people work, but even documents like these don't
explain *why* they set things up in this way. For example, Bernt Hansen's
document explains that his toplevel headings are "main categories", and
shows that they each have a CATEGORY property, but doesn't explain what that
buys him, or what problem that solves.
In short, after studying org-mode for a long time, I finally feel ready to
start using it -- not that I understand it, but that I know where the most
important knobs are. I feel like it would have been a lot easier for me to
start using it if I had started with a tutorial that explained a single
workflow and how org-mode supported it, and I feel like the org-mode manual
could have gone a long way in making this learning easier. For example, the
documentation for C-u C-c C-x C-s could say something like "This supports
workflows where there is a top-level Projects heading, and each heading
underneath represents a project. You could then use this command to archive
all projects which didn't have open TODO items.".
I wish I could offer more concrete improvements in the form of patches and
so on! Maybe as I learn more about org-mode I can do this too, but I wanted
to offer this criticism while it was still fresh in my mind.
Thanks for everything!
Ethan
[-- Attachment #1.2: Type: text/html, Size: 3751 bytes --]
[-- Attachment #2: Type: text/plain, Size: 204 bytes --]
_______________________________________________
Emacs-orgmode mailing list
Remember: use `Reply All' to send replies to the list.
Emacs-orgmode@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-orgmode
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Documentation wishlist items
2009-09-15 21:21 Documentation wishlist items Ethan
@ 2009-09-15 23:56 ` Sean Sieger
2009-09-16 3:20 ` Sebastian Rose
` (2 subsequent siblings)
3 siblings, 0 replies; 26+ messages in thread
From: Sean Sieger @ 2009-09-15 23:56 UTC (permalink / raw)
To: emacs-orgmode
Ethan <ethan.glasser.camp@gmail.com> writes:
Thanks for the mail Ethan. I approached Org ... I don't know, a few
years ago having really really taken advantage of Outline. I promptly
made a mess, trying things I thought I needed to and went back to
Outline and organization that was natural to me. The experience helped
me formulate goals and I came back to Org only weeks ago armed with
fairly precise ideas.
The fundamental problem is that org-mode isn't a planner, it isn't
an organizer. It's a toolkit full of tools which people use
differently, in lots of ways, to build their own
planner/organizer. To understand org-mode, you have to understand
all of the tools available, and the options you have for each, and
the ways they interact with the other tools.
Nah, to understand what Org can do for me, I needed to understand myself
and my limitations.
In my opinion, the documentation doesn't explore the interactions
well enough, it doesn't present the tools in an order that is
conducive to learning, and it never explains why you might choose
one option of tool instead of another.
Right. That documentation has evolved in the little time I've been
reading it. It does explain, and so does this list that the fundamental
... um, primary action is to quickly Capture. That's how I came to Org
this time---getting a ~/.notes file going. Capturing fleeting thoughts
and appending them to that file and then discerning what and how to
organize them.
[...]
I wish I could offer more concrete improvements in the form of
patches and so on! Maybe as I learn more about org-mode I can do
this too, but I wanted to offer this criticism while it was still
fresh in my mind.
... Just captured something my six year-old daughter said on the phone.
I should concentrate on her. I'll do <F8> (remember's bound to it)
several more times in talking with her.
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Documentation wishlist items
2009-09-15 21:21 Documentation wishlist items Ethan
2009-09-15 23:56 ` Sean Sieger
@ 2009-09-16 3:20 ` Sebastian Rose
2009-09-16 9:46 ` Bastien
` (2 more replies)
2009-09-16 3:34 ` Matt Lundin
2009-09-16 9:42 ` Documentation wishlist items Bastien
3 siblings, 3 replies; 26+ messages in thread
From: Sebastian Rose @ 2009-09-16 3:20 UTC (permalink / raw)
To: Ethan; +Cc: emacs-orgmode
Ethan <ethan.glasser.camp@gmail.com> writes:
> Hi guys,
>
> I've been studying org-mode for a few months now, and I think I'm finally
> getting the hang of it. It's really overwhelming, and I really appreciate
> the efforts that must have gone into the manual and the worg project. But I
> think it still needs work.
>
> The fundamental problem is that org-mode isn't a planner, it isn't an
> organizer. It's a toolkit full of tools which people use differently, in
> lots of ways, to build their own planner/organizer. To understand org-mode,
> you have to understand all of the tools available, and the options you have
> for each, and the ways they interact with the other tools. In my opinion,
> the documentation doesn't explore the interactions well enough, it doesn't
> present the tools in an order that is conducive to learning, and it never
> explains why you might choose one option of tool instead of another.
Hmm. I think of myself as a control freak, but I never felt I'd have to
understand everything in Org-mode. I don't. It works out the box, and
the manual helped, in that it is a reference (not complete maybe, but
complete enough).
Documentation is not such an easy thing to do and a lot of work, too. A
tutorial _is_ missing. We had some discussions here about that, but no
one got around to it. I think about it every so often, but writing a
tutorial is such a big thing to do.
Personally, I think that one or two fictive characters would fit
best. People, simply using Org-mode to take notes, plan, publish and so
on.
The entire thing should start _very_ simple and without any
customization at all. I see customization in chapter 15 - no earlier
really unless unavoidable.
Here is some kind of outline for such a tutorial.
Chapter 1
It simply starts when Alice starts Emacs to take a note or jot down
some ideas (brainstorming?). Headlines are moved around and later
filled with text (not sure, but maybe add promotion and demotion
here, too).
Chapter 2
Alice adds a simple list. This would repeat the shortcuts for adding
and moving headlines (they are the same, just in a similar but
slightly different context. This shows for the first time in this
tutorial, that all those keys are well structured).
Chapter 3
Alice adds the TODO keyword to one of the headlines. I.e. she holds
down the shift key while adding a headline.
Chapter 5
Alice starts to work on her first TODO, and changes the TODO state to
STARTED. After she finishes her work, she feels so good and switches
the TODO state to DONE. (Note: We will not add any configuration
options here at all. Alice just does it, and enjoys what Org-mode does
for her [1]).
Chapter 6 (was Chapter 4)
Alice is so exited, that she adds another TODO item. But what she does
now, is even more:
Alice does the same/similar for plain list items: hold down the shift
key, while adding an item. This is the time we introduce the `very
busy C-c C-c' key as the shortcut, that updates something. Here the
check boxes.
Chapter 9
Alice gets tired of open the Org-file, add a note, save the buffer and
close the file. She finds out about remember (or maybe Carl told her
about it - or she tells Carl how to do it? Maybe Alice is an
Org-pro... and Carl is one of her customers?).
Again, she just uses remember as it comes with Org-mode. No special
configuration necessary.
....
That's about the speed and the first Chapters for a tutorial, I think
[2].
A Page would look like this (e.g. Chapter 5):
=> --->8----------------------------->8----------------------------->8---
<- previous chapter index next chapter ->
* Chapter 5: Getting things DONE
Little introduction in what Alice will do in this chapter.
Alice starts to work on her first TODO. Alice changes the TODO state
to STARTED. More text describing how she changes the TODO state
(S-RIGHT), what she does - something in Emacs maybe - is Alice an
author or programmer?..
... When finished, After she finishes her work, she feels so good and
switches the TODO state to DONE. She uses the same shortcut
again. Alice enjoys what Org-mode does for her. She notes the new
little drawer (maybe, if this is the default) and the nice green color
of the `DONE' keyword.
,-------------------------------------------.
! Box 'WHAT WE HAVE LEARNED IN THIS CHAPTER |
! |
! S-RIGHT changes the TODO state |
`-------------------------------------------´
See also:
- list of links to advanced features
- for the impatient and the curious.
- In the tutorial
- or the Org-mode manual, worg, mailing list...
<- previous chapter index next chapter ->
<= ---8<-----------------------------8<-----------------------------8<---
While this looks a little childish, it will be really relaxed
reading. In the ideal case, children would be able to follow, and adults
wouldn't get bored.
While I think about the tutorial, I see, that some of Org-mode's
defaults could be reworked. Did you notice, that I did not mention
emphasis, bold and fixed width in the first 9 chapters? As things stand,
I would add them, when Alice starts publishing, which will be in chapter
25. I would have added it in chapter 15, if the default faces were
different. I use headline faces in different font sizes and they inherit
the variable face. If the default face for text would be in variable
width, the fixed width face for =code= et al would be visible too. I
don't use a variable width font for normal text, if Org-mode wouldn't
use the `default' face.
Best wishes
Sebastian
Footnotes:
[1] We should discuss this in an extra thread: make log-into-drawer and
clocking the default and just have it turned on (is it the
default??). It's sooo useful. And I'm sure, Alice would simply
enjoy it (without any customization !!!).
[2] An option would be, to pack the tutorial as some kind of zip file
and add some interactive features, like the Emacs tutorial has. That
said, we could simply add
`orgmode.org/worg/the-org-tutorial/index.org' to start it.
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Documentation wishlist items
2009-09-15 21:21 Documentation wishlist items Ethan
2009-09-15 23:56 ` Sean Sieger
2009-09-16 3:20 ` Sebastian Rose
@ 2009-09-16 3:34 ` Matt Lundin
2009-09-16 11:37 ` Bernt Hansen
` (3 more replies)
2009-09-16 9:42 ` Documentation wishlist items Bastien
3 siblings, 4 replies; 26+ messages in thread
From: Matt Lundin @ 2009-09-16 3:34 UTC (permalink / raw)
To: Ethan; +Cc: emacs-orgmode
Ethan <ethan.glasser.camp@gmail.com> writes:
> Hi guys,
>
> I've been studying org-mode for a few months now, and I think I'm
> finally getting the hang of it.
I'm still saying the same thing after 1 year. :)
> It's really overwhelming, and I really appreciate the efforts that
> must have gone into the manual and the worg project. But I think it
> still needs work.
>
> The fundamental problem is that org-mode isn't a planner, it isn't an
> organizer.
???
> It's a toolkit full of tools which people use differently,
> in lots of ways, to build their own planner/organizer. To understand
> org-mode, you have to understand all of the tools available, and the
> options you have for each, and the ways they interact with the other
> tools.
I must respectfully disagree here. The org-mode basics are quite simple.
Create an outline, organize it however you see fit, mark actions as
TODOs, schedule, view and review using the agenda. To take advantage of
org, you really don't need to know much more than that. The basic
concepts would apply to any outliner or basic task management tool.
All the other features---clocking, properties, column view, exporting,
publishing, tags, tables/spreadsheets, effort estimates, etc.---are
there in the background in the event that you need them.
Heck, even without all the extras, org would still be a world-class
outliner.
> For example, let's take Archiving. The documentation I'm reading right
> now, at http://orgmode.org/manual/Archiving.html#Archiving, puts
> archiving in "Document Structure", section 2.6, before TODO keywords,
> tags, the agenda, or anything else. There's one paragraph about what
> archiving means, then five or six paragraphs about how a headline with
> the ARCHIVE tag behaves, and then a section about moving trees and
> where you could move them. It isn't clear what workflows you might use
> Archive Sibling in, or why C-u C-c C-x C-s would archive *children* of
> the selected headline instead of the headline itself.
The manual is not your only source of information. I make heavy use of
C-h v and C-h f to learn more about particular variables and functions.
> Another good example is TODO keywords, categories, and tags. It isn't
> clear what they all are, or why they are distinct, or what the
> differences are, and it's easy to confuse them with similarly-named but
> completely distinct concepts like properties.
Here's how I see it.
1) TODO keywords: How does this item fit into my workflow?
2) Category: What group does this tree belong to? (This is the word that
appears next to the item in the agenda.)
3) Tags: What words do I want to add to this item/tree to enable me to
find it easily. (Commonly used for GTD contexts.)
4) Properties: What extra data would I like to attach to this item?
(Commonly used to set special options for a subtree/item, but also
very useful for creating ad-hoc "databases".)
In my opinion, one of the biggest decisions new users have to make is
how to designate projects. Should I use a TODO keyword, a tag, or a
second level headline? I prefer the todo keyword "PROJECT" myself, but
any of these would work fine.
And if you regret the decision three months from now, you can always use
org-map-entries to change your project items en masse.
> Reading HOWTO's like Bernt Hansen's and Charles Cave's are really
> interesting to see how people work, but even documents like these don't
> explain *why* they set things up in this way. For example, Bernt
> Hansen's document explains that his toplevel headings are "main
> categories", and shows that they each have a CATEGORY property, but
> doesn't explain what that buys him, or what problem that solves.
My guess is that this allows him to see what group an item belongs to in
the agenda view, since categories are listed in the left column.
But this is like asking why someone puts their pots in the cupboard next
to the oven rather than above the sink, or why someone uses legal pads
rather than a spiral notebook.
My recommendation: Just start creating trees, use only a few TODO
states, and allow the organization to evolve in the way that feels the
most comfortable to you.
Best,
Matt
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Documentation wishlist items
2009-09-15 21:21 Documentation wishlist items Ethan
` (2 preceding siblings ...)
2009-09-16 3:34 ` Matt Lundin
@ 2009-09-16 9:42 ` Bastien
2009-09-17 3:46 ` Matt Lundin
3 siblings, 1 reply; 26+ messages in thread
From: Bastien @ 2009-09-16 9:42 UTC (permalink / raw)
To: Ethan; +Cc: emacs-orgmode
Hi Ethan,
Ethan <ethan.glasser.camp@gmail.com> writes:
> I've been studying org-mode for a few months now, and I think I'm finally
> getting the hang of it. It's really overwhelming, and I really appreciate the
> efforts that must have gone into the manual and the worg project. But I think
> it still needs work.
"needs" is the wrong word here. "might enjoy" would be better. Because
Org comes with no warranty or customer service or whatsoever :)
> In my opinion, the documentation doesn't explore the interactions well
> enough, it doesn't present the tools in an order that is conducive to
> learning, and it never explains why you might choose one option of
> tool instead of another.
The manual is a reference. It's here so that people can refer to it
when they write tutorials or when they send answers to the mailing list.
This is not to say that the manual is perfect, but as you guess, Carsten
has been incrementally working on it -- suggestions which incrementally
improve it will enjoy a warmer welcome than incentives to rewrite it...
(= patch welcome!)
On top of that, "exploring the interactions" between all Org concepts is
beyond the goals of the manual and that's why Worg exists as a community
project.
> Another good example is TODO keywords, categories, and tags. It isn't clear
> what they all are, or why they are distinct, or what the differences are, and
> it's easy to confuse them with similarly-named but completely distinct concepts
> like properties.
The manual might enjoy a glossary. ;)
I have created org-glossary.org on Worg, please check it out and add
your own definitions: http://repo.or.cz/w/Worg.git
> In other words, to really understand the manual, you have to read it twice --
> once to hear about all the concepts, and once more to see how they
> relate.
The other way is to start using Org very spontaneously and just fetch
documentation when you feel the need of it. This is how I do and it
works well enough.
> I feel like it would have been a lot easier for me to
> start using it if I had started with a tutorial that explained a single
> workflow and how org-mode supported it
Your next contribution?
> I wish I could offer more concrete improvements in the form of patches and so
> on! Maybe as I learn more about org-mode I can do this too, but I wanted to
> offer this criticism while it was still fresh in my mind.
:) I guess the other way around is also useful: share the criticism
when the fresh impression vanished, and the core of it remains.
> Thanks for everything!
Thanks for sharing your thoughts, I'm sure positive improvements will
follow.
best,
--
Bastien
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Documentation wishlist items
2009-09-16 3:20 ` Sebastian Rose
@ 2009-09-16 9:46 ` Bastien
2009-09-16 9:54 ` Greg Newman
2009-09-16 12:17 ` Jean-Marie Gaillourdet
2009-09-16 9:49 ` Bastien
2009-09-16 12:46 ` Matt Lundin
2 siblings, 2 replies; 26+ messages in thread
From: Bastien @ 2009-09-16 9:46 UTC (permalink / raw)
To: Sebastian Rose; +Cc: emacs-orgmode
Sebastian Rose <sebastian_rose@gmx.de> writes:
> Documentation is not such an easy thing to do and a lot of work, too. A
> tutorial _is_ missing. We had some discussions here about that, but no
> one got around to it. I think about it every so often, but writing a
> tutorial is such a big thing to do.
I'm a go player. The best book I've read so far is "Lessons in the
fundamental of Go" -- check it here:
http://www.librarything.fr/work/151625
The nice thing about this book is that it's a dialog better two players,
and they learn from each other.
I would love to see a dialog between two org-ers, exchanging on how they
progressively adapt Org to their needs or any other topics. This could
actually be a bit more fun to write, and I'm sure the result would be
useful.
Who's in?
--
Bastien
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Documentation wishlist items
2009-09-16 3:20 ` Sebastian Rose
2009-09-16 9:46 ` Bastien
@ 2009-09-16 9:49 ` Bastien
2009-09-16 14:10 ` Sebastian Rose
2009-09-16 12:46 ` Matt Lundin
2 siblings, 1 reply; 26+ messages in thread
From: Bastien @ 2009-09-16 9:49 UTC (permalink / raw)
To: Sebastian Rose; +Cc: emacs-orgmode
Sebastian Rose <sebastian_rose@gmx.de> writes:
> Here is some kind of outline for such a tutorial.
Wow. That an outline for a full book!
And I guess that's what comes at the horizon: an (O-Reilly) book about
Org-mode. It would not compete with the manual as a reference, but it
would make it easier to more people to open Org's doors.
--
Bastien
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Documentation wishlist items
2009-09-16 9:46 ` Bastien
@ 2009-09-16 9:54 ` Greg Newman
2009-09-16 10:04 ` timetrap
2009-09-16 12:17 ` Jean-Marie Gaillourdet
1 sibling, 1 reply; 26+ messages in thread
From: Greg Newman @ 2009-09-16 9:54 UTC (permalink / raw)
To: Bastien; +Cc: emacs-orgmode
[-- Attachment #1.1: Type: text/plain, Size: 635 bytes --]
On Wed, Sep 16, 2009 at 5:46 AM, Bastien <bastienguerry@googlemail.com>wrote:
> Sebastian Rose <sebastian_rose@gmx.de> writes:
>
>
> I would love to see a dialog between two org-ers, exchanging on how they
> progressively adapt Org to their needs or any other topics. This could
> actually be a bit more fun to write, and I'm sure the result would be
> useful.
>
> Who's in?
>
+1 -- I'd love to see this too!
>
>
>
> _______________________________________________
> Emacs-orgmode mailing list
> Remember: use `Reply All' to send replies to the list.
> Emacs-orgmode@gnu.org
> http://lists.gnu.org/mailman/listinfo/emacs-orgmode
>
[-- Attachment #1.2: Type: text/html, Size: 1364 bytes --]
[-- Attachment #2: Type: text/plain, Size: 204 bytes --]
_______________________________________________
Emacs-orgmode mailing list
Remember: use `Reply All' to send replies to the list.
Emacs-orgmode@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-orgmode
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Documentation wishlist items
2009-09-16 9:54 ` Greg Newman
@ 2009-09-16 10:04 ` timetrap
0 siblings, 0 replies; 26+ messages in thread
From: timetrap @ 2009-09-16 10:04 UTC (permalink / raw)
To: emacs-orgmode
Configuration through dialectic. I like it.
Why not start a thread, and have an experienced user teach a newbie
how to get this org-mode thing working.
The only portion of the thread that would be published would be from
the two users, and the rest of the list could inject comments into the
thread as the users go about the business of building a config.
I'll be the newbie. We are good for something after all.
-Joseph Kern
On Wed, Sep 16, 2009 at 5:54 AM, Greg Newman <greg@20seven.org> wrote:
>
>
> On Wed, Sep 16, 2009 at 5:46 AM, Bastien <bastienguerry@googlemail.com>
> wrote:
>>
>> Sebastian Rose <sebastian_rose@gmx.de> writes:
>>
>>
>> I would love to see a dialog between two org-ers, exchanging on how they
>> progressively adapt Org to their needs or any other topics. This could
>> actually be a bit more fun to write, and I'm sure the result would be
>> useful.
>>
>> Who's in?
>
> +1 -- I'd love to see this too!
>>
>>
>> _______________________________________________
>> Emacs-orgmode mailing list
>> Remember: use `Reply All' to send replies to the list.
>> Emacs-orgmode@gnu.org
>> http://lists.gnu.org/mailman/listinfo/emacs-orgmode
>
>
> _______________________________________________
> Emacs-orgmode mailing list
> Remember: use `Reply All' to send replies to the list.
> Emacs-orgmode@gnu.org
> http://lists.gnu.org/mailman/listinfo/emacs-orgmode
>
>
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Documentation wishlist items
2009-09-16 3:34 ` Matt Lundin
@ 2009-09-16 11:37 ` Bernt Hansen
2009-09-16 15:33 ` Ethan
` (2 subsequent siblings)
3 siblings, 0 replies; 26+ messages in thread
From: Bernt Hansen @ 2009-09-16 11:37 UTC (permalink / raw)
To: Matt Lundin; +Cc: emacs-orgmode
Matt Lundin <mdl@imapmail.org> writes:
> Ethan <ethan.glasser.camp@gmail.com> writes:
>
>> Reading HOWTO's like Bernt Hansen's and Charles Cave's are really
>> interesting to see how people work, but even documents like these don't
>> explain *why* they set things up in this way. For example, Bernt
>> Hansen's document explains that his toplevel headings are "main
>> categories", and shows that they each have a CATEGORY property, but
>> doesn't explain what that buys him, or what problem that solves.
>
> My guess is that this allows him to see what group an item belongs to in
> the agenda view, since categories are listed in the left column.
That's correct. The category only shows up in my agenda in the left
column and gives me instant access to what this task is related to. I
usually specify a shorter category name than the filename just to keep
the agenda compact. My todo.org file has multiple categories since it's
a mishmash of personal stuff.
I use filtering to limit the displayed tasks but the category is a
useful piece of information on the agenda. I don't use category for
anything else.
I guess the problem it solves is if I have two identical tasks in
separate categories that both show up in the agenda then I can tell
which is which -- but that doesn't happen often. I clock in tasks from
the agenda so knowing which is which is important. "Invoicing and
Archive Tasks" is one example since I carry one of those for every
client (which are in separate files and separate categories).
-Bernt
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Documentation wishlist items
2009-09-16 9:46 ` Bastien
2009-09-16 9:54 ` Greg Newman
@ 2009-09-16 12:17 ` Jean-Marie Gaillourdet
2009-09-16 12:56 ` Peter Frings
1 sibling, 1 reply; 26+ messages in thread
From: Jean-Marie Gaillourdet @ 2009-09-16 12:17 UTC (permalink / raw)
To: emacs-orgmode
Am 16.09.09 11:46, schrieb Bastien:
> Sebastian Rose<sebastian_rose@gmx.de> writes:
>
>> Documentation is not such an easy thing to do and a lot of work, too. A
>> tutorial _is_ missing. We had some discussions here about that, but no
>> one got around to it. I think about it every so often, but writing a
>> tutorial is such a big thing to do.
>
> I'm a go player. The best book I've read so far is "Lessons in the
> fundamental of Go" -- check it here:
>
> http://www.librarything.fr/work/151625
>
> The nice thing about this book is that it's a dialog better two players,
> and they learn from each other.
Another interesting source for inspiration might be the tutorials of the
TikZ/PGF Manual.
http://www.ctan.org/tex-archive/graphics/pgf/base/doc/generic/pgf/pgfmanual.pdf
page 20 till 54
These tutorials are a nice contrast to the huge amount of reference
material available in the rest of the tikz manual.
Just my 2cents
Regards,
-- Jean-Marie
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Documentation wishlist items
2009-09-16 3:20 ` Sebastian Rose
2009-09-16 9:46 ` Bastien
2009-09-16 9:49 ` Bastien
@ 2009-09-16 12:46 ` Matt Lundin
2 siblings, 0 replies; 26+ messages in thread
From: Matt Lundin @ 2009-09-16 12:46 UTC (permalink / raw)
To: Sebastian Rose; +Cc: emacs-orgmode
Sebastian Rose <sebastian_rose@gmx.de> writes:
> Ethan <ethan.glasser.camp@gmail.com> writes:
>> Hi guys,
>>
> Documentation is not such an easy thing to do and a lot of work, too. A
> tutorial _is_ missing. We had some discussions here about that, but no
> one got around to it. I think about it every so often, but writing a
> tutorial is such a big thing to do.
>
> Personally, I think that one or two fictive characters would fit
> best. People, simply using Org-mode to take notes, plan, publish and so
> on.
>
> The entire thing should start _very_ simple and without any
> customization at all. I see customization in chapter 15 - no earlier
> really unless unavoidable.
Great ideas here and in the outline! Before we dive into creating a new
tutorial, we might want to use David O'Toole's venerable tutorial as a
point of reference. Rereading it today, it's remarkable how none of the
core principles of org-mode have changed despite so much development:
- http://orgmode.org/worg/org-tutorials/orgtutorial_dto.php
We might also take a look at the beginner's customization guide:
- http://orgmode.org/worg/org-configs/org-customization-guide.php
What needs to be updated there? What's missing?
I do like how org currently places Bernt's and Charles's tutorials under
a "power users" section, to distinguish them from basic tutorials. They
are examples of how two seasoned org-mode users take advantage of the
variety of features that org offers.
Would it be safe to say, though, that org-mode has since grown so
powerful and feature-rich that its many options can now overwhelm new
users, despite its core simplicity? What I hear in Ethan's original post
and in many recent mailing list posts is a request for help sorting out
the essentials from the "optional" features depending on use-scenarios.
An example: It seems that a new user, inspired by the many excellent
tutorials on remember, might be tempted to use remember to enter
*everything* in their org-files (with dozens of complex remember
templates). But in many instances, it may be faster and more convenient
to enter things directly into the outline.
I think what we're dealing with is the paradox of choice. Too many
options can paralyze/overwhelm a user. For instance, while archiving is
a straightforward feature, it's easy to get hung up on the fact that
there are three separate types of archiving, which gives rise to
uncertainty about which to use and when to use it, or perhaps even a
sense that one *must* understand and use all of them just because they
all exist.
With that in mind, we might add sections to the tutorial/book structured
around various use scenarios:
- If you're outlining/writing an book, here are some of the
features that might be useful.
- If you want a basic GTD system, here are a few ways you might do it.
- If you want to use org for sophisticated project management and
clocking, here are some of the things you might use find useful.
- If you're researching a book...
- If you want to keep track of interesting bookmarks on the web...
- If you want to publish documents for your co-workers...
Alternatively, we might move through the tutorial/dialogue feature by
feature:
- What in the world are drawers? Why would I want to use those?
- Etc.
Just a few ideas.
Best,
Matt
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Documentation wishlist items
2009-09-16 12:17 ` Jean-Marie Gaillourdet
@ 2009-09-16 12:56 ` Peter Frings
0 siblings, 0 replies; 26+ messages in thread
From: Peter Frings @ 2009-09-16 12:56 UTC (permalink / raw)
To: org-mode Mailinglist
On 16 Sep 2009, at 14:17, Jean-Marie Gaillourdet wrote:
> Another interesting source for inspiration might be the tutorials of
> the TikZ/PGF Manual. http://www.ctan.org/tex-archive/graphics/pgf/base/doc/generic/pgf/pgfmanual.pdf
> page 20 till 54
I agree, the tikz manual is really good.
Another well done piece of documentation (and a superb program as
well) is that of lilypond: http://lilypond.org/doc/v2.12/Documentation/user/lilypond-learning/index
Some people have spent a *lot* of their time on that. Chapeau!
I agree that org-mode could use gentler documentation, but I think
that is by itself a tremendous chore. And then to keep up with all the
improvements that Carsten et all produce at an almost daily rate...
Cheers,
Peter.
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Documentation wishlist items
2009-09-16 9:49 ` Bastien
@ 2009-09-16 14:10 ` Sebastian Rose
2009-09-16 16:03 ` Matt Lundin
0 siblings, 1 reply; 26+ messages in thread
From: Sebastian Rose @ 2009-09-16 14:10 UTC (permalink / raw)
To: Bastien; +Cc: emacs-orgmode
Bastien <bastienguerry@googlemail.com> writes:
> Sebastian Rose <sebastian_rose@gmx.de> writes:
>
>> Here is some kind of outline for such a tutorial.
>
> Wow. That an outline for a full book!
>
> And I guess that's what comes at the horizon: an (O-Reilly) book about
> Org-mode. It would not compete with the manual as a reference, but it
> would make it easier to more people to open Org's doors.
OK, let's just start it. I'd like to have the tutorial on
orgmode.org/worg. But I'm not yet sure about the structure.
Option (A)
is, to create an .../worg/the-org-tutorial/index.org, that just
contains an index to the chapters. Each chapter goes to a single file
in that directory.
Option (B)
Put the entire thing into one big file. This has the advantage, that
we wouldn't need to create any extra directories on worg:
orgmode.org/worg/org-tutorials/the-org-tutorial.org
| | (A) Multiple files | (B) Monolitic |
|----------------------------+--------------------+---------------|
| Outlining a skeleton | - | + |
| Restructure | - | + |
| Multiple editors | + | - |
| Distribution (e.g. as PDF) | - | + |
| Easy navigation | + | - |
|----------------------------+--------------------+---------------|
| Sum | -1 | +1 |
Thoughts?
BTW: The first user in the tutorial is called Allice. I wanted to call
her Trillian, but I'm afraid, people would let her add tasks, that are
not easily understood :-D
The readers are supposed to use their brain to understand Org-mode...
Sebastian
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Documentation wishlist items
2009-09-16 3:34 ` Matt Lundin
2009-09-16 11:37 ` Bernt Hansen
@ 2009-09-16 15:33 ` Ethan
2009-09-16 16:32 ` Matthew Lundin
2009-09-18 15:02 ` org-invoice question Dave Täht
2009-09-18 15:19 ` org-examples.git? Dave Täht
3 siblings, 1 reply; 26+ messages in thread
From: Ethan @ 2009-09-16 15:33 UTC (permalink / raw)
To: Matt Lundin; +Cc: emacs-orgmode
[-- Attachment #1.1: Type: text/plain, Size: 1471 bytes --]
On Tue, Sep 15, 2009 at 11:34 PM, Matt Lundin <mdl@imapmail.org> wrote:
> My guess is that this allows him to see what group an item belongs to in
> the agenda view, since categories are listed in the left column.
>
> But this is like asking why someone puts their pots in the cupboard next
> to the oven rather than above the sink, or why someone uses legal pads
> rather than a spiral notebook.
>
And if you were setting up a kitchen for the first time, wouldn't you ask
that kind of question? :)
> My recommendation: Just start creating trees, use only a few TODO
> states, and allow the organization to evolve in the way that feels the
> most comfortable to you.
>
At the time of this writing, I've stumbled because I have had one file
called TODO which is becoming too cluttered for me to process usefully. I
used C-c C-v to show only TODO items, but some TODO items have ellipses
indicating content while some have ellipses indicating DONE items
afterwards, so I end up expanding a bunch of DONE items. I have a TODO state
called BLOCKING which clutters the view too. I have a vague sense that
learning how to use the agenda would help, but I haven't gotten to it yet,
since I've been trying to put together a coherent org-mode setup by
cargo-culting things from the advanced users' setups. This probably isn't
the best way to go about it, of course..
I thought org-mode level 1 was pretty easy to learn -- but I'm really
struggling to get to level 2.
Ethan
[-- Attachment #1.2: Type: text/html, Size: 1966 bytes --]
[-- Attachment #2: Type: text/plain, Size: 204 bytes --]
_______________________________________________
Emacs-orgmode mailing list
Remember: use `Reply All' to send replies to the list.
Emacs-orgmode@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-orgmode
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Documentation wishlist items
2009-09-16 14:10 ` Sebastian Rose
@ 2009-09-16 16:03 ` Matt Lundin
0 siblings, 0 replies; 26+ messages in thread
From: Matt Lundin @ 2009-09-16 16:03 UTC (permalink / raw)
To: Sebastian Rose; +Cc: Bastien, emacs-orgmode
Sebastian Rose <sebastian_rose@gmx.de> writes:
> Bastien <bastienguerry@googlemail.com> writes:
>> Sebastian Rose <sebastian_rose@gmx.de> writes:
>>
>>> Here is some kind of outline for such a tutorial.
>>
>> Wow. That an outline for a full book!
>>
>> And I guess that's what comes at the horizon: an (O-Reilly) book about
>> Org-mode. It would not compete with the manual as a reference, but it
>> would make it easier to more people to open Org's doors.
>
>
> OK, let's just start it. I'd like to have the tutorial on
> orgmode.org/worg. But I'm not yet sure about the structure.
>
>
> Option (A)
> is, to create an .../worg/the-org-tutorial/index.org, that just
> contains an index to the chapters. Each chapter goes to a single file
> in that directory.
>
> Option (B)
> Put the entire thing into one big file. This has the advantage, that
> we wouldn't need to create any extra directories on worg:
> orgmode.org/worg/org-tutorials/the-org-tutorial.org
>
>
> | | (A) Multiple files | (B) Monolitic |
> |----------------------------+--------------------+---------------|
> | Outlining a skeleton | - | + |
> | Restructure | - | + |
> | Multiple editors | + | - |
> | Distribution (e.g. as PDF) | - | + |
> | Easy navigation | + | - |
> |----------------------------+--------------------+---------------|
> | Sum | -1 | +1 |
>
>
>
> Thoughts?
My vote would be for separate files that could also be published as a
monolithic pdf file. I know the possibility of publishing multiple files
as a single book exists in muse, but how would one do that with
org-mode? Is there a directive to publish separate html files and a
monolithic pdf file simultaneously (perhaps via #+INCLUDE directives)?
- Matt
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Documentation wishlist items
2009-09-16 15:33 ` Ethan
@ 2009-09-16 16:32 ` Matthew Lundin
2009-09-16 18:42 ` tycho garen
0 siblings, 1 reply; 26+ messages in thread
From: Matthew Lundin @ 2009-09-16 16:32 UTC (permalink / raw)
To: Ethan; +Cc: Matt Lundin, emacs-orgmode
Ethan <ethan.glasser.camp@gmail.com> writes:
> On Tue, Sep 15, 2009 at 11:34 PM, Matt Lundin <mdl@imapmail.org> wrote:
>
> My guess is that this allows him to see what group an item belongs
> to in
> the agenda view, since categories are listed in the left column.
>
> But this is like asking why someone puts their pots in the cupboard
> next
> to the oven rather than above the sink, or why someone uses legal
> pads
> rather than a spiral notebook.
>
> And if you were setting up a kitchen for the first time, wouldn't you
> ask that kind of question? :)
Agreed. What I meant by the analogy is that often these times decisions
come down to personal convention/habit. You just start doing things one
way and they stick.
The analogy was in part a reminder to myself to avoid worrying about the
"one right way." :)
As a point of comparison, I divide my files according to area of
responsibility (household.org, health.org, family.org, writing.org,
etc.) so that I can quickly review what I need to do in each area. When
I'm done with an item, I archive it and it is nicely deposited in the
appropriate archive file. If a project within one of these files becomes
quite big, I create a new file for it. I almost never set CATEGORY,
because all my appointments are already organized by category (i.e.,
file name).
>
> My recommendation: Just start creating trees, use only a few TODO
> states, and allow the organization to evolve in the way that feels
> the
> most comfortable to you.
>
> At the time of this writing, I've stumbled because I have had one file
> called TODO which is becoming too cluttered for me to process usefully.
> I used C-c C-v to show only TODO items, but some TODO items have
> ellipses indicating content while some have ellipses indicating DONE
> items afterwards, so I end up expanding a bunch of DONE items.
Is this necessarily a bad thing? If you expand a TODO item with a bunch
of DONE items, it might indicate that you should either 1) create a new
TODO item or 2) mark the parent item as DONE.
> I have a TODO state called BLOCKING which clutters the view too.
Perhaps you could make the BLOCKING state it an inactive todo state in
order to exclude it from the sparse tree view.
#+SEQ_TODO: TODO(t) | DONE(d) BLOCKING(b)
> I have a vague sense that learning how to use the agenda would help,
> but I haven't gotten to it yet, since I've been trying to put together
> a coherent org-mode setup by cargo-culting things from the advanced
> users' setups. This probably isn't the best way to go about it, of
> course..
The agenda is calling you! :)
I wouldn't worry about custom commands until you need them. Just type
type C-c a t or C-c a T "TODO" and you'll get a "clean" list of all your
todos.
Hope this helps.
Matt
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Re: Documentation wishlist items
2009-09-16 16:32 ` Matthew Lundin
@ 2009-09-16 18:42 ` tycho garen
0 siblings, 0 replies; 26+ messages in thread
From: tycho garen @ 2009-09-16 18:42 UTC (permalink / raw)
To: emacs-orgmode
On Wed, Sep 16, 2009 at 12:32:02PM -0400, Matthew Lundin wrote:
>
> As a point of comparison, I divide my files according to area of
> responsibility (household.org, health.org, family.org, writing.org,
> etc.) so that I can quickly review what I need to do in each area. When
> I'm done with an item, I archive it and it is nicely deposited in the
> appropriate archive file. If a project within one of these files becomes
> quite big, I create a new file for it. I almost never set CATEGORY,
> because all my appointments are already organized by category (i.e.,
> file name).
I didn't know there was a category option. I've been using org mode
pretty seriously for the last 9 months or so. I work pretty much like
Matt, but the details differ as does, I think, my thought process, so
I'll share, just because....
I have two general files codex.org and data.org. I've been naming my
general organization file codex for years, so this is a personal
holdover. Data, is my clipping/reference folder (describe here:
<http://www.tychoish.com/2009/09/fact-files/>) and contains various
reference material and citation information for casual things that I
want to be able to capture and reuse later.
The remaining files are either "sphere" files, so I have a file for
each client/employer/work project, I have a "writing" file to manage
my blogging and wiki projects. These files and the trees inside of
them, tend to address ongoing projects and fairly well defined
projects. The outline tends to describe process rather than project.
And then, I have a number of project I have files for specific
projects, creative writing projects, specific research projects,
larger scope things which are the kinds of things that I need to work
on for a while, but eventually finish. These files tend to describe
projects rather than processes, and contain notes and a great deal of
text, but aren't, on the whole "todo lists" as they are outlines that
happen also to support my todo list.
I've always found that org-mode works the best for me when I think of
it more as an outline and data storage tool that happens to generate
todo-lists if there's something actionable around.
> I wouldn't worry about custom commands until you need them. Just type
> type C-c a t or C-c a T "TODO" and you'll get a "clean" list of all your
> todos.
I don't really use custom commands either. I'd recommend playing
around with tags and filtering agendas by tags, and then building on
that as you need to. There is also some crazy-awesome stuff around
using agendas generated from specific files (I think.) but I've also
never touched that.
In any case, I have the following two key bindings set up to do what
Matt suggested above.
(global-set-key (kbd "C-c o a") 'org-agenda-list)
(global-set-key (kbd "C-c o t") 'org-todo-list)
Cheers,
sam
--
tycho(ish) @
garen@tychoish.com
http://www.tychoish.com/
http://www.criticalfutures.com/
"don't get it right, get it written" -- james thurber
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Documentation wishlist items
2009-09-16 9:42 ` Documentation wishlist items Bastien
@ 2009-09-17 3:46 ` Matt Lundin
2009-09-17 17:34 ` Ethan
0 siblings, 1 reply; 26+ messages in thread
From: Matt Lundin @ 2009-09-17 3:46 UTC (permalink / raw)
To: Bastien; +Cc: emacs-orgmode
Bastien <bastienguerry@googlemail.com> writes:
> Hi Ethan,
>
> Ethan <ethan.glasser.camp@gmail.com> writes:
>
>> Another good example is TODO keywords, categories, and tags. It isn't clear
>> what they all are, or why they are distinct, or what the differences are, and
>> it's easy to confuse them with similarly-named but completely distinct concepts
>> like properties.
>
> The manual might enjoy a glossary. ;)
>
> I have created org-glossary.org on Worg, please check it out and add
> your own definitions: http://repo.or.cz/w/Worg.git
O.K. So I went a little crazy and added a bunch of definitions to the
glossary.
- http://orgmode.org/worg/org-glossary.php
Perhaps it's not so much a glossary any more as an shorter introduction
to the basic concepts of org-mode.
My apologies if I ended up repeating details from the manual, but my
goal was to provide the following:
1) a brief definition of each term/concept.
2) a more detailed explanation of what it is and/or how it works.
3) possible uses (e.g., Why might one want to use categories?)
I made a small dent in the list of terms. Please feel free to take up
any of the remaining entries.
Best,
Matt
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Documentation wishlist items
2009-09-17 3:46 ` Matt Lundin
@ 2009-09-17 17:34 ` Ethan
2009-09-17 19:30 ` Matthew Lundin
0 siblings, 1 reply; 26+ messages in thread
From: Ethan @ 2009-09-17 17:34 UTC (permalink / raw)
To: Matt Lundin; +Cc: Bastien, emacs-orgmode
[-- Attachment #1.1: Type: text/plain, Size: 613 bytes --]
On Wed, Sep 16, 2009 at 11:46 PM, Matt Lundin <mdl@imapmail.org> wrote:
> O.K. So I went a little crazy and added a bunch of definitions to the
> glossary.
>
> - http://orgmode.org/worg/org-glossary.php
>
> Perhaps it's not so much a glossary any more as an shorter introduction
> to the basic concepts of org-mode.
>
I just wanted to say thank you! This was amazingly, amazingly helpful.
Just one thought: The section on Archiving says that C-u C-c C-x C-s is an
"alternate version" of the C-c C-x C-s command, but C-u C-c C-x C-s doesn't
archive the current headline but its subtrees.
Thanks again!
Ethan
[-- Attachment #1.2: Type: text/html, Size: 1011 bytes --]
[-- Attachment #2: Type: text/plain, Size: 204 bytes --]
_______________________________________________
Emacs-orgmode mailing list
Remember: use `Reply All' to send replies to the list.
Emacs-orgmode@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-orgmode
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Documentation wishlist items
2009-09-17 17:34 ` Ethan
@ 2009-09-17 19:30 ` Matthew Lundin
0 siblings, 0 replies; 26+ messages in thread
From: Matthew Lundin @ 2009-09-17 19:30 UTC (permalink / raw)
To: Ethan; +Cc: Bastien, Matt Lundin, emacs-orgmode
Ethan <ethan.glasser.camp@gmail.com> writes:
> On Wed, Sep 16, 2009 at 11:46 PM, Matt Lundin <mdl@imapmail.org> wrote:
>
> O.K. So I went a little crazy and added a bunch of definitions to
> the
> glossary.
>
> - http://orgmode.org/worg/org-glossary.php
>
> Perhaps it's not so much a glossary any more as an shorter
> introduction
> to the basic concepts of org-mode.
>
> I just wanted to say thank you! This was amazingly, amazingly helpful.
I'm glad it helped! I think I might add some further reading links to
some of the more important items. For instance, it might be helpful to
Bernt's use of categories to that of Charles Cave, etc.
> Just one thought: The section on Archiving says that C-u C-c C-x C-s is
> an "alternate version" of the C-c C-x C-s command, but C-u C-c C-x C-s
> doesn't archive the current headline but its subtrees.
Fixed it.
Thanks,
Matt
^ permalink raw reply [flat|nested] 26+ messages in thread
* org-invoice question
2009-09-16 3:34 ` Matt Lundin
2009-09-16 11:37 ` Bernt Hansen
2009-09-16 15:33 ` Ethan
@ 2009-09-18 15:02 ` Dave Täht
2009-09-21 17:15 ` Peter Jones
2009-09-18 15:19 ` org-examples.git? Dave Täht
3 siblings, 1 reply; 26+ messages in thread
From: Dave Täht @ 2009-09-18 15:02 UTC (permalink / raw)
To: emacs-orgmode
My eyes glazed over too much to comment directly on the documentation
wishlist thread, and I also saw someone having trouble with org-invoice.
More on the first issue in my next mail.
This was very cool, as I hadn't heard of org-invoice before then.
So I cribbed and modified the org-invoice from the code example and
tried to make it work. I guess it needs the CLOCKSUM properties
generated, which I don't quite know how to do, or something else I am
missing to generate the summaries.
Presentation-wise I have other issues with it, but I'll settle for
making it work first:
--cut--
* Invoices
:PROPERTIES:
RATE: 40.00
** Client Foo
*** DONE Built New Server for Production
CLOSED: [2009-09-18 Fri 08:30]
:LOGBOOK:
- State "DONE" from "STARTED" [2009-09-18 Fri 08:30]
- State "STARTED" from "STARTED" [2009-09-18 Fri 07:00]
CLOCK: [2009-09-18 Fri 07:00]--[2009-09-18 Fri 08:19] => 1:19
:END:
:PROPERTIES:
:Effort: 10
:END:
*** [2009-09-17 Thu] Meeting with Team to Design New System
:PROPERTIES:
WORK: 3:00
:END:
**** Invoice
#+BEGIN: invoice
| Task / Date | Time | Price |
|----------------------------------------+------+-------|
| DONE Built New Server for Production | 0:00 | 0.00 |
|----------------------------------------+------+-------|
| Meeting with Team to Design New System | 0:00 | 0.00 |
| Invoice | 0:00 | 0.00 |
|----------------------------------------+------+-------|
| Total: | 0:00 | 0.00 |
#+END:
* Client Bar
:PROPERTIES:
RATE: 95.00
:END:
*** DONE [2008-01-01 Tue] Searched for Widgets on Google
:PROPERTIES:
RATE: 25.00
WORK: 20:00
:END:
*** [2008-01-02 Wed] Billed You for Taking a Nap
*** Invoice
#+BEGIN: invoice
| Task / Date | Time | Price |
|--------------------------------------+------+-------|
| Tuesday, January 01, 2008 | 0:00 | 0.00 |
| DONE Searched for Widgets on Google | 0:00 | 0.00 |
|--------------------------------------+------+-------|
| Wednesday, January 02, 2008 | 0:00 | 0.00 |
| Billed You for Taking a Nap | 0:00 | 0.00 |
|--------------------------------------+------+-------|
| Total: | 0:00 | 0.00 |
#+END:
--cut--
--
Dave Taht
http://the-edge.blogspot.com
^ permalink raw reply [flat|nested] 26+ messages in thread
* org-examples.git?
2009-09-16 3:34 ` Matt Lundin
` (2 preceding siblings ...)
2009-09-18 15:02 ` org-invoice question Dave Täht
@ 2009-09-18 15:19 ` Dave Täht
2009-09-18 17:00 ` org-examples.git? Matt Lundin
3 siblings, 1 reply; 26+ messages in thread
From: Dave Täht @ 2009-09-18 15:19 UTC (permalink / raw)
To: emacs-orgmode
My eyes glazed over at the documentation thread. Maybe this suggestion
already went by. I can't keep up, sorry.
There are a lot of wonderful tutorials out there, and some great
documentation, but often it requires a fairly high level of
understanding of emacs to solve what's missing or what goes wrong and a
bit of cutting and pasting.
I'm kind of more interested in actual, working examples, that require as
little setup and thought as possible, all collected in one place (like,
org-examples.git or as part of the org-mode git tree), that anyone could
try, use, or edit as a base...
They would range in complexity from the basics to whole-user setups of
org.
It would have some sort of directory structure like this, maybe:
org-examples/invoices-weekly/lisp org-examples/invoices-weekly/org
org-examples/users/dtaht/lisp/org-config.el ;; etc
Now, that would be a good start. What would help more (and I worry if
this is even feasible) would be something like
(org-example foo)
;; which would load the given example and the requisite lisp code for it
;; without messing up the rest of your org configuration.
--
Dave Taht
http://the-edge.blogspot.com
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: org-examples.git?
2009-09-18 15:19 ` org-examples.git? Dave Täht
@ 2009-09-18 17:00 ` Matt Lundin
0 siblings, 0 replies; 26+ messages in thread
From: Matt Lundin @ 2009-09-18 17:00 UTC (permalink / raw)
To: Dave Täht; +Cc: emacs-orgmode
d@teklibre.org (Dave Täht) writes:
> My eyes glazed over at the documentation thread.
I'm afraid my posts may have had something to do with that. :)
> There are a lot of wonderful tutorials out there, and some great
> documentation, but often it requires a fairly high level of
> understanding of emacs to solve what's missing or what goes wrong and a
> bit of cutting and pasting.
>
> I'm kind of more interested in actual, working examples, that require as
> little setup and thought as possible, all collected in one place (like,
> org-examples.git or as part of the org-mode git tree), that anyone could
> try, use, or edit as a base...
Here are a couple of nice places to start:
http://orgmode.org/worg/org-configs/org-customization-guide.php
http://orgmode.org/worg/org-configs/org-customization-survey.php
Best,
Matt
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: org-invoice question
2009-09-18 15:02 ` org-invoice question Dave Täht
@ 2009-09-21 17:15 ` Peter Jones
2009-09-21 17:30 ` Dave Täht
0 siblings, 1 reply; 26+ messages in thread
From: Peter Jones @ 2009-09-21 17:15 UTC (permalink / raw)
To: emacs-orgmode
d@teklibre.org (Dave Täht) writes:
> So I cribbed and modified the org-invoice from the code example and
> tried to make it work. I guess it needs the CLOCKSUM properties
> generated, which I don't quite know how to do, or something else I am
> missing to generate the summaries.
CLOCKSUM properties are generated on the fly from CLOCK lines by
org-mode. The alternative, as you have figured out, is to use a
property called WORK. This is the approach I personally use so that I
can round task times to the nearest 15 minutes.
> Presentation-wise I have other issues with it, but I'll settle for
> making it work first:
>
> * Client Bar
> :PROPERTIES:
> RATE: 95.00
> :END:
> *** DONE [2008-01-01 Tue] Searched for Widgets on Google
> :PROPERTIES:
> RATE: 25.00
> WORK: 20:00
> :END:
> *** [2008-01-02 Wed] Billed You for Taking a Nap
The properties need to begin and end with a colon. Try changing "RATE:"
and "WORK:" to ":RATE:" and ":WORK:".
--
Peter Jones - 303-219-0226
pmade inc. - http://pmade.com
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Re: org-invoice question
2009-09-21 17:15 ` Peter Jones
@ 2009-09-21 17:30 ` Dave Täht
0 siblings, 0 replies; 26+ messages in thread
From: Dave Täht @ 2009-09-21 17:30 UTC (permalink / raw)
To: Peter Jones; +Cc: emacs-orgmode
Peter Jones <mlists@pmade.com> writes:
> d@teklibre.org (Dave Täht) writes:
>> So I cribbed and modified the org-invoice from the code example and
>> tried to make it work. I guess it needs the CLOCKSUM properties
>> generated, which I don't quite know how to do, or something else I am
>> missing to generate the summaries.
>
> CLOCKSUM properties are generated on the fly from CLOCK lines by
> org-mode. The alternative, as you have figured out, is to use a
> property called WORK. This is the approach I personally use so that I
> can round task times to the nearest 15 minutes.
Well, in my case I would rather like to get a rough total via clocksum
so I will play with it. Perhaps CLOCK: also was once upon a time :CLOCK:?
(See below)
>
>> Presentation-wise I have other issues with it, but I'll settle for
>> making it work first:
>>
>> * Client Bar
>> :PROPERTIES:
>> RATE: 95.00
>> :END:
>> *** DONE [2008-01-01 Tue] Searched for Widgets on Google
>> :PROPERTIES:
>> RATE: 25.00
>> WORK: 20:00
>> :END:
>> *** [2008-01-02 Wed] Billed You for Taking a Nap
>
> The properties need to begin and end with a colon. Try changing "RATE:"
> and "WORK:" to ":RATE:" and ":WORK:".
Thank you. That worked better. It even picked up on my LANG variable. Didn't
pick up on the CLOCK line.
* Invoices
:PROPERTIES:
:RATE: 40.00
:END:
** Client Foo
*** DONE Built New Server for Production
CLOSED: [2009-09-18 Fri 08:30]
:LOGBOOK:
- State "DONE" from "STARTED" [2009-09-18 Fri 08:30]
- State "STARTED" from "STARTED" [2009-09-18 Fri 07:00]
CLOCK: [2009-09-18 Fri 07:00]--[2009-09-18 Fri 08:19] => 1:19
:END:
:PROPERTIES:
:Effort: 10
:END:
*** [2009-09-17 Thu] Meeting with Team to Design New System
:PROPERTIES:
:WORK: 3:00
:END:
**** Invoice
#+BEGIN: invoice
| Task / Date | Time | Price |
|----------------------------------------+------+--------|
| DONE Built New Server for Production | 0:00 | 0.00 |
|----------------------------------------+------+--------|
| jueves, septiembre 17, 2009 | 3:00 | 120.00 |
| Meeting with Team to Design New System | 3:00 | 120.00 |
| Invoice | 0:00 | 0.00 |
|----------------------------------------+------+--------|
| Total: | 3:00 | 120.00 |
#+END:
* Client Bar
:PROPERTIES:
:RATE: 95.00
:END:
*** DONE [2008-01-01 Tue] Searched for Widgets on Google
:PROPERTIES:
:RATE: 25.00
:WORK: 20:00
:END:
*** [2008-01-02 Wed] Billed You for Taking a Nap
*** Invoice
#+BEGIN: invoice
| Task / Date | Time | Price |
|--------------------------------------+-------+--------|
| martes, enero 01, 2008 | 20:00 | 500.00 |
| DONE Searched for Widgets on Google | 20:00 | 500.00 |
|--------------------------------------+-------+--------|
| miércoles, enero 02, 2008 | 0:00 | 0.00 |
| Billed You for Taking a Nap | 0:00 | 0.00 |
|--------------------------------------+-------+--------|
| Total: | 20:00 | 500.00 |
#+END:
--
Dave Taht
http://the-edge.blogspot.com
^ permalink raw reply [flat|nested] 26+ messages in thread
end of thread, other threads:[~2009-09-21 17:31 UTC | newest]
Thread overview: 26+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2009-09-15 21:21 Documentation wishlist items Ethan
2009-09-15 23:56 ` Sean Sieger
2009-09-16 3:20 ` Sebastian Rose
2009-09-16 9:46 ` Bastien
2009-09-16 9:54 ` Greg Newman
2009-09-16 10:04 ` timetrap
2009-09-16 12:17 ` Jean-Marie Gaillourdet
2009-09-16 12:56 ` Peter Frings
2009-09-16 9:49 ` Bastien
2009-09-16 14:10 ` Sebastian Rose
2009-09-16 16:03 ` Matt Lundin
2009-09-16 12:46 ` Matt Lundin
2009-09-16 3:34 ` Matt Lundin
2009-09-16 11:37 ` Bernt Hansen
2009-09-16 15:33 ` Ethan
2009-09-16 16:32 ` Matthew Lundin
2009-09-16 18:42 ` tycho garen
2009-09-18 15:02 ` org-invoice question Dave Täht
2009-09-21 17:15 ` Peter Jones
2009-09-21 17:30 ` Dave Täht
2009-09-18 15:19 ` org-examples.git? Dave Täht
2009-09-18 17:00 ` org-examples.git? Matt Lundin
2009-09-16 9:42 ` Documentation wishlist items Bastien
2009-09-17 3:46 ` Matt Lundin
2009-09-17 17:34 ` Ethan
2009-09-17 19:30 ` Matthew Lundin
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).