Re: [PATCH] oc-csl: Improve LaTeX bibliography formatting

[Ihor Radchenko]

András Simonyi <andras.simonyi@gmail.com> writes:

>> Also, it would be nice to describe CSL usage and tweaks in the manual.
>
> Time permitting I may try to add something, but wouldn't it be a
> problem if the CSL export processor was discussed in much more detail
> than the others?
> I was also thinking about providing a list of available citation
> substyles but I do not want to make the manual very unbalanced.

Maybe not in the release, but otherwise we need to finish the citation
section of the manual one way or another. May as well start from CSL
part.

>> I have two comments here:
>> 1. Where are all these new commands coming from? They are not used
>>    directly in the code. Are you tweaking citeproc.el output this way? May
>>    it be better to use customizations provided by citeproc.el itself?
>
> Yes, the citeproc org-latex formatter, which I added specifically for
> Org, uses these commands in the LaTeX code produced for the
> bibliography. As citeproc doesn't have customizable variables by
> design (if I recall correctly, the only exception is 2 hooks), and
> oc-csl already had some variables concerned with very similar
> formatting settings (org-cite-csl-latex-hanging-indent,
> org-cite-csl-html-hanging-indent,
> org-cite-csl-html-label-width-per-char) I think it is more consistent
> to have the new ones also in Org.

Thanks for the clarification. I'd prefer to see a similar explanation
and the details about what the LaTeX variables/commands do in the
docstring.

>> 2. You are declaring this variable as defcustom, but it is not clear
>>    what is going to happen if the user changes it. It is not how to
>>    change this template in meaningful ways either.
>
> Right, I can try to detail a bit in the docstring what type of
> commands and environments have to be provided by the preamble (are
> expected by citeproc). I tried to follow Timothy's handling of the
> ox-latex engraved preamble, but a simpler alternative would be to
> treat it simply as a constant template, at least for the time being --
> WDYT?

Note that `org-latex-engraved-preamble' explains which packages need to
be loaded and which commands need to be defined in the preamble. This at
least make it more clear what the users may change and not break the
export.

I see not problem keeping this a defcustom, but we definitely need to
explain the default value and what is required to be in there. At least,
to make the code readable for future contributors.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
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>