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

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

Hi again,

> -----Original Message-----
> From: Nicolas Goaziou <mail@nicolasgoaziou.fr>
> Sent: den 5 februari 2020 17:54
> To: Gustav Wikström <gustav@whil.se>
> Cc: emacs-orgmode@gnu.org
> Subject: Re: attachment: link type export to HTML invalid attach dir
> 
> > That was kind of what I was trying to do, by allowing subtyping, so
> > that the parser would be more knowledgeable about particular types of
> > links, by allowing extended attributes. Maybe not implemented in the
> > most extensible way though I'll admit.
> 
> Just to be clear, I firmly believe Element library should be as
> low-level as possible. Ideally (we're not there yet), it should not
> depend on any other part of Org. It should be the step (largely) above
> "re-search-forward".

Ok, fair enough. I guess where I was going was a bit further than only parsing the characters, into also interpreting them in meaningful ways. Especially true for attachment links that would need to look up other parts of the tree to fetch extended information. I'll leave that trail of thought. 

> > My suggestion to the link parser would be to have the following properties as the catch-all properties for links:
> > - type :: Which type of link protocol applies. E.g. file, http, ftp, attachment, duckduckgo (ex. for a custom link abbreviation to search ddg)
> > - raw-path :: The path to use for the particular protocol. Would contain everything in the link following "protocol:"
> > - format :: Which format the link has. Plain, bracket or angular bracket
> 
> Barring custom link abbreviations, this is already the case.

Hmm, maybe that is so.. Except raw-path is called path (not really an issue though) and there is another property called raw-link. Not sure how to interpret the use of both path and raw-link. And there are things happening between parsing the actual buffer link and storing the raw-link and path parameters. 

In the end, what made me consider the sub-typing I've been writing about could very well just have been the ambiguities regarding what's what, and the lack of treatment for parts that arguably could be seen as additional parameters to the link-path. For example the "::extra_content" suffix in file links, that by the parser currently is just a part of the path itself. Maybe clearer documentation in the function of what each part is /supposed/ to be, and the design principle that is applied, i.e. that the path is the raw path with options included can help future me and others who might want to understand. Thoughts on that? 

> > - description :: The description part of the link ([[protocol:path][description]])
> 
> Description is not meaningful here. This is parsed content.
>
> > - begin, end, post-blank :: The default properties used for all elements. Not sure if contents-begin and contents-end are a part here as well.
> 
> They are when the link has contents, i.e., a description.

Hmm, don't really know if a link description should be regarded as content. I for one hadn't considered it until now when you mentioned it! But it preserves space in the parse tree I suppose. If the docstring of the link parser would make it clear what each property is supposed to contain, in this case :contents-begin & :contents-end, I'm sure I would have been less confused about this, and wouldn't have had any objections.

> > As you've stated previously, from a performance perspective maybe it
> > will be best to not expand the specific properties and instead let the
> > expansion of those be handled in code by the link type owner (e.g.
> > org-attach.el for attachment links).
> 
> More than performance, this is a design issue.
> 
> > Ah yes. Just briefly looking at the docview code. Docview doesn't seem
> > to use the parser when extracting information about that "go to page"
> > information from the link. Which means docview links doesn't really
> > care how the link information is encoded in the parser anyways.
> 
> Indeed. However, higher level functions, e.g., org-open-link, do care
> about it and ensure that "ol-docview.el" really processes a link.
> 
> > Maybe if docview were allowed to encode custom docview information
> > into the parsed link in the parser it and others could reused that
> > encoded information later? Docview would be able to add
> > a ":go-to-page" option, for example. Just a thought.
> 
> I'm quite sure this is a wrong way to go.

Ok, got it. You're saying the link interpreter for docview (in this case) have to be able to parse the link one step further, to be able to extract this ":go-to-page" information, before being able to operate on it. Indeed a design decision. Maybe the best one, who am I to say otherwise. It will make the Org link parser leaner for sure.

> > Most link types probably won't need custom link properties anyways.
> > But could maybe let the parser know stuff by use of higher order
> > functions? Or push for being important enough to be included into Org
> > and allowed to be known by the parser.
> 
> Only syntax changes can go into the parser. Attachment links are regular
> links, not something that requires extending Org's syntax. Note that
> this is not the case of file links, which have a special syntax, e.g.,
> [[./cat.jpg]].

Sure. 

> > Ok, got it. Thanks for explaining. I'll admit it hasn't been totally
> > clear to me what the best way forward is. After refreshing my
> > understanding on links the conclusion I came to was that link
> > abbreviations in its current form was not a fitting concept for
> > attachment links. Attachments are pretty much similar to file links
> > though, so even if my intention isn't to blur the meaning they will
> > and should be treated very similar, since functionality is so similar.
> 
> Functionality may be familiar, but their syntax is not the same,
> therefore, the differences should be handled elsewhere.
> 
> > Speaking from the perspective of attachment links, if there were
> > a file link type exporter function available that could be used by
> > attachment links without code duplication.
> 
> Where would live that function? ox.el is not an option since every
> exporter treats file links differently.

Not sure about location. Maybe ol.el? What I'm talking about is a higher order function for the :export property within org-link-parameters. File link exporting would then have to be declared using org-link-set-parameters, just as other link types are supposed to be declared for exporting.

> As suggested already (I think) we could add a phase in ox.el that would
> expand attachment links into their file link counterpart automatically.
> This would avoid adding specific code in every export back-end. However,
> export back-end would miss the opportunity to handle attachment links
> specifically. This is one way or the other.

Let's settle with option two for now. As it's defined in the patch.

> > Yes, and the function that implements that would also need the user
> > argument as input. In addition to the link path.
> 
> Patch welcome. I see no objection to extending :follow link parameter in
> "ol.el".

Ok, got it. I'll see what I can come up with.

> > Anyways, patch attached that makes org-element not know about
> > attachments any longer, and moves most of the responsibility to
> > org-attach.el. The exporters still needs to know to use the new
> > function inside org-attach.el though.
> 
> Thank you. Please apply it.

Will do!

> Now we can try improving the situation for exporters.
> 
> Regards,
> 
> --
> Nicolas Goaziou

Thanks!
Gustav