CUSTOM_ID vs ID

CUSTOM_ID vs ID

[Nathan Neff]

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

Hello all,

I've often been confused why org-mode has both a CUSTOM_ID
and a ID property.  I mean, why not just use one or the other name?

When would I ever have both an ID and a CUSTOM_ID property for a heading?

Thanks,
--Nate

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

Re: CUSTOM_ID vs ID

[Nicolas Goaziou]

Hello,

Nathan Neff <nathan.neff@gmail.com> writes:

> I've often been confused why org-mode has both a CUSTOM_ID
> and a ID property.  I mean, why not just use one or the other name?

Custom ID are user-defined, and only meaningful in the scope of the
document. Also, they may appear as-is when exported, e.g., as an anchor
in HTML.

ID are (or should be) generated by Org, and are valid across files,
which means they need to be absolutely unique.  

Org keeps track of ID if `org-id-track-globally' is non-nil (the
default). If this is nil, there is almost no difference between ID and
custom ID.

> When would I ever have both an ID and a CUSTOM_ID property for
> a heading?

You may want to refer to a heading from anywhere with id:... but need
a clean anchor in HTML export, for example.

FWIW, I never use ID property.

Regards,

-- 
Nicolas Goaziou

Re: CUSTOM_ID vs ID

[David Masterson]

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> Nathan Neff <nathan.neff@gmail.com> writes:
>
>> I've often been confused why org-mode has both a CUSTOM_ID
>> and a ID property.  I mean, why not just use one or the other name?
>
> Custom ID are user-defined, and only meaningful in the scope of the
> document. Also, they may appear as-is when exported, e.g., as an anchor
> in HTML.
>
> ID are (or should be) generated by Org, and are valid across files,
> which means they need to be absolutely unique.

Can you talk a little bit about how IDs are generated so that they are
absolutely unique?

> Org keeps track of ID if `org-id-track-globally' is non-nil (the
> default). If this is nil, there is almost no difference between ID and
> custom ID.
>
>> When would I ever have both an ID and a CUSTOM_ID property for
>> a heading?
>
> You may want to refer to a heading from anywhere with id:... but need
> a clean anchor in HTML export, for example.

IDs sound like something that would be useful for synchronizing
information between two (or more) separate Org systems - the ID could be
updated whenever a change occurs and then used to determine what needs
synchronization.  True?
--
David

Re: CUSTOM_ID vs ID

[Nicolas Goaziou]

Hello,

David Masterson <dsmasterson@outlook.com> writes:

> Can you talk a little bit about how IDs are generated so that they are
> absolutely unique?

See `org-id-new'. By default, it uses "uuidgen" command.

> IDs sound like something that would be useful for synchronizing
> information between two (or more) separate Org systems - the ID could be
> updated whenever a change occurs and then used to determine what needs
> synchronization.  True?

I think this is different. ID property is meant to never change once
created. If you update it, you lose the reference to the headline, which
defeats the intended purpose.

Regards,

-- 
Nicolas Goaziou

Re: CUSTOM_ID vs ID

[David Masterson]

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> David Masterson <dsmasterson@outlook.com> writes:
>
>> Can you talk a little bit about how IDs are generated so that they are
>> absolutely unique?
>
> See `org-id-new'. By default, it uses "uuidgen" command.
>
>> IDs sound like something that would be useful for synchronizing
>> information between two (or more) separate Org systems - the ID could be
>> updated whenever a change occurs and then used to determine what needs
>> synchronization.  True?
>
> I think this is different. ID property is meant to never change once
> created. If you update it, you lose the reference to the headline, which
> defeats the intended purpose.

Ah. Gotcha.
--
David

Re: CUSTOM_ID vs ID

[Nathan Neff]

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

On Sun, Jul 28, 2019 at 3:10 AM Nicolas Goaziou <mail@nicolasgoaziou.fr>
wrote:

> Hello,
>
> Nathan Neff <nathan.neff@gmail.com> writes:
>
> > I've often been confused why org-mode has both a CUSTOM_ID
> > and a ID property.  I mean, why not just use one or the other name?
>
> Custom ID are user-defined, and only meaningful in the scope of the
> document. Also, they may appear as-is when exported, e.g., as an anchor
> in HTML.
>
> ID are (or should be) generated by Org, and are valid across files,
> which means they need to be absolutely unique.
>

I have a lot of org files and one of the main purposes of links is to be
able to link
to different headings across documents.  This seems to imply I should use
the ID property.

