Set better default values for references on IEEE template

[swhaat]

• IEEE template works by default with biblatex, it makes sense to use it as a default on the Rmd file so that users can benefit directly from its usage.
• As the package biblatex is used, the options style=numeric and sorting=none are unnecessary, as these parameters are the default for references on the IEEEtran.bst which is shipped with the ieee template., and its used when creating the references style.
• A consequence of biblatex is the citations have to be used in native latex form \cite{...}, as pandoc conversion will create \autocite or \textcite..
• biblio-title is removed as the references title can be defined directly on the Rmd file, because the references will be appended at the end of the file.

[swhaat]

I do want that the IEEE template uses biblatex as a default, but taking a look a it now, i think the biblatex entry on the Rmd seems a bit hacky... I will investigate further why the citation_package = "biblatex" does not behave correctly and will amend this request to a more standard solution

[swhaat]

As the idea is to use biblatex as a default I modified the template.tex so that if the user gives a bibliography file, it then uses biblatex with that file as a default.

[DunLug]

Hello everyone, This PR seems ok to me, and keeping the IEEE template as simple as possible is a good idea for scientifics with basic computer science knowledge. I wonder if the natbib option use would work correctly, or have some side effects with these modifications. Maybe the natbib usage could be removed if biblatex is good enough for IEEE papers. Finally, I would suggest to customize the markdown reference conversions ([@citation] or @citation) to produce \cite commands. I don't know if it is possible but it could be nice to keep rmarkdown document as clean as possible.

[swhaat]

I have generally met people that use biblatex for their papers, that is why i suggested that we make it a standard.. i do confess not to try natbib, so im unaware of the results... Regarding the @citation usage, as i said pandoc does not convert @citation to \cite{}, but rather to \textcite{} or \autocite{}, which might be problematic when using xelatex or in some cases pdflatex.. so i opted to use the direct version of \cite{} which doesnt need pandoc translation and it would just work as one might expect... I also support to keep the rmakrdown as clean as possible, but in this case, or unless someone has another workaround i would keep the \cite{}, so that the template works out-of-the-box, and people can directly start to write their content...

[DunLug]

I made some research about a way to convert pandoc citation syntax to \cite{} commands. It seems that it is not possible easily so it's better to stay with raw latex \cite commands for now. A quick-and-dirty trick could be to renew \autocite and \textcite commands in template to have \cite behaviour but I don't know if this could create unwanted effects.

About natbib / biblatex, it seems that there're two options : natbib defined with biblio-style, biblio-files, biblio-title options bibliography defined (list of bibliographic ressources) that trigger biblatex If we consider keeping natbib, maybe these modifications could improve clarity :

• use of a single option for the citation engine with natbib or biblatex values
• use of a single field for bibliography / biblio-files
• use biblio-style and biblio-title for both engine if needed, or remove them

[DunLug]

I made some quick tests about my previous post. I added : rmarkdown::render('input_file.Rmd', rticles::ieee_article('final', pandoc_args=c('--biblatex'))) to disable citeproc filter and add --biblatex option. This should be possible using yaml header parameter citation_package but I didn't find how.

Then, this generates a tex file with [@test] and @test \autocite and \textcite commands. To consider them as \cite command I've added renewcommands in the skeleton file: ` \renewcommand{\autocite}{\cite} \renewcommand{\textcite}{\cite}

