Scrivener3 + LaTeX for the LaTeX newbie

User avatar
rdale
Posts: 1156
Joined: Tue Jul 14, 2015 1:07 pm
Platform: Mac, Win + iOS
Location: St. Louis, MO
Contact:

Wed Feb 14, 2018 9:48 pm Post

I discovered a nifty LaTeX template that I want to use for compiling a new project, but I'm struggling with the LaTeX functions being escaped in the output. I'm getting the pretty "old parchment" background that's part of the template, so I'm pretty sure I've got everything installed correctly, including the preamble in Scrivener, and I've tested everything in MacTex, so I know that stuff is working.

I'm trying to use custom styles to simulate the final output look. I've inserted the function in the paragraph prefix and the closing curly-brace in the suffix, but the end result is not the formatted text.

For instance: there's a function in the template that is invoked by adding this to the document in MacTex:
\chapter{CHAPTER 1}

When I defined my style, I added this to the Prefix (I tried both the first box and the "Paragraph prefix" box):
\chapter{

I added the closing } to the suffix box.
The compiled PDF (MMD->PDF output option) just contains the raw LaTeX. When I compile to straight LaTeX, I see the following in the .tex file:
\textbackslash{}chapter\{CHAPTER 1\}

Un-checking the compile style definition's "Treat as raw markup" checkbox seems to make no difference.

So it looks like I've got a setting wrong somwhere, but searching through the manual, the forums, and the web at large doesn't help, since most of the help is with Scriv2.

Any help would be greatly appreciated.
FKA: robertdguthrie
AKA: R Dale Guthrie, Robert, Mr. Obscure, and "Oh, it's you again".

User avatar
nontroppo
Posts: 985
Joined: Mon Mar 05, 2007 5:22 pm
Platform: Mac
Location: Airstrip One

Thu Feb 15, 2018 7:26 am Post

If you use MultiMarkDown format option only to compile then \chapter{CHAPTER 1} is correctly generated (i.e. Scrivener is doing what it is supposed to just fine). But MMD itself needs special markup to not modify raw latex, so for example if you have MMD V6.x installed, then you use Scrivener:

prefix = `\chapter{
suffix = }`{=latex}

— ensuring that MMD does not escape the latex (` `{=latex} means treat the enclosed text as inline raw LaTeX, you can also use a block with newlines by using ```{=latex} ```). For older MMDs (the one built in to Scrivener) you need to replace the backticks with <!-- and --> if I remember correctly:

prefix = <!--\chapter{
suffix = }-->

User avatar
AmberV
Posts: 21543
Joined: Sun Jun 18, 2006 4:30 am
Platform: Mac + Linux
Location: Santiago de Compostela, Galiza
Contact:

Thu Feb 15, 2018 12:28 pm Post

Yeah, to reiterate the first point: if you are using MultiMarkdown then you probably don’t want to be inserting your own raw LaTeX for chapter breaks like that. You certainly can—and in fact that can be useful if you need to do something unusual that MMD doesn’t do—like inserting an unnumbered break with \chapter*{Preface} (the asterisk is the important part there). But for common regular old chapter breaks, you will be much better off using native MMD heading structure, and essentially just ticking the Title checkbox and letting Scrivener handle that aspect for you.

Reason being, MMD is not only going to insert the \chapter stuff for you, but it will automatically generate a label code that can be used for easy cross-referencing (which, like bookmarks in a word processor, can be universally formatted a certain way, so we aren’t ending up with static text as a cross-ref, but a thing that changes dynamically if the document structure is altered).

Oh, and if you don’t want the binder title, you can still use the prefix stuff with the pure MMD approach. Just leave the title checkbox off, and add “Chapter <$n>” to the title prefix. Let Scrivener generate the hashmarks around it.

You will probably need to adjust your LaTeX stylesheet though, since it by nature does the numbering for you. With stock Memoir for example, and a prefix like that, you’d get:

Code: Select all

Chapter 1

CHAPTER 1