However, I usually *do* manually assign IDs (not CUSTOM_IDs) myself.   The
reason is so I can reasonably search for the ID within my org files and
that the link
ID makes some sense to me.

For example, if I see a link to "id:keyboard_shortcuts" I can tell where
it's going.
Later on, if I want to insert a link to my keyboard shortcuts heading in
another place
in my org files,  I can make a guess of the ID I want to link to.

So, I guess I'm okay manually assigning ID properties, as long as I don't
have conflicts.

Thanks for the explanation!

Thanks,
--Nate




>
> Org keeps track of ID if `org-id-track-globally' is non-nil (the
> default). If this is nil, there is almost no difference between ID and
> custom ID.
>
> > When would I ever have both an ID and a CUSTOM_ID property for
> > a heading?
>
> You may want to refer to a heading from anywhere with id:... but need
> a clean anchor in HTML export, for example.
>
> FWIW, I never use ID property.
>
> Regards,
>
> --
> Nicolas Goaziou
>

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

Re: CUSTOM_ID vs ID

[Richard Lawrence]

Hi Nate,

Nathan Neff <nathan.neff@gmail.com> writes:

> However, I usually *do* manually assign IDs (not CUSTOM_IDs) myself.
> The reason is so I can reasonably search for the ID within my org
> files and that the link ID makes some sense to me.
>
> For example, if I see a link to "id:keyboard_shortcuts" I can tell where
> it's going.

If this is what you want IDs for, then you probably want CUSTOM_ID.
There is built-in Org syntax for links based on CUSTOM_ID: write your
links like [[#some-custom-id]] or [[file:foo.org::#some-custom-id]].

And if you use CUSTOM_ID, then if you ever need ID later (e.g., for
something like org-caldav), you won't have a collision between the two
different properties.

-- 
Best,
Richard

Re: CUSTOM_ID vs ID

[Adam Porter]

Nathan Neff <nathan.neff@gmail.com> writes:

> I have a lot of org files and one of the main purposes of links is to be able to link
> to different headings across documents.  This seems to imply I should use 
> the ID property.
>
> However, I usually *do* manually assign IDs (not CUSTOM_IDs) myself.   The
> reason is so I can reasonably search for the ID within my org files and that the link
> ID makes some sense to me.
>
> For example, if I see a link to "id:keyboard_shortcuts" I can tell where it's going.
> Later on, if I want to insert a link to my keyboard shortcuts heading in another place
> in my org files,  I can make a guess of the ID I want to link to.
>
> So, I guess I'm okay manually assigning ID properties, as long as I
> don't have conflicts.

FYI, you may find the package org-bookmark-heading useful.

Re: CUSTOM_ID vs ID

[Nathan Neff]

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

On Sun, Jul 28, 2019 at 3:10 AM Nicolas Goaziou <mail@nicolasgoaziou.fr>
wrote:

> Hello,
>
> Nathan Neff <nathan.neff@gmail.com> writes:
>
> > I've often been confused why org-mode has both a CUSTOM_ID
> > and a ID property.  I mean, why not just use one or the other name?
>
> Custom ID are user-defined, and only meaningful in the scope of the
> document. Also, they may appear as-is when exported, e.g., as an anchor
> in HTML.
>
> ID are (or should be) generated by Org, and are valid across files,
> which means they need to be absolutely unique.
>
> Org keeps track of ID if `org-id-track-globally' is non-nil (the
> default). If this is nil, there is almost no difference between ID and
> custom ID.
>
> > When would I ever have both an ID and a CUSTOM_ID property for
> > a heading?
>
> You may want to refer to a heading from anywhere with id:... but need
> a clean anchor in HTML export, for example.
>
> FWIW, I never use ID property.
>

Hi Nicolas,

Ah yes, I remember when I was exporting to HTML and would have
both properties.  Thank you.

Also, I think I will stick with ID purely because I want links which
span multiple org mode files.

I also plan to learn some more Emacs Lisp to make this link creation
thing a bit easier.  I know there's been efforts to get org to behave a lot
like a Wiki (which I think it already does):
https://orgmode.org/worg/org-blog-wiki.html

I'd like to mess with Helm and get a custom helm source.  org-insert-link
can already use Helm, but it could be improved a bit.