\begin{document} `

The issues with this method are:

• The --biblatex option is given at hand to the function call. It could be interesting to make all processing pipeline using one citation_package
• I don't know how to make multiple citations as with \cite{test1,test2} using markdown syntax
• The bibtex bbl file isn't generated so users needs to create pdf file using pdflatex, bibtex and pdflatex twice

[swhaat]

to add bibllatex to the file just:

output:
  rticles::ieee_article:
    citation_package: biblatex

the renew command does seem pretty hacky, but the compatibility might be an issue.. if pandoc translates the @citation to something other than \textcite or \autocite.. then more renew commands will have to be added.. seems to require too attention to what pandoc might do.. I think the raw \cite{} serves a better global solution even thought it doesnt look as polished as plain markdown, but it will probably create less compatibility issues

[DunLug]

About the renew command, I consider that forcing pandoc to convert [@cite] to \cite would be great, while rticles users are not necesseraly aware of the need to use \cite command. For now, it's effectively not needed to bother ourselves with this issue.

I've checked pandoc documentation again and I think that there is an elegant way to choose between natbib and biblatex behaviour, using pandoc options:

pandoc -t latex --bibliography=biblio1.bib --bibliography=biblio2.bib --biblatex -V biblio-title:Titre -V biblio-style:numbered -V biblatexoptions:sorting=none file.md

This allows to simplify the template with all work made on pandoc side. But this would probably need another pull request.

@yihui After discussion I'm OK with this merge 👍

[umarcor]

FTR:

• https://tex.stackexchange.com/questions/201582/natbib-ieeetran-and-alphanumeric-citation-is-there-an-ieeetransan-style-availa/244651#244651
• https://tex.stackexchange.com/questions/202963/how-to-cite-author-in-ieee-format/202964#202964

Hence, to make the transition easier, I would suggest setting \usepackage[backend=bibtex,style=ieee,natbib=true]{biblatex} by default. Would that allow to use [@ref] for preserving compatibility with other outputs (HTML, EPUB, etc.)?

Regarding bibtex vs biber as backend, in this bookdown document/project, biblatex and ieee.cls are defined. That installs biber: https://github.com/LarsAsplund/github-facts/runs/962397200?check_suite_focus=true#step:3:1247. However, I don't know whether it is actually used.

[umarcor]

• biblio-title is removed as the references title can be defined directly on the Rmd file, because the references will be appended at the end of the file.

@swhaat, this conflicts with bookdown-demo, where the 'References' title is shown for HTML output only: https://github.com/rstudio/bookdown-demo/blob/master/06-references.Rmd. Moreover, depending on the output, the word might change between 'References' (article) and 'Bibliography' (report or book); hence, users would need to work around it.

[cderv]

@swhaat What is the status on this PR ? do you plan to work on it again or is it ready for you ?

[swhaat]

As we had discussed with @DunLug it was about how pandoc translates the @ref into \textcite or \autocite.. and this is behavior could lead to errors as some latex processors do not like those \XXXXcite commands. And if the user just uses direct \cite this is no longer a problem because pandoc just process it as it is..

so, @cderv after the agreement and discussion with @DunLug this PR was/is ready.

[cderv]

I see that the template is using the \cite package. Currently it is note by default. https://github.com/rstudio/rticles/blob/623fb4668d798620a05da87495b74f4ecf501d11/inst/rmarkdown/templates/ieee_article/resources/template.tex#L95-L114

If we activate biblatex by default, then if I set with_cite: true for this format. I'll get an error.

! Package biblatex Error: Incompatible package 'cite'

(We got the same type of error if we activate natbib - see https://github.com/rstudio/rticles/pull/269#discussion_r472012525)

For citation, this package is mentioned to be used with IEEEtrans : http://www.ctan.org/tex-archive/macros/latex/contrib/IEEEtran/IEEEtran_HOWTO.pdf and because IEEEtrans contains a bibliography style that work well with this (per the doc)

I am mainly new to this as I discover this issue but I am wondering: why use natbib or biblatex, and even make biblatex the default here ? It does not seem to be part of the template.

[DunLug]

@cderv I didn't use the cite package and I don't have enough knowledge about it. However, the \cite command doesn't need the cite package to be included so it doesn't conflict with using biblatex or natbib packages. If the cite package is relevant in the IEEE documents redaction, we should probably modify the code again to let the user choose between natbib, biblatex and cite options. This could however forbid the merging for the moment.

[cderv]

However, the \cite command doesn't need the cite package to be included so it doesn't conflict with using biblatex or natbib packages.

I just tested by activating the provided option with_cite and it conflicts with biblatex if included by default. with_cite is part of the template already so if anyone is using it (i.e setting to TRUE), I think it will break.

[CLAassistant]

All committers have signed the CLA.

[swhaat]

hi @DunLug and @cderv.. i had to use this template again so i thought i give it a try again..

i tried the with_cite option with the default template, and it does not actually work as it is described on the template, references are listed as they were listed before, by name, and not as the documetnation says, with numbers e.g. [1],[2].

So it either has been broken all along or it wasnt used so much that people realized it, either case, to me, it makes more sense to try and remove this option as it, in reality, should not break anyones files, as the results are not what they are supposed to be.

[cderv]

So I tried to catch up with this PR and the initial issues it tried to solve. Here is my understanding:

• cite package is not compatible with biblatex package. So it is one or the other. With Pandoc, it is either natbib or biblatex, if no pandoc citeproc is used. This means biblatex can be use this way

  utput: 
   rticles::ieee_article:
     citation_package: biblatex
  

  This will activate the biblatex part of the template. I adapted the options so that none is provided by default, but it can be modified using biblio-style, citation-sorting and biblatex-options fields

  If \cite{} is desired, it can be used in the document instead of Pandoc's @ syntax. Example:

   Acknowledgment {#acknowledgment}
  
  he authors \cite{Feynman1963118} would like to thank...
  
   Bibliography styles
  
  ere are two sample references: \cite{Feynman1963118,Dirac1953888}.
  

• biblio-title is here if anyone needs to customize the title. It should not create duplication as by default, the last header with nothing below in the document will be used.

• If natbib is prefered it can be used the same way. citation_package: natbib. The support is now fixed.

• with_cite: true is only needed if the bibliography part is handle manually - no Pandoc's processing at all and bibliography added manually. The cite package conflicts with other options so it needs to be used on its own. (include latex command for bibliography

I did the changes in #530. I am closing this one.