extensions wrong

[saudiwin]

Just downloaded the template on Mac OS X and when building on Rstudio received an error that the extension path was wrong for the CSL file. I looked at the path and it was indeed incorrect. It should be:

csl: _extensions/christopherkenny/nature/csl/springer-basic-author-date.csl

instead of:

csl: _extensions/nature/csl/springer-basic-author-date.csl

[christopherkenny]

@saudiwin, thanks for the report. If you reinstall, that should be fixed now. Please let me know if it doesn't work as expected.

[cameronraysmith]

I think it's useful to clarify in general that when using the template from this repository it is required to verify and possibly update the path to the desired csl file in the yaml csl field.
@christopherkenny's fix in 5f26bb4 documents the fact that, when you pull this repo in as an extension, it happens to place the csl files we chose to vendor directly from this repo as examples at the path noted in the OP. One currently has to manually specify the relative path to the csl file to be used

nature/README.md

Lines 66 to 68 in d18b5ea

	```yaml
	csl: ./path/to/springer-basic-author-date.csl
	```

I agree the subtle change that is required to render an instance of template.qmd directly in a repository where you import the extension versus what is required for it to work correctly from within this extension development repository has the potential to be quite confusing. Mentioning this explicitly in the template.qmd file's comments in addition to the README.md would be better than assuming the user should receive a broken template.qmd they immediately have to patch in order to successfully render it.

[cameronraysmith]

It might be helpful to update the issue title to reflect that, while obviously confusing, it results from a misunderstanding of/failure to account for in #2 the relationship between the folder structure in a quarto extension repository and the fact that, due to the ability to import many extensions into a single end-user repository, the outcome of executing commands like quarto add christopherkenny/nature is to insert the repository organization name from the repository into the file path. I believe this is designed so that if someone else vendors an extension from otherorg/nature you could theoretically import both. It's probable this is mentioned somewhere in the quarto docs or in various issues in the quarto repositories themselves. We clearly did not account for the confusion this naturally leads to in #2.

[christopherkenny]

Thanks for the input @cameronraysmith.

We did provide that path, but it's already been fixed, so the search of the current state of the repo doesn't turn up anything. However, see that path in use at the time that the issue was opened:

nature/template.qmd

Line 22 in d18b5ea

csl: _extensions/nature/csl/springer-basic-author-date.csl

But yes, the underlying cause is a difference in how the extension is installed/used:

• When working within the extension's repo (i.e. this repo or a fork of it), there is not an organization or author folder
• When installed by path (including locally or by zip folder), there is not an organization
• When installed with quarto add, the recommended way, then there is an organization or author folder

This distinction is documented here. I would not expect most people to have that information ingrained in their mind though and am grateful for the issue, as it helps up improve the extension for all.

All that said, I think the current fixes should be a reasonable resolution here, as they ensure that the extension works no matter the installation method, by moving the use of CSL files (which are optional) to the readme. Of course, this is all assuming that the fix works for people other than me 😄

[cameronraysmith]

Thank you for clarifying @christopherkenny. Apologies for the confusion @saudiwin. However, the template.qmd in this repository is designed to be rendered in the extension repository itself rather than in another repository where the extension is imported. The template.qmd renders in this extension repository where documentation for what is required in an end-user instatiation

nature/README.md

Lines 66 to 68 in d18b5ea

	```yaml
	csl: ./path/to/springer-basic-author-date.csl
	```

or now

nature/README.md

Lines 67 to 69 in 564b6f2

	```yaml
	csl: _extensions/christopherkenny/nature/csl/springer-basic-author-date.csl
	```

should be considered to override the explicit contents of the template from the perspective of using the extension as opposed to developing it. In any case, the general point that this path has to be to the actual path that ends up being instantiated depending on how you work with the repository is clear. I just wanted to make sure the root cause of confusion was documented in the issue and I think #4 (comment) finally clarifies it sufficiently.

The only issue with the current fix that makes natbib the default is that I am not sure how easy it would be, if you do not already know, to figure out how to use citeproc at all, and using natbib is not fully supported by pandoc.

[cameronraysmith]

Taking

The only issue with the current fix that makes natbib the default is that I am not sure how easy it would be, if you do not already know, to figure out how to use citeproc at all, and using natbib is not fully supported by pandoc.

and #5 #7 into account, I proposed to refine the solution to this issue in #6. Perhaps we can continue the discussion there.

[cameronraysmith]

the template.qmd in this repository is designed to be rendered in the extension repository itself rather than in another repository where the extension is imported

Another option could be to place a complete end-user example in a sub-folder, but I think this might lead to dragging around extra copies of files that would decrease the maintainability of this project.

[christopherkenny]

Could you clarify what you mean by this?

However, the template.qmd in this repository is designed to be rendered in the extension repository itself rather than in another repository where the extension is imported

The recommended way to use Quarto is with quarto use or quarto add. These both use the template file to instantiate the end-user's qmd file, so should work under those situations and avoid settings which make that fail, hence the fixes for this issue.

[cameronraysmith]

Yes so if we're not going to

place a complete end-user example in a sub-folder

then you'd need two files (cfcb653, #6 (comment)) or a script to modify the end-user template for rendering it from this extension repo. In either case and in my opinion, it would be better not to couple the solution to the OP's issue to also reverting from the default citeproc to natbib citation method, since, as far as I understand, the latter isn't supported to the same extent by pandoc and would prevent resolution of #5. See also #5 (comment).