A question about the 3.0 manual

Firstly, thanks for the kind words! The design of the PDF was a labour of love, and so it’s always nice to hear when it gets noticed. (And I cannot take full credit, much of it must go to Donald Knuth’s TeX system, and the countless thousands of volunteers who have worked to refine this system since the late ’70s.)

The download link that Katherine provided will get you a copy of the Scrivener project itself, and you will quickly note that I don’t use Scrivener as a publishing tool, but rather a writing tool to generate the text that will be processed through software more dedicated toward that task. Scrivener’s simple text layout system simply cannot do many of the things you see in this PDF—but that’s not to say that in a broader sense, Scrivener as software cannot do these things, it just needs a little help, as you suspect.

While Scrivener could maybe do some of it, in theory, it would take a monumental exercise in using a hammer for a screwdriver to do so.

So yes, to answer that more specifically, where it starts is simple: with a new Blank project. Every word of it was written in Scrivener, and there is no single facet of the output PDF that I cannot control from the text editor or other organisational tools. I spend no time at all, after compiling, “finishing the job” myself.

Where the process ends, on the other side of things, is a bit blurry, and perhaps open to debate. Here’s the basic sequence:

  1. The Compiler generates a MultiMarkdown document. This is a form of Markdown (like you often see on forums, Github, blog comments and so on) that is geared toward authoring books. It has additional tools and conversion scripts, as well as syntax for things like glossaries and footnotes.
  2. Much of the particulars of how it compiles will be documented in the download, at the top of the binder (I have written a bit on the forum regarding the tip boxes themselves, though). Importantly, the penultimate output of what Scrivener creates looks quite unlike what you see in the editor, thanks to a wide variety of compile features.
  3. After a Markdown file is created on the disk, the next phase the compiler starts on is running through a custom script that does further text processing. Here is where we can tell the compiler to do things using full-scale programming languages, really the sky is the limit, but I use it fairly simply to clean things up where Replacements don’t reach, and so on.
  4. This script takes the next step of using MultiMarkdown to generate a .tex file, and runs a few additional processing tasks to finalise the document. At this point, it loads in my text editor, and I hit a shortcut to start the typesetting process.
  5. Once that is done, a PDF opens up and I’m ready to proof the changes.

So where does Scrivener end in that process? You could maybe say around step four, though technically if I really wanted to, I could add the typesetting steps to my script and have the end result of compiling be a PDF file rather than the intermediate .tex file. (I do like having that stage though, as I can make quick corrections to the .tex file without having to redo the long compile process.)

So in theory we could even go so far as to say that Scrivener could produce this PDF “all by itself”. Yes, it’s with the help of third-party conversion tools, but frankly that is not much of a caveat—if you compile a DOCX file you’ll be doing almost the same exact thing, only using an embedded third-party conversion engine called Aspose, that you may never even be consciously aware of since it is all automated for you. That’s what that second progress bar is for though. :slight_smile:

The details of how that works are in the download package, but from the project side of things it’s all pretty simple—it is in fact nothing more than a binder item title. In fact the output is so clean of formatting that this precise look is only applied at the very, very end of everything. Even the .tex file is entirely devoid of such details. All it has to say for the screenshot you posted is:

\chapter{Installation \& Upgrading} \label{installationupgrading}

Not even the number is in there. In my opinion this workflow is really the Scrivener ethos in extended form: don’t bother with formatting, just write and keep it simple. Let technology handle the formatting for you. Whether you use the compiler exclusively, or as a tool to produce the content that will be formatting, it’s all the same at the front of the process where you do the writing.

Did I spend a bunch of time creating the workflow? Yeah… maybe too much, because I’m a geek about this kind of stuff. :laughing: But at this point, three years later? I don’t even think about it. I know that if I create a new level 2 item in the Draft folder, it will be formatted correctly, have an automatically generated section ToC added after the page break, with each major section pointing back to it at the end, etc.

So yeah… here comes the bad news. :slight_smile: It is a lot better than it used to be, but at this time there are still a number of compiler issues that make compiling to the PDF you see pretty much not worth the trouble of attempting it. You’d be in for a few hours of fixing the output in a text editor.

It’s less that the Mac has more features, and more that there are a few bugs and issues here and there that cause widespread output problems that are hard to fix by hand. One example is as simple as an empty line being added between two others, where it shouldn’t be—that can be all it takes to break what is meant to be rigid syntax, and hundreds of pages break their formatting (in this case, the menu appendix and anywhere else you see that hanging indent glossary style, such as settings lists).

Small things, but, I suppose that in itself is the silver lining. We’re not talking about big things, like we certainly would be when comparing Scrivener 3 for Mac with Scrivener 1 for Windows. Small bugs and issues are much easier to fix (usually), and hopefully in short order we’ll be able to add instructions for setting up the compiler on Windows and getting a PDF out of this thing. :slight_smile:

In the meanwhile I’ll need to add a disclaimer to the text where it states it was “made in Scrivener”, if these issues cannot be resolved by launch.

Correct! Now that part you could do with just regular Scrivener. It’s a special “glyph” font that is open source and available from the Linux Libertine Project. It would be simple to add a style to handle the font change and any other formatting you wanted, and the project auto-complete list might help with typing in the stuff that uses special characters, like the Ctrl key. It’s a lot like working with WingDings, really—if you were to change the font you’d just see “F” instead of the “F” in a key shape.

As you’ll see in the manual though, I again follows that ethos of pushing output details to a later phase. The shortcut itself is just typed in like, “Ctrl+Shift+P”. It’s the compiler and post-compile conversion that turn that into what you see, and thus different compile settings could do something entirely different with the shortcuts. For example if I ever get time to create an ePub version, I’ll probably have to use something other than fonts to handle shortcuts, and will be glad I didn’t use the fonts up front in the content.

Huh, now that is a missing feature, looking at it. I think Keith did in fact add a horizontal line option to the Mac version, specifically so it could match this look. But it looks like they haven’t figured out how to do that yet for Windows. It’ll be a setting in the Page Settings compile format pane though, by the way, not something you type in anywhere.

There are design notes on the copyright page, if you’re interested in the details. We don’t have the necessary (and extremely expensive licences) to distribute the fonts unfortunately, but I did try to find some suitable system alternatives for the public copy. I’ll have to do that for Windows as well in time.

I suspect you get Sitka because your PDF reader is copying plain text (most do), so it’s like copying from Notepad at that point.

Well that was a very wordy post that probably all boils down to: learn LaTeX or give up! :laughing: But as I think I expressed in the help file of the downloadable project, it is my hope that even if the technology used to typeset the PDF (or the intermediary approach of using Markdown) isn’t your cup of tea, the techniques used to write the manual itself will still be of interest to those in non-fiction, documentation and technical writing. They at the least demonstrate some of the geekier edges of what Scrivener can do to make various tasks easier, no matter which compile output setting you use. While it may not natively have a way of drawing a margin box or whatever, it can systematise the processes that goes into ultimately doing that. And in the end, that is how most books with specialised formatting are made.