Christian Moe <[email protected]> writes:
> Having spent a little more time with the basic processor, I think the
> manual should also explicitly include the disclaimer from oc-basic.el:
> "this citation processor is meant to be a proof of concept, and possibly
> a fall-back mechanism when nothing else is available. It is too limited
> for any serious use case." Perhaps shortened to: "The =basic= citation
> processor is not meant for serious use, but only as a proof of concept
> and a fall-back mechanism." Without this disclaimer, we set people up for
> disappointment if they try citations right out of the box.
Not sure here. Yes, it is a proof of concept, but it is also the only
built-in processor that works with all export backends.
So, by putting a disclaimer, we are leaving users with no good
alternatives. Also not nice, IMHO.
>>> +- =author= (=a=) :: As default, but suppress the year. Variants:
>>> + =bare=, =caps=, =full=, and all their combinations.
>>> ...
>>
>> Compared to the earlier list with examples, this reads much less
>> clearly.
>
> I'm not sure what you're comparing with here. The list itself was pretty
> much unchanged from my first patch, and it will be the first such list
> to appear in the manual. Perhaps you're referring to the additional info
> I added below it.
I was referring to
- Each citation is surrounded by brackets and uses the =cite= type.
- Each key starts with the character =@=.
: [cite:@key]
- Each key can be qualified by a /prefix/ (e.g.\nbsp{}"see ") and/or
a /suffix/ (e.g.\nbsp{}"p.\nbsp{}123"), giving information useful or
necessary
for the comprehension of the citation but not included in the
reference.
: [cite:see @key p. 123]
After reading that, the new list you added felt less clear because of
missing examples.
> That's my rationale, but your way also makes sense, and the complex
> layout actually looks pretty readable. It compels us to supply examples
> for all items for consistency, though, and that leads to duplication,
> e.g.:
>
>> +- default style =nil= (<omitted>) :: Provide a typical author-date
>> + citation in parentheses.\\
>> [...]
>> +
>> + | =[cite:@dewaal06 p. 5]= | (de Waal et al. 2006, 5) |
>> + | =[cite//bare-caps:@dewaal06 p. 5]= | De Waal et al. 2006, 5 |
>> + | =[cite//bc:@dewaal06 p. 5]= | De Waal et al. 2006, 5 |
>> [...]
>> - =bare-caps= (=bc=) :: Combine =bare= and =caps=.
>> +
>> + | =[cite//bare-caps:@dewaal06 p. 5]= | De Waal et al. 2006, 5 |
>> + | =[cite//bc:@dewaal06 p. 5]= | De Waal et al. 2006, 5 |
>>
> But I can try to deduplicate a bit and add the missing examples, if it's
> your call that we should do it this way.
I left duplicates deliberately in the first list and only in the first
list. Mostly to illustrate // syntax. Maybe we can have a different
example for bare-caps though.
--
Ihor Radchenko // yantar92,
Org mode maintainer,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>
