Trying to get into ScrivQ

[xiamenese]

Hello @bernardo_vasconcelos, @nontroppo and others using ScrivQ.

I am once again trying to get into using a ScrivQ workflow. I’m doing it for two reasons:

1. My Chinese friend and collaborator is coming over here to do a (taught) MPhil in Linguistics, with a view of perhaps continuing to a PhD if possible, so I can imagine that she is going to be needing help with dissertation and perhaps papers for submission. Although she has been using Scrivener for years for translations compiled to DOCX, she might have to produce work with more complex academic elements. I want to get to grips the basics of Scrivener + Quarto in case she might have to use such a workflow. The fact that she is a Windows user is a slight added complication.

2. I’m getting old, and one of the things we are encouraged to do to keep our brains in good working order, is to learn something new… so I have decided that one of those should be a Scrivener + Quarto workflow.

All that said, I installed Quarto; having scanned the ScrivQ template, I thought the best thing would be tp try Compiling it to PDF to give me a fair copy. A ScrivQ.md folder was created and a pane came up saying it was downloading something, though I didn’t clock what. But no PDF was created.

I checked the log file, which said I needed to install Cromium, so I duly did what it said, using terminal quarto install chromium. It seemed to install fine.

I ran the compile again, and half way through Chromium crashed and Scrivener hung. I shut down and today I tried again. Cromium crashed again; I clicked Reload; the crash came up again; I clicked Reload; the crash came up again; I clicked Reload. This time, a (presumably Chromium) window opened onto Google offering me a choice of desktops. I closed it and a few minutes later Preview opened with the PDF saved in the ScrivQ.md folder. Scrivener was hung.

Can any of you help me as to why Chromium might be crashing? I attach the Quarto.log. In it, the only thing that makes any sense to me is that it was looking for the Allegrya font, which I don’t have on my machine. Is that enough to be the cause of the crashing (I don’t know what the font is in the final PDF)?

Quarto.log.zip (2.4 KB)

Thanks

Mark

[bernardo_vasconcelos]

Mark, thanks for giving it a try.

I used to have the same issue with Chromium. It went away by itself after one of the updates, I can’t really say which one. I suggest updating Quarto (perhaps to one of the pre-release versions available at Quarto - Download Quarto) and installing Chromium again.

Also, assuming you could do away with diagrams for now, the problem can be avoided by removing the documents that include diagrams (mermaid or dot diagrams) from Compile.

I hope this helps.

[jpkell]

Bernardo, Do you have a ScrivQ project you could share that features a traditional YAML metadata doc instead of toggling all that in compile? Like maybe one for a standard academic article, rather than a book?

[nontroppo]

@xiamenese

I ran the compile again, and half way through Chromium crashed and Scrivener hung.

Chromium is used for some of the additional features like graphviz/mermaid diagrams IIRC, it is not used for the core functionality[1]. I also see crashes when using my template, though this doesn’t impact the compile (mermaid figures are made, then chromium crashes only as it shuts down; it is a macOS bug with the older version of chromium quarto installs, doesn’t happen in Linux at least).

Don’t compile the sections that use graphviz/mermaid and see if the crash goes (it should).

I wouldn’t worry about it as I doubt you’ll be using mermaid? If you install Chromium yourself (using homebrew etc.) I tink Quarto uses that version and you don’t need the quarto tools version).

@jpkell

Bernardo, Do you have a ScrivQ project you could share that features a traditional YAML metadata doc instead of toggling all that in compile? Like maybe one for a standard academic article, rather than a book?

My original template (on which ScrivQ is based) uses a single metadata file, though this template doesn’t have the document splitting mod Bernardo made. I imagine you can modify Bernardo’s front matter design to use a simple metadata file, though he does quite a few things with his front-matter and may need some input from him. It should be fairly straight forward to also modify my templete to use his script for document splitting if that is what you need.

I think the binder-as-metadata concept ScrivQ uses is very clever and cool conceptally, but it adds a lot of complexity to the compile settings (each YAML level uses a different section etc., lots of settings I never use are still present in the UI) and I personally prefer to use a YAML file.

---

[1] the technology is cool: mermaid is a regular app, and they have compiled it using webassembly, treats the browser as a virtual machine, therefore you don’t need to precompile binaries for different operating systems etc.

