Gustav Wikström <gus...@whil.se> writes:

> 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]].

> 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,

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

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?


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

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


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.

> 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).


Nicolas Goaziou

Reply via email to