RE: attachment: link type export to HTML invalid attach dir

["Gustav Wikström" <gustav@whil.se>]

Hi Nicolas,

Thanks for your comments!

> -----Original Message-----
> From: Nicolas Goaziou <mail@nicolasgoaziou.fr>
> Sent: den 19 januari 2020 22:12
> To: Gustav Wikström <gustav@whil.se>
> Cc: emacs-orgmode@gnu.org
> Subject: Re: attachment: link type export to HTML invalid attach dir
> 
> Hello,
> 
> Gustav Wikström <gustav@whil.se> writes:
> 
> > Functionally it's in a good (and maintainable) state right now, in my
> > opinion. But I do understand that the contextual attribute added to
> > the parser may require some discussion.
> 
> This is not my main gripe here, although I'm not convinced that extra
> attribute is warranted. My concern is that you hard-code "attachment"
> type in the parser. I don't think this is the correct way to handle the
> situation.

Ok, noted. To my defense I was thinking more in the terms of subtyping then hardcoding. Because we have multiple link types which try to share an interface. But the interface isn't perfect for all different kinds of links. So it doesn't seem too farfetched that some of those link types would benefit from additional custom properties, specific for those types. =application= and =search-option= for example isn't universally applicable to all link types. And link abbreviations are completely hidden from the parser output, since even the raw-link is expanded. So maybe, in the quest for completion, link abbreviations should have custom properties as well? And allowing some kind of sub-typing might make the parsed output more easy to use, because the interpreter can infer based on type (which already exist as a link property) what extra properties to use.

What I'm trying to argue for here is: Maybe it's not that crazy after all to allow links to have additional properties in the parser based on its type? (While certainly still trying to avoid it if possible!)

> Some link types specifically handle files, e.g., "docview", yet do not
> need a special treatment in the parser. Note that "file" links have a good
> reason to be treated specially there, besides their obvious importance, as
> their type can be omitted. E.g., [[~/file.org]]. OTOH, I see no strong
> reason to handle "attachments" in here, since they behave like any other
> link type.
> 
> Worse, the parser is more or less the definition of the Org syntax.
> Therefore, including "attachment" in the parser is a signal meaning that
> in order to fully implement Org syntax, e.g., in another language, one
> need to support attachment links. Attachment links are undoubtedly useful,
> but they are not core, at all. So, I feel uneasy about leaking that type
> of link in the Element library.
> 
> Also, you sometimes seem to blur, on purpose, the difference between
> "attachment" and "file" links. If there should be no difference of
> treatment between them, as I already suggested, you may want to consider
> "attachment" as some functional link abbreviation. Then the "attachment"
> type doesn't really exist, much like the "bugzilla" link type from the
> manual.

(Off topic) I'm sorry to hear that you think I'm intentionally making things fuzzy. If it seems so, then please take it as a lack of clarity of thought or communication rather than intentional bad will. (/Off topic)

> In any case, we need a proper definition, a proper category too, for
> "attachment" links. Meanwhile, modifying the parser is just grasping at
> straws.
> 
> > I argue that the attachment folder is a part of the attachment link,
> > even though the information is found at a different location in the
> > document (i.e. as a property to nodes in the document hierarchy).
> > Parsing an attachment link would then be incomplete if that
> > information is discarded.
> 
> I argue that the buffer position of the attachment link and the path as
> written in the link are enough to fully expand the attachment file name.

One can indeed use the buffer position to derive the part of the path that comes from the subtree. But leaving it at that puts more requirements on the user of the parsed link in order to use it. Which takes us back to my first implementation of how the exporters would deal with the parsed link information (d70db54dbc).

> If I'm wrong, which could be, I probably didn't invest enough time in the
> Attach changes, then having the expanded form in :path and the initial
> form in :raw-path is enough.
> 
> > One option to adding an attribute could be to modify existing
> > properties by adding the attachment folder to, for example, the path
> > property. But that means to remove information about what was written
> > as path in the original link.
> 
> There is :raw-path for that purpose.

There is no :raw-path available in the properties for a parsed link. If there were we surely wouldn't have this conversation and I'd be using that already! :) I.e. I like this suggestion. I considered using the :raw-link property, but the way it's currently used by the parser (i.e. expanding abbreviations) stopped me. It felt rather like no matter how I tried to utilize the existing parameters I were making an overload with a slightly different meaning. Might have been a lack on my part. In that case, please someone enlighten me! 

> > So I argue to keep path as the original path. But that means extra
> > information is needed to also make it work in the filesystem. If we
> > would translate an attachment link to a file link in ox.el that means
> > we remove the option for exporters to decide for themselves what to do
> > with the link. And I think the exporter should have that option. :)
> 
> Let's first think about what category of object an attachment link belongs
> to. Then we can discuss about how to export it.

So, we're discussing regarding attachment as either: an abbreviation or a proper separate link type? I'm not sure what other options we have? I personally can't categorize it as an abbreviation since that is handled by a separate piece of code with other specifications. I.e. attachment wouldn't fit well inside org-link-abbrev-alist. Attachments should function in the same way as file links, with search options and all. But be limited to the current set of attached files. Which it has completion functionality for when inserting links using C-c C-l. 

> Again, if "attachment" == "file", the exporters shouldn't treat them
> differently. If "attachment" is a new link type, it should define its own
> rules in its own library, namely "org-attach.el".
> 
> > Right now the ASCII exporter for example outputs attachment links as
> > attachment:expanded_path instead of file:expanded_path. Since the link
> > type actually is attachment. And for a solemnly textual export the
> > exported information should be kept as close to source as possible. So
> > either we explicitly and always say attachment-links *are* file-links
> > in disguise (i.e. even change type in the parser), or we don't say
> > that, and then don't say that all the way to the edge of the system.
> > And let the uses of the link type decide themselves what to do. Which
> > is what I propose.
> 
> As I explained above, your proposal is not crystal clear.

Sorry for that...

> My gut feeling is that "attachment" links are just a regular link type,
> that can be opened, and exported, like "file" links. They should live in
> "org-attach.el", using the provided tools to define new link types, like
> almost every other link types do. If those tools are not enough to express
> all the subtleties of "attachment" links, then let's spot the needs and
> improve those tools. That will benefit to every developer that wants to
> implement a new link type, what creating another corner case in the parser
> cannot do.

That's basically the way it was before the patches to fix stardiviners issues. Except not functioning well enough. It would require quite some code in org-attach to replicate existing file links functionality. Mostly code duplication I presume. 

The raw-path option sounds better to my ears. Sub-typing links by saying there are link types which have additional properties feels like a sound option too. I wouldn't regard that as hardcoding.

One improvement I can think of (outside of the discussion above) is to make it possible to pass the argument to org-link-open along to each separate 
link type specialization. That one has bugged me for some time now, when I've wanted to force opening attachment links in emacs but couldn't. Not an issue for attachments any longer (for now I suppose), but all other link types still have that limitation.

Respectfully,
Gustav