[jpkell]

Thank you!

Question about Quarto but not regarding Scrivener: Do you have experience collaborating with others on a Quarto document? I know that rstudio/posit cloud allows for a google-docs-like collaboration. But that requires a paid account. I’m curious about best practices for using rstudio desktop to collaborate with others. Is it as easy as ensuring that only one person at a time is working with an qmd document in (e.g.) Dropbox? (No worries if you don’t have experience with this!)

[xiamenese]

Thank you everyone. I’m in for a steep learning curve.

@jpkell

Bernardo, Do you have a ScrivQ project you could share that features a traditional YAML metadata doc instead of toggling all that in compile? Like maybe one for a standard academic article, rather than a book?

I would find that helpful. I don’t know YAML, but seeing it all in a single file that I can examine would make learning easier. So if anyone has one that I could look at, I’d be really grateful.

@nontroppo

Don’t compile the sections that use graphviz/mermaid and see if the crash goes (it should).

I wouldn’t worry about it as I doubt you’ll be using mermaid? If you install Chromium yourself (using homebrew etc.) I tink Quarto uses that version and you don’t need the quarto tools version).

1. I installed the latest version of Chromium from the repository (not using Homebrew as that has yet more overhead it seems, including having to install x-code and learning how to use the bash shell as currently terminal uses zsh, which Homebrew apparently doesn’t work with!) so it is installed in the standard Applications folder. The Chromium crash still happened when compiling with the diagrams, but this time Scrivener didn’t hang.

2. I unticked the diagram files and there was no crash. You are right, I won’t need mermaid and graphviz diagrams, but I can imagine that Shirley just might… I don’t know the details of her course, what modules it might contain.

I’ve googled the Allegreya font, and downloaded all the variants which I’ll install in the main Fonts folder[1]. Then see what happens, though the Quarto.log mentions .otf and these are .ttf versions. I’ll see what happens.

Mark

P.S. It seems that under these latest versions of MacOS you can’t install fonts into System/Library/Fonts using Font Book, only under ~/user/library/Fonts, so that’s where they’ve gone. I wonder if they can be dragged over into System/Library/Fonts, I’ll try that if necessary.

[bernardo_vasconcelos]

@jpkell, not right now, no. But it should be something easy to achieve. If you export all the documents, then you’ll have all the possible YAML options together in the compiled document. You could paste it back to ScrivQ and use it that way. But the fact that you have it available means that you can always generate such YAML lists.

[bernardo_vasconcelos]

@nontroppo

I think the binder-as-metadata concept ScrivQ uses is very clever and cool conceptally, but it adds a lot of complexity to the compile settings (each YAML level uses a different section etc., lots of settings I never use are still present in the UI)

I fear it has become a bit of a blackbox. The best way to use, I think, is simply to erase unwanted parameters/formats to make the project more lean. If they are needed again, then they can be copied over from a fresh project.

This reminds me that, in the last version, I created some new keywords to mark parameters or documents that had a higher likelihood of causing compilation erros. (These include, of course, font configurations, even if the Alegreya font is sort of covered with the use of the corresponding latex font package and the injection of css to import the font from Google Fonts). And I left some ready-made Collections tied to the keywords to make them easier to access and work it.

I should probably add another Keyword and Collection indicating everything that could be safely erased from the project. Maybe this could help diminish the complexity of having some 500+ parameters staring at the user. When you gaze into the abyss… it does that funny thing.

[nontroppo]

@jpkell

Do you have experience collaborating with others on a Quarto document?

No. But as it is plain text I suspect any git system will work wonders and deal with sync collisions. Falling back to sync alone, then all cavats apply, only one editor at a time…

@xiamenese

I don’t know YAML, but seeing it all in a single file that I can examine would make learning easier. So if anyone has one that I could look at, I’d be really grateful.

Just use my template: Scrivener + Quarto: a technical/academic publishing workflow – the direct template download is here (right-click and “save link as…” or whatever the equivalent is in your browser, then in Scrivener New Project and use Options⇨Import Template...): Scrivener + Quarto.scrivtemplate

@xiamenese

The Chromium crash still happened when compiling with the diagrams, but this time Scrivener didn’t hang.