* Show the IDs (*and* headings :-) of recently created links (because you
know,
the IDs are hash codes (grumble grumble).  Currently Helm just shows the
IDs :-(

* Show a second Helm list of headings (perhaps all headings in org-mode
files)
- If heading already has an ID, then simply use that ID.

* Provide a context menu, where you can choose to create an ID
- Provide a mini buffer to *specify* an ID (evil laugh).  Default action
will
create an ID

Thanks,
--Nate




>
> Regards,
>
> --
> Nicolas Goaziou
>

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

Re: CUSTOM_ID vs ID

[Adam Porter]

Nathan Neff <nathan.neff@gmail.com> writes:

> * Show the IDs (*and* headings :-) of recently created links (because you know,
> the IDs are hash codes (grumble grumble).  Currently Helm just shows the IDs :-(

Small pedantry: they're UUIDs, not hashes.  The distinction is
important, because UUIDs are generated randomly, while hashes are
derived from content.  In fact, nothing prevents UUIDs from being
duplicated except chance (and if you copy a tree, its ID becomes
duplicated in your Org files.)

Re: CUSTOM_ID vs ID

[Jorge P. de Morais Neto]

Hello,

Em 2019-07-28T10:10:01+0200, Nicolas Goaziou escreveu:

> Custom ID are user-defined, and only meaningful in the scope of the
> document. Also, they may appear as-is when exported, e.g., as an anchor
> in HTML.
>
> ID are (or should be) generated by Org, and are valid across files,
> which means they need to be absolutely unique.  
>
>> When would I ever have both an ID and a CUSTOM_ID property for
>> a heading?
>
> You may want to refer to a heading from anywhere with id:... but need
> a clean anchor in HTML export, for example.

Instead of CUSTOM_ID I prefer to use a dedicated target (between double
angular brackets).  This way the link target is conspicuous, which
reduces the chance of me inadvertently removing or moving that heading
and causing dead links.  One disadvantage is that it generates ugly HTML
anchors.  But why does Org not use the dedicated target text as an
anchor?

Regards
-- 
- I am Brazilian.  I hope my English is correct and I welcome feedback
- Please adopt free formats like PDF, ODF, Org, LaTeX, Opus, WebM and 7z
- Free/libre software for Android: https://f-droid.org/
- [[https://www.gnu.org/philosophy/free-sw.html][What is free software?]]

Re: CUSTOM_ID vs ID

[Nicolas Goaziou]

Hello,

Jorge P. de Morais Neto <jorge+list@disroot.org> writes:

> But why does Org not use the dedicated target text as an anchor?

That's because the text could contain anything, including invalid HTML
characters. So we normalize them using only alphanum characters.

Regards,

-- 
Nicolas Goaziou

Re: CUSTOM_ID vs ID

[Jorge P. de Morais Neto]

Hello,

Em 2019-08-18T12:40:29+0200, Nicolas Goaziou escreveu:

> That's because the text could contain anything, including invalid HTML
> characters. So we normalize them using only alphanum characters.

But could not we URL-encode the dedicated target text?  In my testing,
Org generates an ugly anchor even if the dedicated target text is just
"Target".

The current behavior does not harm my current use cases, but I looks to
me it would be simple to improve (for someone familiar with the
codebase) and help some users.  Then again, talk is cheap, so please
just take this as just a suggestion.

Regards
-- 
- I am Brazilian.  I hope my English is correct and I welcome feedback
- Please adopt free formats like PDF, ODF, Org, LaTeX, Opus, WebM and 7z
- Free/libre software for Android: https://f-droid.org/
- [[https://www.gnu.org/philosophy/free-sw.html][What is free software?]]

Re: CUSTOM_ID vs ID

[Nicolas Goaziou]

Hello,

Jorge P. de Morais Neto <jorge+list@disroot.org> writes:

> But could not we URL-encode the dedicated target text?

My example was about HTML, but the same process is used in every export
back-end. URL-encoded strings may also be invalid in other back-ends.

> In my testing, Org generates an ugly anchor even if the dedicated
> target text is just "Target".

"org-XXX" is not "ugly", but functional :)

> The current behavior does not harm my current use cases, but I looks to
> me it would be simple to improve (for someone familiar with the
> codebase) and help some users.

Note that the current behaviour was implemented as an improvement over
the previous solution, to help some users. You may want to dig into the
mailing list archives about it. IIRC, it started out when a Chinese user
reported an issue with targets.

LaTeX back-end uses `org-latex-prefer-user-labels'. HTML could use
a similar mechanism but no one bothered implementing it yet. In any
case, Org provides a robust default solution. I think it is a reasonable
expectation as a default.

Regards,

-- 
Nicolas Goaziou