Cross-reference throwing error when typesetting to LaTeX

Hi AmberV,

I’ve been searching for a way to reference a chapter from within another chapter, and I found your posting from 2018 regarding ‘Auto-numbering’ and the List of All Placeholders… reference.

I’m a relative newbe and was wondering if there was a more detailed, step-by-step description available about how to implement such a cross reference from one chapter to another, either on Scrivener L&L or elsewhere.

Apologies for the basic nature of the request … my expertise is obviously not in Scrivener, so any help would be much appreciated.

Thanks,
Scrive

Hello, welcome to Scrivener!

I’d say the basics for this are pretty simple: drag the thing that represents your chapter from the binder into the editor to create a hyperlink to it, and when you compile that should be all you need (especially if you’re starting from one of the default templates).

It does depend a bit on how you compile though. For example if the chapter isn’t numbered when you compile, then no numbering will be used in the text reference, of course. There are other options that might get in the way, such as not having internal links enabled in the output (those that use them purely for internal writing reference wouldn’t want them to be exported to readers, for instance).

The way this works is described in §10.1.4, Compiling Document Links, of the user manual PDF. It describes the options you need to have set, and so on. As with most of the manual, it isn’t a basic tutorial however, I would say the best way to learn how this can work simply is to try this experiment:

  1. Create a test project using the “General Non-Fiction” starter template, in the Non-Fiction category.
  2. Paste some junk text into the starter “Section” file of the binder.
  3. Select the Chapter folder above it, and hit ⌘D to duplicate it. Rename the folder to “Example Target”.
  4. Return to the starter “Section”, and drag “Example Target” somewhere into the editor.
  5. Run the File ▸ Compile… command, change the output to Compile for: PDF, and otherwise compile with default settings.

When you examine the output, you should find the link you created has had the readable text modified to “Chapter Two - Example Target”. You will be able to click on this as well, to jump straight to that chapter.

So as you can see, if you start with our prepared setups, you shouldn’t have to do too much! Customisation is very deep though, so you aren’t stuck with any of these results.

Thank you AmberV for the very detailed, very timely instructions. :slight_smile:

I was able to drag the chapter in the binder into the target chapter to create the chapter-to-chapter link.

Unfortunately, the compile threw the following “Runaway argument?” error:

"Runaway argument?
{ (\autoref {scrivauto:133}) for more information. \par \par The seco\ETC.
! File ended while scanning use of @xdblarg.
"

As soon as I deleted the chapter-to-chapter link, the “Runaway argument?” error disappeared.

I also attempted to create a different chapter-to-chapter link between two other chapters to see if the error had something to do with the particular chapters, but a similar “Runaway argument?” error also appeared.

I’m a bit at a loss as the “Remove all hyperlinks” option on the General Options (gear-shaped button) section of compile settings does not exist as an option, and I’m not sure what to do next.

Thank you for all your help,
Scrive

Okay! It helps to know you are using LaTeX, as that is a different way of using Scrivener than the “word processor” way, which is largely what I was describing above. The fundamental use of hyperlinks is the same, but with the LaTeX template the mechanics of a cross-reference are configured with the compile settings themselves—and of course one needn’t worry so much about having Scrivener generate chapter numbering and managing the details of the cross-reference at a technical level, since we have LaTeX to do that sort of busy-work for us.

You can find where this happens in the Markup compile format pane (double-click on the “LaTeX (Memoir Book)” format in the left sidebar to edit). You might wonder where the “scrivauto” label is being created. You’ll find most of these being generated by the Section Layouts themselves. For example, the “Chapter” layout, in the “Prefix” tab, is where the \label is inserted. So you have full control over all of this if need be.

That said, it doesn’t sound to me as though this is any kind of Scrivener-specific issue, but perhaps LaTeX configuration of some sort. It’s hard to say, maybe you don’t have hyperref installed right or something? Adding an autoref to your document shouldn’t normally cause a deep problem like that, but it’s something you could surely do in a text editor yourself if creating a .tex file by hand Scrivener’s involvement is more along the lines of being the thing that “typed” it in for you.

Given the above, maybe the \autoref command isn’t the best for your setup, is there something else you’ve been recommended to use? Keeping in mind how you can change the syntax Scrivener generates, that should be an easy to fix thing if so.

P.S. I’ve split and moved your question to the LaTeX board.

Hi AmberV,

Thank you for responding to my queries. :smiley:

I very much appreciate your efforts to address what should be a rather simple issue. My guess is you’re suspicion regarding my hyperref et al. setup as problematic is correct. I have been focusing on the content of my document far more than the amazing Scrivener tools that have allowed a novice like myself to do as much as I have. That may need to change.

It appears this is a conundrum that needs me to do more research at my end. I so much appreciate your feedback, and I do not want to needlessly solicit your efforts when I need to learn more about Scrivener myself.

FYI, the “Runaway argument?” error is not an uncommon event. The error usually has it’s origin in a syntax error of some sort, like forgetting a \ character before a %. I’m hoping that I can tease out what is causing the “\autoref command” error and move on.

Thank you again for your notes, thoughts and efforts,
Scrive

Hi AmberV,

Following up on my earlier posting, I’ve found the setting that was causing the “Runaway argument?” error when creating chapter-to-chapter cross reference links.

On the compile options “Document Title Links” screen, I’d read somewhere about checking the options to “Update titles in document links with prefix and suffix settings” and for “Links use title prefixes only (exclude titles and suffixes)”. The “Runaway argument?” error I experienced occurs when the second option (“Links use title prefixes …”) is checked. However, the first option also causes some odd behavior with the links, so I’ve UNchecked both options in the compile options screen. Error gone!

The question that remains, however, is whether there is a way for chapter-to-chapter cross reference links to be automatically updated when the chapter title in the binder is changed. I briefly tested this by changing the chapter title in the binder, but the chapter-to-chapter cross reference link did not get updated.

Any thoughts or suggestions to enable automatic updating of the cross reference links would be appreciated.

Thank you for all your help,
scrive :smiley:

Ah yeah, that would normally be good advice if you’re not using an extensive document preparation system on the back-end. If Scrivener is solely responsible for generating a “readable” cross-reference and table of content, then these are handy options. With the LaTeX template they are going to make a huge mess, because we are using the title prefix and suffix to insert code, rather than human-friendly things like “Chapter Twenty-Five”. The code we insert of course is what will ultimately generate human-friendly headings via LaTeX. So that is why the default template settings have that whole pane switched off.

The short answer is that there is a tool for doing so. You can select any number of links in the text, right-click on the selection, and use the “Update Links to Use Target Titles” command. In that case, Scrivener assumes you know what you want and will blow away all hyperlinked text and replace each instance with the binder title it points to.

The long answer is that for an automatic solution, there unfortunately is nothing, though for good reason. Scrivener internally and informally supports two different kinds of cross-reference. There is the sort where you would link from some descriptive text to a section or figure, and the hyperlink can be any text you want for that. The other sort of link is “named”, which happens when the visible hyperlink text precisely matches the binder item it links to. In that case, any modifications the compiler makes to the title will be made to the hyperlink text at each point in the document where it occurs—in accordance with the settings in the Document Title Links pane. This is how you would get “Chapter Twenty-Five: Red Book” in Scrivener’s ToC, when the link itself in the editor just reads “Red Book”.

So in short you don’t actually need that, again because we aren’t using Scrivener to replace what LaTeX already does. It’s going to put the “Chapter Twenty-Five” (or however the document class works) in both places for you, replacing the internal “scrivauto:32” or whatever identifies that heading.

But may see the problem with why they don’t automatically update. An outdated title meant to mention a heading by name is going to be logically ambiguous from any random string of text we might hyperlink to a section with. Scrivener can’t know that at some point in the past, “Red Book” used to be called “Working Title - Red Things”. From its point of view, that’s how we wished to descriptively refer to “Red Book”. So to be clear, the options in Document Titles aren’t going to solve that problem, either. No matter how you use Scrivener, it’s going to assume a hyperlink with a non-matching name is meant to be that way.

However, to again return to the main theme here—in general we don’t have to worry about that though. When I refer to a section in my writings, I never bother with naming it myself in the link, because LaTeX is going to do that for me. I’m going to just write normally, and let the autoref command produce the numbering and naming as I design it in the preamble (or let it use defaults).

The defaults, for Hyperref anyway, simply prints the type of section you are linking to along with its numerical designation. E.g. if this sentence here were to refer to another body of material in the work, I wouldn’t refer to it in my writing, but let the autoref tack on the clickable text for me, which will show up like so (Subsection 12.2.1). The parenthetical markings are added by Scrivener, in the Markup pane, which you can remove if you prefer to embed the reference more naturally in the language of the text.

If you don’t like that approach, then like I say, you can configure autoref to do different things, you can even use another package that is better for how you prefer to make cross-references for the reader, maybe even including the target title and page number. That’s really branching out in pure LaTeX usage though. What you need to know for Scrivener is where to modify the code that gets inserted around links (in Markup), and how sections are identified in Section Layouts.

And of course, if you need a more detailed level of control that homogenous automation doesn’t work well with (where all cross-references look the same), then you can always just type the LaTeX you need right into the editor.

And hopefully you can continue to do so! In my experience, with LaTeX you can usually do well ignoring the details for most of the composition phase. It was after all designed with a similar goal that Scrivener was, to put aside the formatting details until later. But when and if you do want to dip into customisation or figuring out how things are going to work technically, there is going to be a fair bit of tinkering and learning involved. The nice thing is that with both systems, once you find a solution you’re pretty much set, and you can usually go on writing in peace, knowing that when you compile and typeset, it’s all going to come out how you designed it.

Hi AmberV,

Thank you again for your help with cross-references. I am grateful for your help with issues that demonstrate how flexible and powerful Scrivener is.

Thank you for mentioning the “Update Links to Use Target Titles” command, where yet again my lack of familiarity with the full range of Scrivener features is on full display. :blush:

I agree an “automatic update” feature is not necessary. So long as I remember how the “Update Links …” works, that’s all I need. By design, Scrivener is not a spreadsheet program, and LaTeX is not a word processor. Together however, Scrivener and LaTeX provide functionality and flexibility that no spreadsheet or word processor, separate or together, can provide.

Thank you for all your help, and for such complete and timely responses. :smiley:

For now, its back to content …
Scrive