One step forwards at least…

@xiamenese

not using Homebrew as that has yet more overhead it seems, including having to install x-code and learning how to use the bash shell as currently terminal uses zsh, which Homebrew apparently doesn’t work with!

homebrew really does make lots of things easier on macOS. It doesn’t need xcode, but does need developer tools which automatically get installed as Apple has a mechanism for this.

zsh works perfectly well with brew, no need for bash - in fact my favorite shell is called elvish, and brew works well with that too. I know terminal things can be a bit obtuse at first, but lots of activities become way easier with a little time. I always install brew on a clean mac, then use that to install all my apps in one go, for example imagine manually installing Scrivener, Bookends, pandoc, LateX, fonts, Microsoft word etc, it takes ages. BUT homebrew it is this:

brew install scrivener microsoft-word bookends basictex font-alegreya font-alegreya-sans pandoc pandoc-crossref ruby

I made a script that does all of this for me automagically so I really just run one script on a new mac, and it installs brew then all my other software, and gets my github code all in one go (here for the curious).

@xiamenese

unticked the diagram files and there was no crash. You are right, I won’t need mermaid and graphviz diagrams, but I can imagine that Shirley just might

These are not so commonly used tools, mostly used by computer developers at the cutting edge. Having said that they do make specific kinds of diagrams so much easier to make and maintain, and building diagrams at compile time from editor text is such a neat thing…

@xiamenese

and downloaded all the variants

As I hint at above, with brew this would have been a simple:

brew install font-alegreya font-alegreya-sans

If you’ve never installed a font, then there is a onetime command to add the fonts cask first: brew tap homebrew/cask-fonts

@bernardo_vasconcelos

When you gaze into the abyss… it does that funny thing.

[xiamenese]

@nontroppo

Just use my template: Scrivener + Quarto: a technical/academic publishing workflow – the direct template download is here: Scrivener + Quarto

Ian, thank you so much, this is just what I need. I have trouble with the “direct template download”. If I just click on the link, it comes up in my browser in hex-code; if I right click on it and choose “Save Link As…” it offers .scrivtemplate (the same extension as my “Standard” blank template). However, on trying to import it, although the dialog finds it, it is imported into the appropriate folder with my personal template but doesn’t appear in the Project Templates dialog. If I double click on it, I get this lovely alert!

However, I have downloaded the project and the PDF output. That is just what I need to get going. I can clear out the Manuscript files and those in Research and then save the result as a project template.

Much as I admire Bernado’s template, as he says:

@bernardo_vasconcelos

I fear it has become a bit of a blackbox.
<snip>
When you gaze into the abyss… it does that funny thing.

I’m afraid that is precisely how I feel on looking at it!

Mark

[xiamenese]

@nontroppo

homebrew really does make lots of things easier on macOS. It doesn’t need xcode, but does need developer tools which automatically get installed as Apple has a mechanism for this.

zsh works perfectly well with brew, no need for bash - in fact my favorite shell is called elvish, and brew works well with that too.

Erm, the Homebrew site says:

and without that, whether I cd down into homebrew or not, I get:

mark@xxxxxxx ~ % cd /opt/homebrew
mark@xxxxxxx homebrew % brew tap homebrew/cask-fonts
zsh: command not found: brew
mark@xxxxxxx homebrew %

Mark

[scarlock]

Mark,

If I recall correctly (it’s been a while since I’ve installed Homebrew), bash is needed for the install because the installation script is written in bash. Once installed Homebrew can be used in any shell.

Did you run the /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" command from the Homebrew website to install Homebrew?

[xiamenese]

Thanks. No, I didn’t. Being of advanced age and a long term Mac user who has hardly ever had much to do with Terminal, I took the offered easy route:

I have since installed xCode, which presumably includes the CLT, but I still get the same result. I don’t know how to activate the bash shell; to date for the very limited occasions I’ve used Terminal, it has been of no consequence which shell it is using.

Mark

[scarlock]

Nothing wrong with that. (I’m rapidly approaching advanced age, and I’m a long term Mac user as well [and an even longer term Unix user].)

When you get a chance, would you please open a Terminal window and type the following command and then share the results:

echo $PATH

