Documentation request

Documentation request

[Peter Mao]

[-- Attachment #1: Type: text/plain, Size: 372 bytes --]

The docstrings for org-metadown and org-metaup (and maybe other
context-dependent commands) should reference the corresponding hooks,
org-metadown-hook and org-metaup-hook.

I recently ran into the (happy) situation where M-<down> popped me from an
org-babel code block into the corresponding session, but took a while to
figure out exactly how that was happening.

Peter

[-- Attachment #2: Type: text/html, Size: 463 bytes --]

Re: Documentation request

[Ihor Radchenko]

Peter Mao <peter.mao@gmail.com> writes:

> The docstrings for org-metadown and org-metaup (and maybe other
> context-dependent commands) should reference the corresponding hooks,
> org-metadown-hook and org-metaup-hook.

But they do?

    org-metadown is an interactive and natively compiled function defined
    in org-edit-special.el.
    
    Signature
    (org-metadown &optional ARG)
    
    Documentation
    ...
    
    This function runs the functions in org-metadown-hook one by
    one as a first step, and exits immediately if a function from the
    hook returns non-nil.  In the absence of a specific context, the
    function runs org-metadown-final-hook using the same logic.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: Documentation request

[Peter Mao]

[-- Attachment #1: Type: text/plain, Size: 1267 bytes --]

ah, I failed to mention my version number -- 9.6.15 (which ships with Emacs
29.3).

If it's complete in the latest version, then that's great -- I can wait for
the future to come to me.

Peter

On Mon, Jul 22, 2024 at 6:43 AM Ihor Radchenko <yantar92@posteo.net> wrote:

> Peter Mao <peter.mao@gmail.com> writes:
>
> > The docstrings for org-metadown and org-metaup (and maybe other
> > context-dependent commands) should reference the corresponding hooks,
> > org-metadown-hook and org-metaup-hook.
>
> But they do?
>
>     org-metadown is an interactive and natively compiled function defined
>     in org-edit-special.el.
>
>     Signature
>     (org-metadown &optional ARG)
>
>     Documentation
>     ...
>
>     This function runs the functions in org-metadown-hook one by
>     one as a first step, and exits immediately if a function from the
>     hook returns non-nil.  In the absence of a specific context, the
>     function runs org-metadown-final-hook using the same logic.
>
> --
> Ihor Radchenko // yantar92,
> Org mode contributor,
> Learn more about Org mode at <https://orgmode.org/>.
> Support Org development at <https://liberapay.com/org-mode>,
> or support my work at <https://liberapay.com/yantar92>
>

[-- Attachment #2: Type: text/html, Size: 2007 bytes --]

Documentation request

[Sven Bretfeld]

[-- Attachment #1.1: Type: text/plain, Size: 2835 bytes --]

Hello to all

Org mode is powerful. This well-known, almost trivial, statement
contains a problematic dimension that is so far not solved in neither
the documentation nor in the various howtos all over the web: How do
newbies learn to make optimal use of all it's power?

I read quite a few descriptions of how to use org mode for GTD,
day-planning, even LaTeX-writing. But when reading this list I have
the impression that many members use org mode in a much more creative
way than I can imagine from reading what is to be found on the web.

I'm sure that I don't use the possibilities of org mode in an optimal
way, and that my concept of ordering data and using features is not
the best suitable for me. The major problem is as follows:

- Even if one knows what features are available in org-mode, it's hard
  to imagine what fine things you can actually do with them and how
  they could be used to complement each other in order to build up a
  meaningful overall concept.

In other words, it's a problem of imagination. This might be *my*
problem, but yet I believe that many users will have this same
difficulty, especially the new ones. John Wiegley's and Charles Cave's
howtos are fine and most instructive in this respect, but I have
different needs. I need more of these suggestions in order to pick out
ideas for my own style. On the org mode homepage there are several
descriptions of setups (Lisp code), but AFAIK only these two
explanations of concepts. We had many postings that gave a glimpse on
some concepts, but this is piecemeal.

What I would really like to see -- and now I come to my suggestion --
are some snapshots of org files by other users. What features are they
using and what for? What is the underlying concept of their
organization structure? What I need is the: "Aah, you are doing it
that way ..."

How do you think about making a space on the tutorial page of the org
mode homepage where people can upload example org-files, maybe
together with a short description of their concepts? Of course these
files have to be prepared in order to disguise their personal tasks
and dates, which are (of course) of no concern to the public, but they
should have to be recognizable as snapshots of a work-in-progress
("project A", "project B" isn't very instructive, I think. "Writing
chapter 4 of my dissertation thesis" would be much more informative).

I think this could be a valuable source for ideas how to optimize the
use of org mode, and it could give newbies (as well as experts) a
major clue to orientate themselves in the world of org mode.

I hope this request is not too silly. Of course, I would be willing to
become the first person to submit a file, although I believe that
there is not much to be learned from it.

Thanks for considering my request (and for reading this long message)

Sven

[-- Attachment #1.2: Type: application/pgp-signature, Size: 188 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

Re: Documentation request

[Adam Spiers]

On Sat, Jan 19, 2008 at 06:14:40PM +0100, Sven Bretfeld wrote:
> Hello to all
> 
> Org mode is powerful. This well-known, almost trivial, statement
> contains a problematic dimension that is so far not solved in neither
> the documentation nor in the various howtos all over the web: How do
> newbies learn to make optimal use of all it's power?

[snipped]

> How do you think about making a space on the tutorial page of the org
> mode homepage where people can upload example org-files, maybe
> together with a short description of their concepts? Of course these
> files have to be prepared in order to disguise their personal tasks
> and dates, which are (of course) of no concern to the public, but they
> should have to be recognizable as snapshots of a work-in-progress
> ("project A", "project B" isn't very instructive, I think. "Writing
> chapter 4 of my dissertation thesis" would be much more informative).
> 
> I think this could be a valuable source for ideas how to optimize the
> use of org mode, and it could give newbies (as well as experts) a
> major clue to orientate themselves in the world of org mode.

Hi Sven,

Your request is right on the money; in fact Bastien's already ahead of
you -

 http://search.gmane.org/search.php?group=gmane.emacs.orgmode&query=worg

;-)

It's early days yet for Worg though, so please be patient as people
struggle to find the time to share their own setups with the world.

Adam

Re: Documentation request

[Sven Bretfeld]

[-- Attachment #1.1: Type: text/plain, Size: 605 bytes --]

Hi Adam and all others

From time to time my emails don't reach the list. Maybe I made a
mistake and sent my answer to Adam personally this afternoon.

Adam Spiers <orgmode@adamspiers.org> writes:

> Your request is right on the money; in fact Bastien's already ahead of
> you -
>
>  http://search.gmane.org/search.php?group=gmane.emacs.orgmode&query=worg

In fact, I didn't realize that worg is exactly for that purpose. A
good idea, although the Name reminds me on the MAD Magazine ;-) Thank
you very much, Bastien. I will send you my request for registration
soon.

Greetings

Sven

[-- Attachment #1.2: Type: application/pgp-signature, Size: 188 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

Re: Documentation request

[Sven Bretfeld]

[-- Attachment #1.1: Type: text/plain, Size: 605 bytes --]

Hi Adam and all others

From time to time my emails don't reach the list. Maybe I made a
mistake and sent my answer to Adam personally this afternoon.

Adam Spiers <orgmode@adamspiers.org> writes:

> Your request is right on the money; in fact Bastien's already ahead of
> you -
>
>  http://search.gmane.org/search.php?group=gmane.emacs.orgmode&query=worg

In fact, I didn't realize that worg is exactly for that purpose. A
good idea, although the Name reminds me on the MAD Magazine ;-) Thank
you very much, Bastien. I will send you my request for registration
soon.

Greetings

Sven

[-- Attachment #1.2: Type: application/pgp-signature, Size: 188 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

Re: Documentation request

[Rustom Mody]

[-- Attachment #1.1: Type: text/plain, Size: 4394 bytes --]

On Jan 19, 2008 10:44 PM, Sven Bretfeld <sven.bretfeld@gmx.ch> wrote:

> Hello to all
>
> Org mode is powerful. This well-known, almost trivial, statement
> contains a problematic dimension that is so far not solved in neither
> the documentation nor in the various howtos all over the web: How do
> newbies learn to make optimal use of all it's power?
>

Hear Hear Sven!
I too must confess to increasing depression at the fact that -- in my little
world -- the imminent marriage of GTD with org is far from consummated.  Two
months back I told my friends Give me 2 days of 'leave-me-alone' and I'll
grok this org-thing and soon have my life in order.

2 months on and I am yet to figure out how to match the org notion of agenda
with the corresponding GTD lists.  Not yet figured out how to use
remember... Just 2 examples... Much else that has me at sea...

>
> I read quite a few descriptions of how to use org mode for GTD,
> day-planning, even LaTeX-writing. But when reading this list I have
> the impression that many members use org mode in a much more creative
> way than I can imagine from reading what is to be found on the web.
>
> I'm sure that I don't use the possibilities of org mode in an optimal
> way, and that my concept of ordering data and using features is not
> the best suitable for me. The major problem is as follows:
>
> - Even if one knows what features are available in org-mode, it's hard
>  to imagine what fine things you can actually do with them and how
>  they could be used to complement each other in order to build up a
>  meaningful overall concept.
>

This may be so Sven but I see the problem as more basic:

I never learnt how to be organized
I do not know the intricacies of orgmode
The use of org for organizing (a la GTD or anything else) is clearly a
second order problem


>
> In other words, it's a problem of imagination. This might be *my*
> problem, but yet I believe that many users will have this same
> difficulty, especially the new ones. John Wiegley's and Charles Cave's
> howtos are fine and most instructive in this respect, but I have
> different needs. I need more of these suggestions in order to pick out
> ideas for my own style. On the org mode homepage there are several
> descriptions of setups (Lisp code), but AFAIK only these two
> explanations of concepts. We had many postings that gave a glimpse on
> some concepts, but this is piecemeal.
>
> What I would really like to see -- and now I come to my suggestion --
> are some snapshots of org files by other users. What features are they
> using and what for? What is the underlying concept of their
> organization structure? What I need is the: "Aah, you are doing it
> that way ..."
>

Of course this  would be useful.
Also would be useful to see the lisp setups, makefiles/shell scripts people
are using showing how remember, diary, bbdb and much else hang together

>
> How do you think about making a space on the tutorial page of the org
> mode homepage where people can upload example org-files, maybe
> together with a short description of their concepts? Of course these
> files have to be prepared in order to disguise their personal tasks
> and dates, which are (of course) of no concern to the public, but they
> should have to be recognizable as snapshots of a work-in-progress
> ("project A", "project B" isn't very instructive, I think. "Writing
> chapter 4 of my dissertation thesis" would be much more informative).
>
> I think this could be a valuable source for ideas how to optimize the
> use of org mode, and it could give newbies (as well as experts) a
> major clue to orientate themselves in the world of org mode.
>
> I hope this request is not too silly. Of course, I would be willing to
> become the first person to submit a file, although I believe that
> there is not much to be learned from it.
>
> Thanks for considering my request (and for reading this long message)
>
> Sven
>

Sorry if Ive sounded grumpy.  When I saw the mail talking of the need to
rewrite org-mode I thought I know lisp better than many people and I may
even be able to round up some ex-students of mine to chip in to this
rewrite.
Then I thought-- knowing Scheme is one thing whereas the intricacies of
elisp something else.  Each time the emacs version bumps up I find I
understand it less and less

So for now will have to stay as a user rather than contributor. :-(

[-- Attachment #1.2: Type: text/html, Size: 5376 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

Re: Documentation request

[Carsten Dominik]

On Jan 20, 2008, at 11:20 AM, Rustom Mody wrote:
> Sorry if Ive sounded grumpy.  When I saw the mail talking of the  
> need to rewrite org-mode


Just to be sure - I was not really serious in a practical way.  No  
rewrite in sight.
Very unlikely to happen.

- Carsten