How to make a box like in the Scrivener User Manual

Scrivener
, ,
1

Hi,
I’m relatively new to Scrivener and wondering how to use boxes in Scrivener like the ones in the Scrivener User Manual.
Are these boxes just tables with 1col/row or is there a more elegant way to achieve this goal?

Kind Regards
Holger

box.jpg
box.jpg1756×1264 291 KB

2

Using Scrivener alone, the 1x1 table is the best approach. You probably won’t be able to get a box quite like the manual though without using the same tools we do: LaTeX. For anyone curious as to how it works, I’ll describe the process.

In Scrivener I have two styles that I use to build a box. There is a paragraph style with a yellow background highlight used to enclose the entire thing. This is used to insert part of the code necessary to build one in the output. The other style handles the heading, which inserts the rest of the code.

  • The box style itself has compile settings that insert a prefix and suffix around the whole thing of \begin{callouttip} and \end{callouttip}.
  • The title style has its own prefix and suffix around the line of text, simply: { and }\n.

Consequently, in Scrivener the box itself looks nice—not terribly unlike the end result, and no code visible within it. The compiler does all of the dirty work for me, and it means if I change how these boxes are constructed at a technical level, I can do so in one single place rather than fixing hundreds of them.

The compiled result looks like this though:

\begin{callouttip}{The heading of the box}
The body text of the box...\end{callouttip}

This is shorthand, a LaTeX environment I’ve built that looks like this:

