emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed

* 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-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  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  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 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  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: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 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  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-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-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  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 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

  • * 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

  • • * 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

  • * 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: 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  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

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).