Seeking further clarification of org-refile-targets variable

Seeking further clarification of org-refile-targets variable

[Charles Cave]

I am having trouble understanding the help text for org-refile-targets.
I don't know what a "cons cell" is and I would like to see some examples
of customising the variable.

For example, how can I specify headings of levels 1 and 2?
I entered the value of 
(:level . N). 
in the customization prompt but now I get a message
"No refile targets".

Perhaps some examples for non-Lisp programmers would be helpful.

As org-mode popularity increases, the users are not necessarily
Lisp-literate, and I have read messages from users willing to learn
Emacs just to use org-mode! 

Thanks,
Charles

Re: Seeking further clarification of org-refile-targets variable

[Matthew Lundin]

Hi Charles,

Charles Cave <charles_cave@optusnet.com.au> writes:

> I am having trouble understanding the help text for org-refile-targets.
> I don't know what a "cons cell" is and I would like to see some examples
> of customising the variable.
>
> For example, how can I specify headings of levels 1 and 2?
> I entered the value of 
> (:level . N). 
> in the customization prompt but now I get a message
> "No refile targets".
>

I believe you need to substitute a number for N, such as:

(:level . 2:)

But I think the setting you're looking for is:

(:maxlevel . 2:)

As I understand it, the difference between level and maxlevel is that
the level setting only offers level 2 headlines as targets, while the
maxlevel offers both level 1 or level 2 headlines as targets.

I think this is a good candidate for an FAQ entry. I'll put it up on
Worg.

> Perhaps some examples for non-Lisp programmers would be helpful.
>
> As org-mode popularity increases, the users are not necessarily
> Lisp-literate, and I have read messages from users willing to learn
> Emacs just to use org-mode! 

Yes, as a long-time vim user, I was certainly in that category. And I
have to say that your very helpful and accessible tutorials were one
of the first things that drew me to org-mode (and emacs) in the first
place.

Best,

Matt

Re: Seeking further clarification of org-refile-targets variable

[Matthew Lundin]

Matthew Lundin <mdl@imapmail.org> writes:
>
> I believe you need to substitute a number for N, such as:
>
> (:level . 2:)
>
> But I think the setting you're looking for is:
>
> (:maxlevel . 2:)

Oops, that should be:

(:level . 2)

(:maxlevel . 2) 

[Thank goodness for smileys in gnus, which alerted me to my own error.
I'm afraid I'm too used to PmWiki markup, so I tried to close the
opening parenthesis-colon.]

For good measure my own full setting is:

