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

[Gustav Wikström]

Hi,

> -----Original Message-----
> From: Nicolas Goaziou <address@hidden>
> Sent: den 7 februari 2020 15:28
> To: Gustav Wikström <address@hidden>
> Cc: address@hidden
> Subject: Re: attachment: link type export to HTML invalid attach dir
> 
> > 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.
> 
> There is some normalization involved, indeed. The intent of :raw-link is
> to provide the link almost as it was in the buffer, without any parsing.
> I agree there should not be any `org-link-unescape' and
> `org-link-expand-abbrev' involved there. Something to fix at some point.
> 
> :path, on the contrary is parsed. It is the part of the link between the
> type and the search options, i.e., [[type:path::search]], [[type:path]],
> or [[path]].

Unless search-option applies as a general construct for all link types I don't 
think it should be in the parser. Given the discussion we've had about design 
of the parser from before. I.e. if the parser isn't supposed to know anything 
about the specific types themselves, all properties of the parsed elements have 
to make sense for all types of links. So either search-option remains but is 
parsed in exactly the same way for all link types, or it's not there at all. 
And if it's not available in the parser, the file link interpreters (that still 
might need to be constructed) gets to parse the :search-option from the 
raw-link as it wishes itself. 

Given the above paragraph, the :path and :search-option property doesn't make 
sense in the parser. :raw-link is enough. Less ambiguous names for :path and 
:search-option would be :file-path and :file-search-option. But that's 
sub-typing. We've already concluded that that should not belong to the parser.

> > 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.
> 
> In [[file:name::extra_content]] :path is "name", and :search-option is
> "extra_content". As you noted, :search-option is not valid in non-file
> links, so it belongs to the path.
> 
> It seems there is some friction about this search option part. IIUC, you
> want attachment links to support this link-specific syntax. This is
> indeed not possible. As I commented earlier, letting libraries decide
> what the parser should do is not an option. There are a few options,
> though:
> 
> 1. Allow every link with an explicit type (i.e., not internal links) to
>    have a search option, so you can write [[docview:filename::12]] or
>    [[attachment:filename::*Section 2]]. IMO this is a waste, because
>    most links do not need this, and it could become confusing
>    [[https:www.orgmode.org::#sec2]].
> 
> 2. Provide a function in "ol.el" to do the parsing for you, so that
>    every new link library doesn't have to re-invent the wheel. E.g.,
>    (org-link-extract-search-options "foo::bar") => (:path
>    "foo" :search-options "bar").
> 
> 3. Keep that way, i.e., any link library requiring to read the search
>    part can do a dumb `match-string` and, in two or three lines of code,
>    extract it. IOW, since this is so trivial, why bother?
> 
> WDYT?

I agree that option 1 is suboptimal. :search-option isn't obvious as a property 
for all link types. Since option 3 is fairly trivial, option 2 isn't necessary 
either. For attachment links to reuse the :search-option semantics, without the 
hard-coding we're currently doing, I see one option where attachment link 
higher order functions could reuse file link higher order functions. Those file 
link higher order functions don't exist yet as far as I know.

> > 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?
> 
> There is some information in the manual, and the Org Syntax document.
> 
> > 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.
> 
> This is unrelated to the size of the parse tree.
> 
> A description may contain Org specific markup, e.g., bold, so it needs
> to be parsed further. Therefore, a link with a description is not
> a leaf: it has contents.
> 
> > 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.
> 
> A docstring is not a manual. I explained this in the Org Element API
> documentation, IIRC.

True that. There is a balance to strike. Maybe it's time to pull in the org 
element document into the manual? I vote for that at least.

> > 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.
> 
> Sarcasm?

No, not sarcasm. Sorry for not being more clear. I'm well aware that I'm 
delving in things quite advanced where my prior experience is thin. I can't 
cite articles about best way to work with parsers and interpreters. I can only 
reason to the best of my ability.

> My opinion is the library defining the Org syntax should be a fixed
> point. It is important that the output of the parser does not depend on
> what libraries are currently loaded. It guarantees that if we both open
> the same document, we'll get the same parse tree.
> 
> Of course, this is not exactly true at the moment. For example, we may
> not have the same TODO keywords, or the same item list separator.
> Nevertheless, I see no reason to diverge further from this goal.

Ok, sure. Let the syntax be as rigid as possible, and let extensibility to that 
be dealt with in auxiliary parsing/interpreting functions. I guess that would 
be the approach, put in different words. Still correct?

> > 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.
> 
> See above about my suggestion of a generic tool.
> 
> >> 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.
> 
> Too bad. I still think that first option is more seducing. Transparently
> turning attachment links into file links at export time would prevent
> some headache in exporters out there. It boils down to adding a function
> that transforms "attach" links into "file" links, e.g.,
> `org-export--expand-attachments', and insert it in `org-export-as',
> right after (org-export--remove-uninterpreted-data tree info).

It might be seducing but I'm not sold. I'd rather have an attachment-link 
exporter explicitly reuse functionality for exporting file links than automatic 
translation. For that to be possible, there first is a need for a file link 
exporter function. And the current implementation (since the patch) is good 
enough imo, for now, and until anyone of us does some file link refactoring.

Kind regards
Gustav