emacs-orgmode
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [O] Citation syntax: a revised proposal


From: Richard Lawrence
Subject: Re: [O] Citation syntax: a revised proposal
Date: Sun, 15 Feb 2015 08:40:33 -0800
User-agent: Gnus/5.13 (Gnus v5.13) Emacs/23.4 (gnu/linux)

Hi Tom,

address@hidden (Thomas S. Dye) writes:

> 0
>
> A syntax that relegates citation commands to an extension that might not
> export properly in future versions of Org mode isn't useful in my work.

Sorry to disappoint!  

I tried really hard to represent in the [cite: ...] syntax all the
particular cases of citation commands that people said were important,
including the ones you suggested.  But maybe I missed something, or
maybe you have other suggestions.  If so, I am happy to try again.

It is true that the [cite: ...] syntax does not support specifying an
arbitrary citation command.  The point of this is to keep the number of
features that Org would initially commit to making work in all backends
at a reasonable level, while still encompassing all the important cases.

If you need arbitrary extensions, that is what the %%(...) part of the
syntax is for.  Let me try to clarify what I was thinking about this,
since I didn't say much about it in the proposal.  I don't know if this
will address your concern, but I hope it will at least partly do so.

Basically, I'm thinking of the %%(...) part of the syntax as a kind of
playground; it represents `everything we haven't decided about yet', and
is meant to encompass both user-extensions and backend-specific
extensions.  

If we treat %%(...) as an arbitrary s-expression, then it should already
be flexible enough to allow people who need even the most esoteric
citation commands to implement them via export filters.  But like all
user extensions that execute arbitrary code on arbitrary data, Org is
not in a position to *guarantee* that it will work forevermore.  (For
example, your filter might call an Org function that could one day be
removed or renamed, at which point it will break.)  Hence this warning:

> *At least for now*, any information supplied this way is /strictly the
> user's responsibility/ to interpret (e.g., using an export filter).
> This means that citations that have information like this are not
> portable and might not be exported correctly:
>  - in other users' setups
>  - by particular backends
>  - by future versions of Org

Note that exactly the same warning applies to links with custom types
and similar user extensions, even if the manual is less explicit about
it.  In practice, I expect that the information in %%(...) clauses will
be at least as stable and portable as information in custom links.

(By the way, just to be super clear: `correctly' in the above warning
means `handling the extra information correctly'.  I didn't mean to
imply that even the default export behavior could go awry.)

Eventually, we may find that lots of people have similar needs that they
are dealing with in %%(...) syntax.  At that point, we may want to adopt
stricter conventions for some parts of this syntax.  For example, I
assume we might eventually want a convention that the LaTeX backend will
correctly handle properties that look like:

%%(... :attr_latex (:command "\somecitecommand[%PRE][%POST]{%KEY}") ...) 

Once such a convention is discussed and adopted, Org could then
officially support it, and the above warning would no longer apply,
except the part about other backends.  

Likewise, if we find cases that are important enough that they need to
work on all backends, representations for those cases could be added to
the [cite: ...] part of the syntax.

So really, the idea I had in splitting the syntax into [cite: ...] and
%%(...) was to give us a good starting point that can be built on in the
future -- not to relegate important features to the dustbin.  Sorry that
I did not make that clearer in the proposal!

Best,
Richard




reply via email to

[Prev in Thread] Current Thread [Next in Thread]