(setq org-refile-targets '((org-agenda-files :maxlevel . 2)))

Best, 

Matt

>
> As I understand it, the difference between level and maxlevel is that
> the level setting only offers level 2 headlines as targets, while the
> maxlevel offers both level 1 or level 2 headlines as targets.
>
> I think this is a good candidate for an FAQ entry. I'll put it up on
> Worg.
>
>> Perhaps some examples for non-Lisp programmers would be helpful.
>>
>> As org-mode popularity increases, the users are not necessarily
>> Lisp-literate, and I have read messages from users willing to learn
>> Emacs just to use org-mode! 
>
> Yes, as a long-time vim user, I was certainly in that category. And I
> have to say that your very helpful and accessible tutorials were one
> of the first things that drew me to org-mode (and emacs) in the first
> place.
>
> Best,
>
> Matt
>
>
> _______________________________________________
> 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: Seeking further clarification of org-refile-targets variable

[Bernt Hansen]

Charles Cave <charles_cave@optusnet.com.au> writes:

> I am having trouble understanding the help text for org-refile-targets.
> I don't know what a "cons cell" is and I would like to see some examples
> of customising the variable.
>
> For example, how can I specify headings of levels 1 and 2?
> I entered the value of 
> (:level . N). 
> in the customization prompt but now I get a message
> "No refile targets".
>
> Perhaps some examples for non-Lisp programmers would be helpful.
>
> As org-mode popularity increases, the users are not necessarily
> Lisp-literate, and I have read messages from users willing to learn
> Emacs just to use org-mode! 

A cons cell is a lisp structure which has two values in parentheses
separated by a dot

  ie. (A . B)

There are functions (car and cdr) which returns the two values in the
cons cell respectively.

The easiest way to modify org-refile-targets is with the customize
interface.

C-h v org-refile-targets RET

then click the "You can _customize_ this variable." link

and then use the buttons to construct the value.

I have this value set as follows:

,----
| org-refile-targets is a variable defined in `org.el'.
| Its value is 
| ((org-agenda-files :level . 1)
|  (nil :level . 1))
`----

where:

  (org-agenda-files :level . 1) specifies all level 1 targets in all
                                of my org files listed in
                                org-agenda-files

  (nil :level . 1)              specifies all level 1 files in the
                                current buffer

Sometimes I work in org-files which are not part of my
org-agenda-files list and I want to be able to refile to level 1 targets
in that file too.

I think you want the following setting:

,----
| org-refile-targets is a variable defined in `org.el'.
| Its value is 
| ((org-agenda-files :level . 1)
|  (org-agenda-files :level . 2))
`----

HTH,
Bernt

Re: Re: Seeking further clarification of org-refile-targets variable

[Matthew Lundin]

Hi Bernt,

Bernt Hansen <bernt@norang.ca> writes:

> Charles Cave <charles_cave@optusnet.com.au> writes:
>
> I have this value set as follows:
>
> ,----
> | org-refile-targets is a variable defined in `org.el'.
> | Its value is 
> | ((org-agenda-files :level . 1)
> |  (nil :level . 1))
> `----
>
> where:
>
>   (org-agenda-files :level . 1) specifies all level 1 targets in all
>                                 of my org files listed in
>                                 org-agenda-files
>
>   (nil :level . 1)              specifies all level 1 files in the
>                                 current buffer
>
> Sometimes I work in org-files which are not part of my
> org-agenda-files list and I want to be able to refile to level 1 targets
> in that file too.

I hadn't realized one could mix and match refile targets. This is very
nice. Thanks for the clarification.

Matt

Re: Re: Seeking further clarification of org-refile-targets variable

[Carsten Dominik]

On Dec 18, 2008, at 3:01 PM, Bernt Hansen wrote:

> Charles Cave <charles_cave@optusnet.com.au> writes:
>
>> I am having trouble understanding the help text for org-refile- 
>> targets.
>> I don't know what a "cons cell" is and I would like to see some  
>> examples
>> of customising the variable.
>>
>> For example, how can I specify headings of levels 1 and 2?
>> I entered the value of
>> (:level . N).
>> in the customization prompt but now I get a message
>> "No refile targets".
>>
>> Perhaps some examples for non-Lisp programmers would be helpful.
>>
>> As org-mode popularity increases, the users are not necessarily
>> Lisp-literate, and I have read messages from users willing to learn
>> Emacs just to use org-mode!
>
> A cons cell is a lisp structure which has two values in parentheses
> separated by a dot
>
>  ie. (A . B)
>
> There are functions (car and cdr) which returns the two values in the
> cons cell respectively.
>
> The easiest way to modify org-refile-targets is with the customize
> interface.
>
> C-h v org-refile-targets RET
>
> then click the "You can _customize_ this variable." link
>
> and then use the buttons to construct the value.
>
> I have this value set as follows:
>
> ,----
> | org-refile-targets is a variable defined in `org.el'.
> | Its value is
> | ((org-agenda-files :level . 1)
> |  (nil :level . 1))
> `----
>
> where:
>
>  (org-agenda-files :level . 1) specifies all level 1 targets in all
>                                of my org files listed in
>                                org-agenda-files
>
>  (nil :level . 1)              specifies all level 1 files in the
>                                current buffer
>
> Sometimes I work in org-files which are not part of my
> org-agenda-files list and I want to be able to refile to level 1  
> targets
> in that file too.
>
> I think you want the following setting:
>
> ,----
> | org-refile-targets is a variable defined in `org.el'.
> | Its value is
> | ((org-agenda-files :level . 1)
> |  (org-agenda-files :level . 2))
> `----

This works well, but faster is:

  ((org-agenda-files :maxlevel . 2))

Because it will do only one pass over all involved files.

- Carsten