In general one doesn’t have to bother with auto-numbering in Scrivener when using LaTeX. Its system for doing so is more sophisticated and it just kind of assumes it’s going to be handling all of that itself. You’d have to go well out of our way to hardwire your own numbering, and the result would be a less flexible .tex file in the end.
.:.
Ioa Petra'ka
“Whole sight, or all the rest is desolation.” —John Fowles

User avatar
rdale
Posts: 1156
Joined: Tue Jul 14, 2015 1:07 pm
Platform: Mac, Win + iOS
Location: St. Louis, MO
Contact:

Thu Feb 15, 2018 2:10 pm Post

nontroppo wrote:prefix = `\chapter{
suffix = }`{=latex}

I thought it might be something like that, thanks!

AmberV wrote:you probably don’t want to be inserting your own raw LaTeX for chapter breaks like that

The template has its own custom functions for other formatting that isn't covered in MMD, so I'm glad I asked about the injection of raw LaTeX, but I have two more questions:
  1. Are you saying that the MMD "heading 1" syntax (a single # sign at the beginning of a line) translates into "\chapter{my title here}" in the MMD->LaTeX->PDF compile? Being new to LaTeX,I had assumed that it didn't necessarily have the concept of a "chapter" in its syntax (as with HTML's H1, H2, etc...), and that the \chapter function was part of the template.
  2. Is there somewhere that shows what the translation is from MMD syntax to standard LaTeX, so I know when MMD is sufficient vs. when I will have to inject raw LaTeX?

Thanks for your guidance on this. I kind of skipped the whole "learn LaTeX" part that I should probably dip into before I get too far into this project...
FKA: robertdguthrie
AKA: R Dale Guthrie, Robert, Mr. Obscure, and "Oh, it's you again".

User avatar
nontroppo
Posts: 985
Joined: Mon Mar 05, 2007 5:22 pm
Platform: Mac
Location: Airstrip One

Thu Feb 15, 2018 3:13 pm Post

Goethe wrote:By seeking and blundering we learn.
:D

I never really "learned" LaTeX, and yet I use it regularly via Pandoc (almost all my academic work is simultaneously compiled from Scrivener to LaTeX->PDF and DOCX/ODT, and I have several LaTeX templates which are driven by metadata stored in Scrivener's frontmatter).

MMD/Pandoc aim to convert everything that is part of their structured format to LaTeX. As the example here, heading levels are a core part of markdown and thus get converted. It also includes things like block quotes, code blocks, maths, figures with captions, lists, tables, footnotes, comments etc. should all be translated from Scrivener by MMD/Pandoc into LaTeX.

So really you do not need to "learn" LaTeX so much as be aware of the markup available with MMD/Pandoc. Scrivener 3 contains its own custom rich text to markdown converter (how EPUB3/KF8 compiles generate such beautifully clean HTML), and so almost everything Scrivener can do can be translated via markdown into LaTeX (or many other text-based publishing formats).

User avatar
AmberV
Posts: 21543
Joined: Sun Jun 18, 2006 4:30 am
Platform: Mac + Linux
Location: Santiago de Compostela, Galiza
Contact:

Thu Feb 15, 2018 3:54 pm Post

rdale wrote:Are you saying that the MMD “heading 1” syntax (a single # sign at the beginning of a line) translates into “\chapter{my title here}” in the MMD->LaTeX->PDF compile? Being new to LaTeX,I had assumed that it didn’t necessarily have the concept of a “chapter” in its syntax (as with HTML’s H1, H2, etc…), and that the \chapter function was part of the template.


That’s a good question, I should have clarified that further. The heading cascade that MultiMarkdown uses by default goes like this:

  1. part
  2. chapter
  3. section
  4. subsection
  5. subsubsection
  6. paragraph

The latter is as special kind of paragraph—not a paragraph in the sense of what you’re reading right here, but something more like a paragraph with a run-in heading (it depends a bit on the style being used).

So one approach, if you don’t need parts, is to start your heading level at 2, but that’s a bit awkward in both MMD and Scrivener. You can do that with Scrivener—in the Section Layouts: Title Options tab at the bottom you’ll find a place to force a layout to use a specific number of hashes (the default being to use outline order). But then you have to make a different layout for every level of depth and manage all of that in the project Type by structure settings. That works, but it’s much nicer to just have a Layout that is called “Heading with Text” that handles everything Part I down to a titled paragraph.

So to that end, a better approach is to make use of the “Base Header Level” MMD metadata key (insert either into the project’s metadata pane, or in the Format if that is an intrinsic part of its design). That essentially offsets the effective hash level by whatever value you define as “top”. A base header level of “1” is the default, where one hash = one hash = part. Set to “2”, one hash = two hashes = chapter.

Is there somewhere that shows what the translation is from MMD syntax to standard LaTeX, so I know when MMD is sufficient vs. when I will have to inject raw LaTeX?


I’m not aware of a comprehensive resource, save to say that if MMD has syntax for it then it tries to do something effective with LaTeX in the output. So your primary clue that you may need to dip into raw LaTeX is if there is no native MMD syntax to do thing you’re trying to do. If there is a native way of doing it, then chances are it will “just work”. For example, here is a chapter heading using a custom bookmark label:

Code: Select all

## Name of Chapter [myhook] ##


The LaTeX result of that code:

Code: Select all

\chapter{Name of Chapter}
\label{myhook}


Instead of the default:

Code: Select all

\chapter{Name of Chapter}
\label{nameofchapter}


You could then refer to this chapter in a cross reference using MMD’s native syntax for doing so: [like this][myhook]. But if you’re using the default heading behaviour both the cross-ref and the heading will be interpolated to the same internal label. Thus [Name of Chapter] becomes “Name of Chapter (\autoref{nameofchapter})”, which when typeset will come out like “Name of Chapter (Chapter 1)”. Or in the first example, “like this (Chapter 1)”. Not MMD is not only generating the autoref code, but building the parenthetical structure and visible text as well (and it is LaTeX that is responsible for knowing that “Name of Chapter” is in fact a chapter and that it is the first chapter.

Cross-reference are then super easy in Scrivener. You just drag the thing into the editor that you want to link to and put brackets around the name. You get a handy link yourself that you can use while writing, and the brackets make the link functional in the end.

So as mentioned one case to use raw LaTeX is when MMD doesn’t do a thing—but the above is a good example of the other case, where you want a different output than what is automatically generated. Maybe you don’t want the name of the document in a parenthetical, or want to use a different referencing package than what provides autoref, then you would have to build you own cross-reference via Styles in Scrivener or something.

nontroppo wrote:So really you do not need to “learn” LaTeX so much as be aware of the markup available with MMD/Pandoc


Very true! If you’re happy with stock output, or you have a stylesheet and preamble all supplied to you and don’t really care to make any modifications to, then chances are you won’t need to learn much at all. If you want to do something like the Scrivener user manual… yeah you might need to learn a thing or two. ;) But even there, I was able to accomplish a good 75% of that by just searching tex.stackexchange for commonly asked questions. This is a decades old system, and I’ve found nearly everything you might need to do is answered many times over, and more often than not there is some package you can make use of that does exactly what you want and takes maybe ten minutes to figure out how to use. I would put my level of LaTeX knowledge down as “dabbler” at best. I know enough to know where to go to look for packages, where to get help when I’m stuck, and just enough to make my own simple layouts when need be. But I’m by no means an expert, which should demonstrate how far one can go with this approach with a little investment in learning.

Lastly, if you do want an approach that is closer to the source, you could try a template that looks to generate .tex on its own, without the Markdown layer. You probably will need to learn a little more if you go that route—but I’ve been taking a stab at a sort of easy-enough purist Scrivener+LaTeX compile setup, in this thread. From the sounds of it, you might have ended up with a similar template? If so—it might be intended to be used more like mine, where you are compiling to .txt instead of through any Markdown engine.
.:.
Ioa Petra'ka
“Whole sight, or all the rest is desolation.” —John Fowles