Q: Attachments and IDs?

Q: Attachments and IDs?

[David Masterson]

It's taking awhile to get through my hard head, but I think I'm
beginning to understand the directory structure of attachments.

  org-attach-id-dir/IDx/attachment-file

I don't understand the value of IDx. I would think that "attachment:"
could simply reference 'org-attach-id-dir' (drop 'id'?) unless
overridden by a DIR property.  I think I'm missing something that would
help my understanding of attachments.  Am I?

Is there a section of the Org manual that talks about IDs?

-- 
David Masterson

Re: Q: Attachments and IDs?

[Ihor Radchenko]

David Masterson <dsmasterson@gmail.com> writes:

> It's taking awhile to get through my hard head, but I think I'm
> beginning to understand the directory structure of attachments.
>
>   org-attach-id-dir/IDx/attachment-file
>
> I don't understand the value of IDx. I would think that "attachment:"
> could simply reference 'org-attach-id-dir' (drop 'id'?) unless
> overridden by a DIR property.  I think I'm missing something that would
> help my understanding of attachments.  Am I?

> Is there a section of the Org manual that talks about IDs?

10.2.2 Attachment options

‘org-attach-id-to-path-function-list’
     When ‘ID’ is used for attachments, the ID is parsed into a part of
     a directory-path.  See ‘org-attach-id-uuid-folder-format’ for the
     default function.  Define a new one and add it as first element in
     ‘org-attach-id-to-path-function-list’ if you want the folder
     structure in any other way.  All functions in this list will be
     tried when resolving existing ID's into paths, to maintain backward
     compatibility with existing folders in your system.

For IDs, we use `org-attach-id-uuid-folder-format' by default - it puts
attachments under

<org-attach-id-dir>/<first two letters of ID>/<the rest of ID>/attached-file

-- 
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: Q: Attachments and IDs?

[David Masterson]

Ihor Radchenko <yantar92@posteo.net> writes:

> David Masterson <dsmasterson@gmail.com> writes:
>
>> It's taking awhile to get through my hard head, but I think I'm
>> beginning to understand the directory structure of attachments.
>>
>>   org-attach-id-dir/IDx/attachment-file
>>
>> I don't understand the value of IDx. I would think that "attachment:"
>> could simply reference 'org-attach-id-dir' (drop 'id'?) unless
>> overridden by a DIR property.  I think I'm missing something that would
>> help my understanding of attachments.  Am I?
>
>> Is there a section of the Org manual that talks about IDs?
>
> 10.2.2 Attachment options
>
> ‘org-attach-id-to-path-function-list’
>      When ‘ID’ is used for attachments, the ID is parsed into a part of
>      a directory-path.  See ‘org-attach-id-uuid-folder-format’ for the
>      default function.  Define a new one and add it as first element in
>      ‘org-attach-id-to-path-function-list’ if you want the folder
>      structure in any other way.  All functions in this list will be
>      tried when resolving existing ID's into paths, to maintain backward
>      compatibility with existing folders in your system.
>
> For IDs, we use `org-attach-id-uuid-folder-format' by default - it puts
> attachments under
>
> <org-attach-id-dir>/<first two letters of ID>/<the rest of ID>/attached-file

Hmm. I'm still misunderstanding the *value* of an ID (value in the sense
of why is it useful for me).  This suggests to me that, under
org-attach-id-dir, you could have a tree of attachments, but what is an
example of why that's a good thing (particularly for a newbie)?  Since
the documentation on attachments starts out mentioning an ID, it's
helpful to understand why it's useful.  Basically, I guess the above
mentions "folder structure" without defining what is trying to be
achieved with this more complicated folder structure instead of just one
attachment directory where all attachments are dumped.

-- 
David Masterson

Re: Q: Attachments and IDs?

[Ihor Radchenko]

David Masterson <dsmasterson@gmail.com> writes:

>> <org-attach-id-dir>/<first two letters of ID>/<the rest of ID>/attached-file
>
> Hmm. I'm still misunderstanding the *value* of an ID (value in the sense
> of why is it useful for me).  This suggests to me that, under
> org-attach-id-dir, you could have a tree of attachments, but what is an
> example of why that's a good thing (particularly for a newbie)?
> ... Since
> the documentation on attachments starts out mentioning an ID, it's
> helpful to understand why it's useful.  Basically, I guess the above
> mentions "folder structure" without defining what is trying to be
> achieved with this more complicated folder structure instead of just one
> attachment directory where all attachments are dumped.

You can attach files to multiple headings.
Using the heading ID to construct the attachment location makes sure
that we do not dump all the attachments together.
Isn't it obvious? I am genuinely surprised.

-- 
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: Q: Attachments and IDs?

[David Masterson]

Ihor Radchenko <yantar92@posteo.net> writes:

> David Masterson <dsmasterson@gmail.com> writes:
>
>>> <org-attach-id-dir>/<first two letters of ID>/<the rest of ID>/attached-file
>>
>> Hmm. I'm still misunderstanding the *value* of an ID (value in the sense
>> of why is it useful for me).  This suggests to me that, under
>> org-attach-id-dir, you could have a tree of attachments, but what is an
>> example of why that's a good thing (particularly for a newbie)?
>> ... Since
>> the documentation on attachments starts out mentioning an ID, it's
>> helpful to understand why it's useful.  Basically, I guess the above
>> mentions "folder structure" without defining what is trying to be
>> achieved with this more complicated folder structure instead of just one
>> attachment directory where all attachments are dumped.
>
> You can attach files to multiple headings.
> Using the heading ID to construct the attachment location makes sure
> that we do not dump all the attachments together.
> Isn't it obvious? I am genuinely surprised.

I'm getting old, but I think I'm seeing it now.  I think the word
"entry" in 10.2 threw me for awhile (entry as in a task hierarchy as
opposed to a particular attachment). Maybe an Appendix for these generic
words (entry, ID, header, task, ...) that explains their special meaning
in Org for reference?  Not sure.

Thanks for putting with me.

-- 
David Masterson

Re: Q: Attachments and IDs?

[Ihor Radchenko]

David Masterson <dsmasterson@gmail.com> writes:

> I'm getting old, but I think I'm seeing it now.  I think the word
> "entry" in 10.2 threw me for awhile (entry as in a task hierarchy as
> opposed to a particular attachment). Maybe an Appendix for these generic
> words (entry, ID, header, task, ...) that explains their special meaning
> in Org for reference?  Not sure.

I tried to make things more clear by avoiding "outline node".
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=058aec0f3

Entry may still be confusing, but that's basically an alias to
"heading" and it is used all over the place.

I do not think that we need an appendix - most of the terms are simply
introduced one by one while reading the manual.

-- 
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: Q: Attachments and IDs?

[David Masterson]

Ihor Radchenko <yantar92@posteo.net> writes:

> I do not think that we need an appendix - most of the terms are simply
> introduced one by one while reading the manual.

My problem may be in treating the user's manual as a reference manual.
So, if a term is introduced (and explained) in another section(s) that I
didn't think applied to my particular issue, I might not see it or even
know where to look for it without reading the whole manual.  Coupled
with fading memory, I forget what I read a few months ago that might
apply.  The appendix idea was simply to get all the key terminology in
one area (which could then reference out to other sections in the
manual) like Main Index.  Wait a sec -- Main Index?  I hadn't really
thought about that before, but I think that's what I meant by appendix.

Duh.  Thanks for putting *up* with me.

-- 
David Masterson

Re: Q: Attachments and IDs?

[Daniel Fleischer]

You can override the ID generation and the ID-to-path function to create
an attachment hierarchy of your liking, e.g.

ATTACH-DIR/year/month-day/*files*

Checkout `org-attach-id-to-path-function-list' and `org-id-new'.

Daniel

Re: Q: Attachments and IDs?

[David Masterson]

Daniel Fleischer <danflscr@gmail.com> writes:

> You can override the ID generation and the ID-to-path function to create
> an attachment hierarchy of your liking, e.g.
>
> ATTACH-DIR/year/month-day/*files*
>
> Checkout `org-attach-id-to-path-function-list' and `org-id-new'.

Thank you.  That gives me some ideas.

-- 
David Masterson