Re: [O] Citation syntax: a revised proposal

[Thomas S. Dye]

Hi Richard,

Thanks for your thoughtful response.  I had indeed misunderstood the bit
about not being able to export in future versions of Org mode.  Thanks
for the clarification.

However, I'm still 0 because our goals are different.

I want a syntax that recognizes arbitrary citation commands because I
write in Org mode for publication.  You want a syntax that recognizes a
few commands that it might be possible to support in Org mode backends,
some of which are tied loosely, if at all, to publication.  Yours might
be a noble goal that many Org mode users will find useful (I hope it
is!), but I don't think it is (or will be) a syntax useful in my work,
for the following reasons:

1) It is easier for me to have the citation command in one place.  The
decision to represent selected aspects of the citation command in the
syntax and other parts in extensions means that I'd have to learn the
syntax and then remember which aspects were chosen for representation
and which I'd need to develop through extensions of my own.  This is a
lot more work than I do now to get exactly what I want through links.
I'm keen to simplify the authoring process, not make it more complex.

2) Treating footnote citations differently from author-date citations is
a non-starter for me.  When Science turns me away and the editor
suggests that my rant is well suited for another journal, one that
happens to use author-date citations, I'll just search all my citation
links and replace footcite with parencite before exporting the rant to
the suggested journal.  IIUC, with the official Org mode syntax, I'd be
faced with the tedious process of cutting and pasting footnote text back
into the document body.

Also, I'm 0 because there is no need to satisfy me with the official
citation syntax.  I'm able to achieve my goals fully in Org mode without
it.

All the best,
Tom

Richard Lawrence <address@hidden> writes:

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

-- 
Thomas S. Dye
http://www.tsdye.com