\newenvironment{callouttip}[1]{
    \begin{mdframed}[style=titlecallout,
        linecolor=lnl-latte, backgroundcolor=lnl-yellow,
        frametitle={#1}]
}{
    \end{mdframed}
}

The ‘titlecallout’ style is one I’ve defined elsewhere that handles all of the other particulars, like the amount of padding between the edge of the box and the text, between the heading and the text, the heading font, etc.

So I’m using the mdframed package to get this result. It comes with a number of useful features, one of which is multi-paragraph support for the box contents, the ability to put a border around the box and another is page break avoidance. The box will float to the next page if it won’t fit into the end of the previous, rather than getting split between pages.

1 Like
3

I have the same question, so I was very excited to see this thread–but I haven’t been able to figure out how and where to implement the second style. Here’s a summary:

  • I defined a paragraph style with a one-column/one-row table and background highlight.
  • I’d like to define margin space between the box and the text, and the width of the line around the box. I can do this manually for each box using the Scrivener editor, but it doesn’t end up consistent in my output.
  • I’d like to do this for PDF and mobi output.

I’m not sure what “heading” refers to in Amber’s response. I don’t need text headings in the boxes (bold, etc.), but maybe “heading” refers to something else?

I put \begin{callouttip} and \end{callouttip} in the compile prefix/suffix settings for my box style, but they show up in my output; they weren’t recognized as instructions.

This is the only formatting task I haven’t been able to do with built-in styles or compiler settings,

@AmberV, you mentioned your ‘titlecallout’ style, the mdframed package, and a LaTeX environment. Are there specific ways to use LaTeX libraries from within Scrivener–can you point us to a recommended workflow with steps that describe where and how to specify and use packages from within Scrivener? I feel like I’m soooo close, but don’t know how to get there!

Thanks–and thanks for responding to so many of our questions about Scrivener–very helpful.

4

To be clear, LaTeX is a whole different file format, it isn’t something you can graft into other formats like Mobi files or PDFs. Scrivener can greatly help in the construction of .tex files, in the same way that it can greatly aid in the construction of a .mobi file, but it can’t combine two completely different pieces of technology.

In a Mobi file you are going to be using CSS to create a box, and that means using HTML to construct the box code. PDF is another matter entirely, it isn’t as easy to work with directly like that, and so using something like one-cell tables is probably the best approach.

I would imagine these tips would only be of use to someone also using LaTeX. It is another system outside of Scrivener, one you’ll need to download several gigabytes to get started with, and one that you use after compiling the source material with Scrivener, much like you would use InDesign after compiling from Scrivener.

So to reiterate, Scrivener all by itself cannot do any of this stuff that I’m talking about. What it can do is export raw plain-text into an instruction file that tells another system how to format a document.

If you’re interested in that approach, then I would encourage the MultiMarkdown/Pandoc starting point from within Scrivener (refer to the chapter on them in the manual). That is what the user manual makes use of. I only have Scrivener construct raw LaTeX where Markdown-based systems fall off (they don’t have a call-out box syntax for example), so for most things I don’t have to worry about LaTeX—and so for someone starting out it would be a good place to work from since you wouldn’t need to learn as much theory to get a working .tex file. You’re still likely going to need to learn a lot about it though, as a system—and like InDesign or any other professional level design package, it’s going to take a lot of learning to get it under your control.

1 Like
5

I think, but I’m not sure, that Amber setup the second style as a “character style”. So you can select a paragraph and choose two styles…the paragraph style #1 and then for just the one line at the top, apply character style #2. Then in the compiler this gets turned into the tags she mentioned so that the whole thing is in a box with a header on it, using LaTeX.

I’m also a little confused, I was under the impression that LaTeX needed to be escaped inside <!-- comments to get through MMD. Why did I read about that? But it looks like from above, that the prefix/suffix data is applied after Scrivener has generated markdown or whatever… I’m still figuring all this out. But Amber if you could clarify I would appreciate it. I am going to need to do something similar for syntax highlighting with the minted package in LaTeX. and probably I am going to try to use some other LaTeX packages to get a more sophisicated text flow through frames.

But then I don’t know what I will do if I am trying to generate epub, mobi or other ebook formats…if I rely on LaTeX for stuff like boxes, callouts, syntax highlighting, etc… it will make the output look much more custom like InDesign, and I like that…but then will my other outputs go through LaTeX step also?

Also Amber you mentioned some other styles and LaTeX code that you’re using, so that the prefix/suffix can be very simple, where do you define that other LaTeX code…do you put it into a file on your file system somewhere and included it somehow or is that still something that can be placed inside the Scrivener project somehow?

6

That’s correct, the yellow box is a paragraph style that goes around the whole call-out. I use the feature that draws a yellow box on the styled text—that doesn’t exist as formatting, it’s just a semantic cue for myself. The box heading is then a character style within that paragraph style.

The mdframed package doesn’t require a box to have a heading, it’s just a convention I like to use so that one can skip over boxes that do not pertain to them. There is another variation of box in the manual that contains tips for those upgrading from Scrivener 2. In those I don’t have a heading in the editor, because they all use the same heading. I just use the paragraph box (a different style, to generate a different box code in LaTeX) in that case and the heading itself is hard-wired to that box style.

I did leave those out since the syntax itself is currently in flux. The method you mention is what you’d use in MMD5 and lower, but in MMD6 you’ll need to use a code spans or fence blocks. The full prefix is:

`\begin{callouttip}`{=latex}

LaTeX blocks, if you’re curious, are:

```{=latex}
Blah blah...
```

Even though at the moment Scrivener has MMD5 integrated, I would recommend using MMD6 notation at this point. The 3.0.3 upgrade will be using the latest version of MMD, and it will be out in a matter of days. If you need to start testing output right now, you can install MMD6 yourself; Scrivener will use an external installation over its own copy.

In my opinion that very problem is solved elegantly by this particular way of working, in conjunction with Scrivener’s compile Format system. There is no LaTeX in the editor at all for this call-out box—just the styles. Everything that makes this text become LaTeX code is in the compile format and nowhere else. Hence, if we switch to a format designed to generate an ePub, we can do something entirely different in the prefix/suffix fields for these styles, like this for the style prefix/suffix:

<div class="callout"> ... </div>

For the style’s paragraph prefix/suffix (this goes around each line within the styled range:

<p> ... </p>

The heading character style’s prefix/suffix:

<span class="callout-heading"> ... </span>

And the rest would be handed by CSS naturally. The resulting output from Scrivener would be:

<div class="callout">
<p><span class="callout-heading">The Heading of the Box</span></p>
<p>The first paragraph of the call-out</p>
<p>Second paragraph...</p>
</div>

You can have raw LaTeX in the editor as well—I do in fact in the user manual, as there are sometimes one-off things I need to do. So I have a “Raw LaTeX” character style that I use to mark those bits of text. That character style wraps the text in MMD’s above syntax for passing it through.

When I finish making the ePub generator for the user manual, I’ll be checking the Delete text of this style option in the Styles compile format pane. I could conversely have a “Raw HTML” style that was excluded from the LaTeX compile format if I wanted, and so on.

The answer is “yes”. :wink:

  1. For simpler preambles you could go into the LaTeX Options compile format pane and set the document class to “Custom”. Now you have full control. Refer to §24.12, LaTeX Options in the user manual for info; pg. 635. That’s nice as it keeps the entire design in the compile Format itself. Easy to share with others or copy to other machines.
  2. For the user manual—there are around 600 lines of preamble to achieve this look—I want to keep a complex setup like that on the file system so that I can easily edit it in my text editor. You should make use of the “LaTeX Leader”, “LaTeX Begin” and “LaTeX Footer” MMD metadata tags to refer to .tex files. Those files should either be in your compile output folder, or somewhere in your texmf path.
7

[size=85]Amber thanks so much for this response, it is very helpful…

Ok, still wrapping my head around all of this “escaping”. I just installed mmd6 and so it sounds like Scrivener should find and use that if its in the path.

So in general, can I say the following 50,000 foot view of it(please correct errors):

Assume in the following I am trying to absolutely minimize or eliminate any markup from appearing in the document editor. I want MMD/LaTeX/HTML markup added either during compile or post compile.

  1. Simplest case-native Scrivener, just use Scrivener WYSIWYG formatting, make the editor look how you want the finished thing to look and compile directly to the formats that are supported without MMD. In this mode, no markup of any kind will be noticed, so whatever you see on the editor is how it will be printed out, if you add any markup, the markup will print out literally.
  2. Using MMD6 compiles, with MMD as the final output, then in this mode, Scrivener will not attempt to generate too much MMD based on Scrivener formatting, except header level #'s are generated. Aside from that, if we want MMD markup such as bold and what not, then we need to styles and add prefix/suffix for each style so that MMD will be generated. I can put MMD markup directly into the document if I want, or using the style prefixes.
  3. MMD6->LaTeX->PDF: In this mode the compiler is going to use MMD6 to generate LaTeX. In this mode, header levels are converted to something usable by LaTeX, rather then MMD markup. Otherwise, our style prefix/suffix will be used to add the LaTeX formatting we want. IMPORTANT, this LaTeX included in the prefix needs to be properly escaped to get past MMD6. LaTeX can also be added directly to the Scrivener document, but needs to be escaped so that MMD6 will pass it through exactly as is. (note, its not clear to me why MMD6 needs LaTeX text to be escaped?)

I am studying up about LaTeX now and some your explanation about the LaTeX stuff might make sense after I get deeper into it. I will spend some time learning more about MMD6 too. At this point I’m just trying to get a grasp of what is happening during all these conversions from one format to another, with escaping needed to pass some things through to later conversions, etc.

I will leave epub out of the discussion for the moment. I’d probably be inclined to just use Scrivener’s direct compile to those formats, except…in order to use LaTeX for PDF and print copy, then I will almost certainly end up resorting to things like you have done above, using highlighting and what not to show in the editor what style is on for some given text, and not necessarily making the WYSIWYG appearance what I would want in the Epub. So that means ultimately its a bit all or nothing, either keep it simple with WYSIWYG, with whatever limitations that exist…or…go the full MMD/pandoc route and in that case I will need to use style prefixes that generate LaTeX for my PDF/Print, and use CSS/HTML prefixes for the epub output. Is that about right?

Pandoc is an additional level of conversion that I have yet to investigate…I want to understand the basic stuff first…

got it. Thanks![/size]

8

Also , do I have it right that mmd6 requires the fence around latex code...but...pandoc does not use the same method...rather I just have to make sure the raw_latex extension is enabled with pandoc? Or should I just pass normal MMD markup with the fence around raw latex to pandoc and hope it does the right thing?

I guess the fence needs to be there when placed the style prefix/suffix, yes?

9

Thanks Dewdman42 for your comments and questions, and AmberV for your detailed responses.

To double-check my understanding:

  • We can reference mdframed styles/settings via Scrivener compiler style prefix/suffix. It sounds like these styles don’t reside within Scrivener; they’re defined externally.
  • I would compile the book as “Multi-markdown -> LaTeX” (or skip the MMD step per AmberV’s 2/7/18 posts). Either way, I’d have a LaTeX environment and appropriate definitions outside of Scrivener, and I’d run the book through LaTeX,

Sound right?

For my simple use case–text boxes with shading–it sounds like I should continue using single-cell tables and adjust the border line width and padding by hand for every text box, unless/until I want to delve into MMD and LaTeX.

Thanks again for clarifying, and good to know that there is quite a bit of flexibility if I need to use Markdown more extensively in the future.

10

Because all punctuation that might mean something in LaTeX is escaped—for the same reason if you have an XML generator that takes user data, you would escape the user’s input so that a stray “<” in their document doesn’t invalidate the entire book. If someone uses a so much as a percentage mark in their text, if MMD didn’t escape it then it would make bad things happen in LaTeX, since “%” comments the rest of the line.

Thus you have to be very specific and tell MMD that what you are going to be typing in here really is code and it shouldn’t mess with it.

Funnily enough, if you go through the introduction on Markdown and Scrivener in the user manual (§21.5), you’ll see a similar enumerated list of basic approaches we anticipate people making with the available tools. Interestingly, what is referred to as “incidental” usage of Markdown in that list overlaps your “simple case” item in the list. Scrivener actually has a pretty full-featured RTF → MMD conversion engine. For those not using any Markdown at all, it’s possible to get something like LaTeX out of the compiler with a checkbox (but only in a very basic sense).

I think you do get this, but for clarity: there is no substantial difference in terms of underlying technology between points 2 & 3. The difference is solely in how you choose to work with the interface, and what features you take advantage of in the editor. It is possible to treat Scrivener 100% like a plain-text editor and not have the compiler add anything to the document or change any aspect within it. Or you can have a source document that essentially doesn’t look like markup at all, and is just a bunch of styles. Either way, both of those methods result in Scrivener creating a plain-text UTF-8 file in MultiMarkdown or Pandoc dialect and feeding it through one of those engines to produce an final format, such as LaTeX, OpenOffice, DocBook or ePub.

The important thing is that after the point of creating that .txt file Scrivener has nothing to do with any of this. It’s either saving the .txt file to the disk (with the plain “MultiMarkdown” option) or processing it with a script. So that .txt file has to be valid MMD/Pandoc at that time, however it gets that way. When we talk about escaping LaTeX—that’s not a Scrivener thing. That’s what you have to do to print raw LaTeX codes in a Markdown file. So we need to get Scrivener to help with the escaping if we don’t want to type it in ourselves (or we can type it in ourselves too!).

If there is raw code somewhere it needs to be escaped, no matter where it is. Again Scrivener isn’t doing this. You are. It doesn’t know what you’re doing. You could be building a compile engine that is creating MySQL queries for all it knows.

And yes, Pandoc uses the same escape syntax, no worries there.

In my experience it will probably be easier to install Pandoc, and then use the Pandoc->ePub compile mode in Scrivener. It’s a pretty comprehensive setup we’ve built for it, giving you up-front control to just about every aspect you’ll need, and it’s going to be a lot more precise and less “buffered” to work that way.

Granted if your project is indeed purely devoid of all Markdown in the editor, it might be doable to use the native ebook stuff, but it can be constraining to work that way.

Here is a good way to think about it: ultimately these are two radically different approaches to writing. You can have a full system that is extended by the bridge Scrivener builds between these different approaches, or you can sit on the bridge and just use the area of overlap between the two—avoiding all of the unique capabilities the actual methods themselves offer.

11

Yeas I read chapter 21 but honestly it’s kind of hard to follow due to so many details.

12

Pandoc and MMD both use the same syntax for general escaping[1]. This is “Extension: raw_attribute” in the Pandoc user manual. You are correct that Pandoc also has “Extension: raw_tex”, that, similar to original Markdown’s support for raw HTML, allows LaTeX in the document without escaping. If the output is LaTeX it is retained, and for any other output it is removed. However, because both MMD and Pandoc support raw_attribute and Scrivener makes it automatic to add the syntax with Styles, I would just keep using raw_attribute. You can then maximise compatibility all round!

[1] I advocated for Fletcher, the developer of MMD, if he could use consistent syntax with Pandoc so minimising divergence between Markdown flavours: github.com/fletcher/MultiMarkdown-6/issues/38 — he graciously agreed.

13

Looks like Pandoc is really the way to go, I read through the pandoc user guide last night. It has a LOT more options then MMD.

But your comment about sticking to raw_attribute mode with fences around latex or HTML code for backwards compatibility to MMD is well noted, thank you.

I like that pandoc has template facility, etc… Basically I think I can get a lot more elaborate page layout with LaTeX, and later with ePub, by using the templates and plethora of options that pandoc has.

I do have to say the built in RTF->PDF compiling from Scrivener is really not half bad. Honestly, I am going to look at that a little more closely to see if I could format my book good enough that way. The one sticky point for me is syntax highlighting code blocks. If I want that, then I think I need to use Pandoc. There are other things I’d like to flow text around images a bit, in order to put figure explanations next to the figure, etc…but I could live without that probably if I had to, or perhaps use a table in some way to get it close enough, but syntax highlighting…I don’t see an easy way around using pandoc.

14

MMD is a great tool. I migrated from MMD to Pandoc primarily because of its excellent citeproc support (fully automated bibliographic processing), and templates / reference documents (you can use an empty Word or LibreOffice file and it uses the Styles / page layouts and injects contents into it). Then I started making filters using Ruby, and realised the amazing power that you have because Pandoc converts documents into what is called an Abstract Syntax Tree (AST), which is the semantic skeleton of the document. This is what allows Pandoc to read and write so many formats, and do so many cool things with filters. For example,

function Strong(elem)
  return pandoc.SmallCaps(elem.c)
end

Takes any strong element and makes it small caps; no need for complex regex, just use clear semantics! Then I found out about Panzer and Pandocomatic, so I could use “templates” to compile multiple formats in one go.

Yes, for a program that clearly states it is not a layout tool, Scrivener’s built-in formatting is surprisingly powerful! 8) I suspect it is sufficient for most users. But Scrivener didn’t stop there, it built robust bridges to automation tools like MMD, Pandoc (and you can use others like AsciiDoc etc.), so you have so many degrees of freedom it is sometimes hard to know which way to go!

15

It would be much appreciated if someone would generously post using the least complicated technique the exact steps required to generate a textbox with the following characteristics: indented 1 pica (or so) on each side; background color other than white; centered text using a Normal paragraph.

16

It sounds as if these Scrivener styles would have to nest one within the other, but is that even possible? I haven’t been able to do it.

17

You can read the answer to that question, here.

18

Ah. Yes, thanks, and I’ve actually done that, nesting a character style in a paragraph style. I didn’t know that was the situation in this thread.

19

Yeah, if you need more than that, like a “div within a div” type scenario, then you would need to use a different approach, like Section Layouts, which act as a super-container for paragraphs, or if that isn’t practical, some kind of replacement-based approach around the group of special paragraphs. It’s an answer that wouldn’t be terribly different for most workflows for that matter, as nested paragraph styles aren’t really a typical thing.

20

We have quite a bit of formatted nesting, all in all.

  • Project Template
  • Default paragraph (global)
  • Default paragraph (one project)
  • Section Layouts

Three kinds of styles:

  • Paragraph styles (¶)
  • Character style
  • ¶a

and these, but you can’t nest them in a character or ¶a style:

  • bold, italics, underline, etc.