Re: [O] Citation syntax: a revised proposal

[Nicolas Goaziou]

Richard Lawrence <address@hidden> writes:

> Ah, OK, I think I see...so this is basically the second option, with
> users interpreting subtypes via a separate protocol, instead of via
> filters.  Right?

Correct.

> What about this concern, then?
>
>>> But that kind of situation is exactly what the extra-info part
>>> of the syntax is for; in that case,
>>>
>>>   [cite/my-subtype: ...] 
>>>
>>> would just be an exceptional way of writing
>>>
>>>   [cite: ...]{:type my-subtype}
>>>
>>> or whatever.  I'm not totally convinced yet that the convenience of the
>>> former is worth blurring the line between `stuff that definitely works
>>> on all backends' and `stuff that might not work on all backends'.

I think everything is in the category "stuff that might not work on all
backends". Citations do not even make sense in all back-ends.

> Hmm, OK.  I agree in the abstract, but as far as I understand what a
> `subtype' is, I am not sure how well that idea applies in this case.  If
> a subtype encompasses a set of options, and the only way to specify
> those options is by specifying a subtype, then changing one option means
> changing to a whole different subtype, even when you want all the other
> options to stay the same.  That will lead to a lot of duplication in
> subtypes.  That in turn could lead to a lot of author frustration: now I
> have to remember exactly which subtype encompasses the set of options I
> need for this particular citation.

AFAICT, the most advanced use of citations is Thomas', and he is
basically only using "subtype". So I'm pretty confident that 99.9% of
users will be fine with only these subtypes.

> Look at the LaTeX citation commands.  There, you have a different
> `type'/command for every possible combination of options, and there are
> many commands because there are many options to deal with special cases.
> In my mind, that is the wrong abstraction to emulate.  You end up making
> trips to the manual to figure out exactly which one you need.  
>
> To me, it makes much more sense to have a basic citation command, and
> then a way to `answer some questions' to toggle various things related
> to special-case behavior, like:
>   - should it be footnoted?
>   - should it have special-case capitalization?
>   - should it cite the volume?
>   - should it deal with brackets in a context-sensitive manner?
>   - should it use the genitive form of the author's name?
>   - ...
>
> I would guess that the answers to these questions *usually* have nothing
> to do with one another, so it makes sense to be able to answer them
> independently, and change your answer to one independently of your
> answers to the others.  That's why I would want to be able to write
>
> [cite: ...]{:footnoted t :capitalized t :author-title t ...}
>  
> rather than
>
> [cite/footnoted-capitalized-author-title: ...]
>
> In the former case, if I later figure out I don't need the `:capitalized
> t' part, that's easy to remove without changing the other options.  In
> the latter case, I need to remember what name I gave to the subtype for
> footnoted-but-not-capitalized-author-titles, or whatever.

A good naming scheme can certainly help here. I'd choose

  [cite:FAT:...]

over

  [cite: ...]{:footnoted t :capitalized t :author-title t}

Moreover, we certainly can provide a menu offering the defined subtypes
(with a short summary) for completion.

> I don't know; maybe this is not a very serious concern in practice.
> Maybe, in practice, you generally only need one `special case' option at
> a time, so the number of subtypes will be small.  Still, I do not feel
> comfortable declaring *in advance* that that is so; and the bewildering
> array of LaTeX citation commands is at least some evidence that it
> isn't.  Thus, I am in favor of allowing the greater flexibility provided
> by the former syntax.

In fact, the former syntax provides less flexibility since you declare
/in advance/ what features, or properties, will be supported (or you let
users declare their own keywords, which is even worse).

It doesn't even help users because the handler for "foo" subtype has to
take into account all possible combinations of properties, and so has
"bar" subtype's handler. IOW, handlers become complicated to write.

> That's not to say that subtypes never make sense: you are quite right
> that sometimes options *should* be grouped together into a subtype,
> namely, when it makes sense to set or remove them *conjointly*.  But
> that means the two syntaxes above actually have different purposes, even
> though for some range of cases either one would do the job.

They have the same purpose. Your concern is that one may need a large
number of subtypes. That can be handled by appropriate tools.

> So although I would not be in favor of *only* allowing
>
> [cite/subtype: ...]    
>
> I am basically OK with allowing this if we also allow the {:key val ...}
> syntax.  Still, the /subtype form is not needed if we also allow
>
> [cite: ...]{:type subtype}

Again, I don't think we need {:key val} at the moment. Also, it would be
nice to eschew having once again at least two different ways to write
the same thing (footnotes, links...).


Regards,