Difference between installing and embedding an extension?

[ramiromagno]

Description

Hi Quarto team,

I have just updated the extension I am developing to embed latex-environment instead of having it installed side by side with my own extension. It took me a bit to realize the difference, i.e. I had to see how the directory structure changed: ramiromagno/wiley-njd@033da0f.

If I may give a suggestion, I think you could help your users understanding these nuances by doing three things:

1. Explain that embedding means really installing the dependency under _extensions/<your_own_ext>/_extensions/<ext_dependency>. So, perhaps, stress out, that if you're developing an extension, there should not be any other extensions side by side with your own directly under _extensions/.
2. Educate developers by adding to the READMEs of your flagship templates https://github.com/quarto-journals/, a line below the one:
   Creating a new article with acm:

   quarto add quarto-journals/acm
   

   To install acm as a dependency of your extension run:

   quarto add quarto-journals/acm --embed my/own/ext
   

3. And finally, it is easy to misinterpret the "paths" given in the command:

   quarto add quarto-ext/fancy-text --embed quarto-journals/jss
   

   If I understand correctly, the first, i.e. "quarto-ext/fancy-text" refers to the GitHub repository, whereas "quarto-journals/jss" refers to a local path.

And perhaps try to come up with more specific semantics as "adding", "installing" and "embedding" can have overlapping meanings depending on the context. Ah, I forgot something, it would be nice to have messages printed to the console when adding/embedding an extension, i.e. telling you exactly what is changing in the file system, akin to what the {usethis} package does.

[mcanouil]

Thanks for the feedback!

1. What's not clear in https://quarto.org/docs/extensions/formats.html#extension-embedding?
2. not sure but it could be integrated in the extensions templates when using quarto create extension shortcode
3. This is clearly (I think) stated in https://quarto.org/docs/extensions/formats.html#extension-embedding. Also, https://github.com/quarto-journals/jss is a concrete example of the result.

And perhaps try to come up with more specific semantics as "adding", "installing" and "embedding" can have overlapping meanings depending on the context. Ah, I forgot something, it would be nice to have messages printed to the console when adding/embedding an extension, i.e. telling you exactly what is changing in the file system, akin to what the {usethis} package does.

Concretely, what do you suggest? (PRs are welcomed)

telling you exactly what is changing in the file system

Most extensions are distributed through Git repository, Git provides diff of the changes.

[ramiromagno]

Hey @mcanouil ,

Thank you for your detailed replies.

1. Like I said, it is not clear that when you add an extension it goes under _extensions/ and when you add/embed it goes under _extensions/<your_own_ext>/_extensions/;
2. I missed your point about quarto create extension shortcode... not sure how this is related to my suggestion about making the READMEs more complete by having also an instruction for embedding the extension...
3. To be clear about what I think is not so obvious: --embed quarto-journals/jss --- it is not obvious to me when reading this part of the command for the first time in docs that quarto-journals/jss should refer to a local folder in my computer under _extensions/ and not some remote GitHub repository whose user is quarto-journals and repo is jss.

Regarding the semantics, I don't have a suggestion to give, I'm just giving feedback as a user --- I believe that is welcomed too, not just PRs. But note that if I had the knowledge/time, I'd be glad to contribute.

With regards to my last point about the file system changes, I was perhaps not clear enough. I meant the changes that happen when you install or embed an extension, regardless of whether you're using version control or not. Example:

$> quarto add quarto-ext/fancy-text --embed wiley-njd

Quarto extensions may execute code when documents are rendered. If you do not 
trust the authors of the extension, we recommend that you do not install or 
use the extension.
 ? Do you trust the authors of this extension (Y/n) › Yes
[✓] Downloading
[✓] Unzipping
    Found 1 extension.

The following changes will be made:
Fancy Text   [Install]   1.1.1 (shortcode)
 ? Would you like to continue (Y/n) › Yes

[✓] Extension installation complete.
Learn more about this extension at https://www.github.com/quarto-ext/fancy-text

So it would have been nice to know that a new folder popped up: wiley-njd/_extensions/quarto-ext/fancy-text/.

All of my feedback on Quarto should be regarded as user experience feedback, not like fellow developer's feedback... I guess there is space for that too.

[mcanouil]

From the documentation I pointed out

This will add the quarto-ext/fancy-text extension into the quarto-journals/jss extension in the _extensions folder.

How about adding:

quarto-journals/jss
└── _extensions
    └── jss
        ├── _extensions
        │   └── quarto-ext
        │       └── fancy-text
        └── partials

---

I missed your point about quarto create extension shortcode... not sure how this is related to my suggestion about making the READMEs more complete by having also an instruction for embedding the extension...

From this, I guess you need not create your extension using the template helper from Quarto (see https://quarto.org/docs/extensions/creating.html).

quarto create extension shortcode creates the default scaffolding thus a default README.md file.
To note, I don't particularly agree with the facto to add that much documentation into extension's readme, especially because extension embedding is something advanced as it only concerns users developing extensions after reading the documentation on how to do that.
Adding more into README.md extension is not likely to help users in my opinion.

---

Regarding verbosity, @cscheid and @dragonstyle might already have some idea here.

[mcanouil]

@ramiromagno I made a PR to the documentation to improve the example to embed an extension when developing one and to add the directory from my previous message.

• fix: extension embedding example quarto-web#792

[ramiromagno]

@mcanouil That's really nice, cheers!