I’m trying to figure out if the package installer correctly updated the Terminal environment so you can use Homebrew.

Thanks.

[nontroppo]

@xiamenese

However, on trying to import it, although the dialog finds it, it is imported into the appropriate folder with my personal template but doesn’t appear in the Project Templates dialog. If I double click on it, I get this lovely alert!

Yeah, the route to import templates is not very intuitive in Scrivener You need to go to File⇨New Project... and then Options⇨Import Templates... — I hope in a future version @KB can add a double-click import mechanism as templates are such a cool feature…

@xiamenese

Thanks. No, I didn’t. Being of advanced age and a long term Mac user who has hardly ever had much to do with Terminal, I took the offered easy route

Yes, an echo $PATH will tell us why the .pkg route failed… Is shouldn’t have and the command method of installing should always work. You don’t need the whole XCode either, just the command-line tools that can be installed with xcode-select --install pasted into a terminal but now you have XCode it isn’t worth changing this…

[bernardo_vasconcelos]

Mark (@xiamenese), I am pretty sure that, if you open a Terminal (open the Launchpad and type Terminal) window and just paste the command below, Homebrew will be installed (unless I am misremembering) (regardless of zsh or bash).

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Have you tried this route?

[scarlock]

Also, remember that Homebrew installs to /usr/local on Intel Macs, and to /opt/homebrew for Apple Silicon Macs.

[xiamenese]

Thank you all for further help and advice.

@bernardo_vasconcelos: I installed Homebrew using the package they provide on the site, rather than using the command line in Terminal. As I said… getting old (78 this month) and long-term Mac-user (since 1990/91) not having used Unix since 1985, I took the easier (I thought, to me) route.

@scarlock It is installed in /opt/homebrew, I checked by cd’ing into it and tried running brew… from there. As I said, I still got the “command not found” response. What I haven’t said, not that it should make any difference, this is on an M2Pro Mac Mini.

As for trying echo $PATH, I am away from that machine for the next few days, but will try that when I am back in Exeter. I’m pondering whether to install it all on this M1 MBA. Since after a few days in Exeter, we’re going to Cornwall for a week, and the weather is uncertain, so it could be a good idea. If I do, I’ll try installing Homebrew via Terminal and proceed from there.

@nontroppo: (a) That is basically how I tried to install the template, but without starting from File → New…; I had Scrivener running with no project open but the Project Templates dialog open; I’ll try again on this machine. (b) As essentially a Unix tyro, a command like xcode-select --install is very daunting as it gives no idea what is going to be installed, and if I’m then asked for options I would not know what options; if it was xcode-select --install CLT or something like that, it would be more approachable. (c) On that score, I don’t actually know how to stop/quit/kill a process in Terminal; in the Homebrew folder, I tried man homebrew to look for help, but then had to quit Terminal as the only way I knew to end the process. That’s how little knowledge I now have of Unix commands.

I have a lot of learning to do!

Mark

[bernardo_vasconcelos]

Mark, even if you already installed the pkg, you can still copy and paste the command to the Terminal to install Homebrew again. It won’t hurt your Mac in any way shape or form. Just plain copy, paste and enter. Feat not.

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

[scarlock]

I’m almost certain that the issue is the PATH is not set properly. The package installer is fine to use if you are more comfortable with that.

The reason that you haven’t been able to run the command is that for security reasons, the shells no longer will run executables in the current working directory by default. In order to run a file in the current directory you need to put a ./ in front of it, i.e. ./brew after you change your working directory to /opt/homebrew.

The recommended solution to your problem is to add the following line to the .zprofile file in your home directory (creating it if it doesn’t exist - and remember that files starting with a period are “hidden” files and do not show up by default in either finder or with the ls command - use ls -a to see them from the terminal):
eval "$(/opt/homebrew/brew shellenv)"

This will set up all future terminal sessions so the brew command (and anything else installed using brew) is available without having to change directories or remember pathnames. If you don’t want to restart Terminal for that to take effect, you can also run that eval command in your current terminal session as well. (Commands in .zprofile are run every time a new zsh terminal session is started).

The one thing I’m not sure about is how the PATH gets set when Scrivener calls external commands. We may need to update a different file with that eval command, but I’ll let @bernardo_vasconcelos speak to that.