Compiling Styles to MS Word (MSW) Styles for Navigation - An Attempt at understanding

Scrivener Windows Beta (Archived)
1

Background
I’ve spent many hours reading both the manual and the forum exchanges about how to generate Styles in MS Word. Nontroppo, ages ago, made it work in the Mac version so I was pretty certain it was possible, but couldn’t understand what was going on. Here’s my summary which may help others with similar goals and confusion.

Goal - I wanted the structure of my long manuscript to be recreated in MSW so I could move around using the navigation pane after compiling to MSW’s docx format. That essentially requires that each exported part that is to show up in the navigation pane have an MSW “Heading #” where # is 1-9.

My conclusions after many experiments:

Scrivener Styles WILL export to MSW “Heading #” Styles (which are those that will show in the navigation pane), if they have the correct name. To get styles only for navigation purposes here are the rules I deduced, and tested successfully.

  1. Use “Heading #” styles only in the Compile formatting. If you use them in the Manuscript they will show up in navigation and confuse you. You can use other styles in the Manuscript with no problems.
  2. You will want to format the compile section Layout’s Title Format as the appropriate “Heading #” style
  3. You may need to create a “Heading #” style in the compile Style formatting dropdown, even if that style exists already in the Manuscript. The list of compile styles appears to be maintained or displayed separately from the main MS styles.

I welcome corrections to this understanding, but it works for me.

2

Yes, it sounds like you’ve got a good understanding of how this should work, though there are some specific details that aren’t quite right:

I may not quite follow what you are getting at here, though I suppose if you were thinking that the use of “Heading 1” named styled in the editor would be meaningless, I could see how it would be confusing. The rule of thumb is simple though, the naming scheme is adhered to for generating the document outline, no matter where the style is coming from. This allows for one to blend methods if they wish to. E.g. they may not wish to break up a document down to four levels of hierarchy, as subsubsections are generally quite short and topically relate to the subsections they fall within. So they would use Section Types and binder outline hierarchy for the first three levels of document structure, and then “Heading 4” styled text in the editor for the rest.

Yes, that’s the main trick for “fixing” all of our built-in formats. Honestly, I still have no clue why our built-in formats lack proper stylesheet wiring. I don’t really see the downside of having them, does anyone really strongly not want a heading outline? And meanwhile it makes everyone that does need them have to waste a bunch of time figuring out some of the more integrated feature sets in the compiler—like knowing how the compiler styles optionally override editor styles, and how to adjust Layouts, etc.

Something else to be aware of there is how some of our built-in formats have unorthodox multi-paragraph headings. That could create some awkward looking navigation if you added “Heading 1” to the “Chapter One” line—then what do you do about the “Folder Name” line? Much better to just have one line, with a visual break, that is all assigned to “Heading 1”. But there may be other better solutions for that problem as well—I don’t really know all that much about word processor usage, and what are best practices. Where I come from though, typing “Chapter One” into the document at all, like with a typewriter, never mind inserting raw whitespace characters to kludge multiline output is an absolute no-no. That all should be the job of the stylesheet, not the raw text content.

The other weird thing to look out for is the setting in the “New Pages” tab to “pad” the top of the page. That isn’t real padding, it’s going to insert a whole bunch of empty paragraphs to emulate formatted padding (which again should probably be a function of the stylesheet anyway). Purity of good practices aside, the problem is that this will cause each empty line to be added to the navigation outline. That is probably a bug.

If you mean that the compile Format can have its own stylesheet, then yes, that makes sense. It’s meant to compliment, or transform, style usage from the editor. A good example of that is how the stock styles in the editor look nothing like they should in Manuscript-Courier output. The compiler takes the styles used in the editor and transforms them to the correct output, and switching Formats will cause all of the styles to change their appearance accordingly. What you don’t supply in the Format’s stylesheet will be passed through from the project’s stylesheet verbatim.

So it’s a kind of flexibility you have, where maybe some styles aren’t meant to change depending upon the output (Emphasis, for example, may always just be italics). It also means that Scrivener, at its most basic usage, allows one to more simply use styles while writing with the intention of that being exactly what the document looks like.

3

During the Scrivener 3 macOS beta, I did bring this up, and KB’s comment was that this is entirely up to the user (link), I suppose it is more consistent with old behaviour pre-styles, and KB’s approach was to be hands-off in terms of the binder>outline mappings. But I do agree with you that having the hierarchical outline levels of Scrivener’s binder becoming outline levels in Word in the default formats that come with Scrivener would not preclude users changing it if needed, and there have been many posts on the forums asking for how to do the standard mapping (and it isn’t trivial without a solid understanding of compiling). Levels 1=1 2=2 3=3 4=4 5=5 6=6 seems a logical baseline, and if a user wants to turn 1==3 they can use the same compiler tools to do so?

4

Okay, I think maybe what Keith was saying there was that this shouldn’t be something that is determined by outline levels, since nothing else about the compiler works that way. We can create a level-based setup, but that’s all in the project settings, it really has nothing to do with compile settings, save for how we tell project X to use compile format Y’s layouts. So that specifically, I agree, should be left up to the user.

And I get the logistical reason for why the built-in formats are devoid of hierarchy, because they cater to multiple arrangements. With one Format you can output a book where chapters are organised into parts, and as well a book that has chapters at the top level. So simply assigning Heading 1 to chapters wouldn’t work in a universal fashion, since a book with parts would want those to be Heading 1 and chapters at Heading 2. Thus to solve the problem entirely, and make it so Scrivener produced well-formed documents without any complex adjustments, would be difficult in the current design.

But it does still bother me that it takes so much work and learning to get what should be a proper document with minimal fuss. There is a corner that was painted into there, by completely decoupling level hierarchy from output hierarchy. I think overall that’s a good thing, but it makes specifically this problem difficult to solve.

Ultimately I think there are better solutions to these problems than what we have, but it would require a major restructuring to get to that point. The better solution is probably also less “intuitive”, in that it relies more upon the conceptual design used by Markdown, XML and LaTeX approaches, where document structure emerges from the usage, rather than having structure applied to the usage, if that makes sense.

5

I assume adding a built-in compile format in which standard level hierarchies are preserved can be easily added? Possibly add a “Hierarchical” non-fiction template, as preserving a hierarchy makes more sense in non-fiction environments. Now whether users who use this template understand what is going on is another matter, but I do think it would be useful to just tell users, use this template if you want your binder hierarchy to be respected in output formats that support outline levels, rather than refer a user to dive in at the deep end. Possibly some instructions could be included in that template?

As for a longer-term solutions, I do really appreciate the way Scrivener enables such flexibility, and wouldn’t want to lose that. But assuming a linear relationship as a default (without precluding other mappings) has merit. This is actually how the MMD outputs work already, giving linearly-mapped #header levels in output by default…

6

Yeah, it’s not an impossible to solve problem, rather I can’t think of a rather neat way to solve it in the current toolset. A Format with a bunch of different choices for each level (h2 Section, h3 Section, h4 Section…) to satisfy the various different large-book, small-book, paper/article structural schemes sounds very messy and confusing. Like you say, it feels like this Format would need instructions to explain why it has five tiles for Subsection that all look the same.

And the alternative is to fix the overloading problem by instead spamming a bunch of extra Formats into the list. Now you’ve got “Manuscript (Times) for Books with Parts”, “Manuscript (Times) for Articles”, and so on—multiply each bookish format by three.

Well yes and no, and I think that fact is something that would have to be part of an RTF solution as well. You can have the basic default linear assumption from the local compile group context, but I think you would also need the same thing Markdown has in the Title tab—a setting that allows for one to specifically target an h-level statically. That keeps Scrivener’s outline from being 100% slaved to the document structure, which remains one of its great advantages over outlines that aren’t, like Word’s.

But yeah, something like that makes the most sense to me, and what I was getting at by modelling structure from use rather than applying structure externally. Maybe even a “Hierarchical Heading” toggle in the style dropdown itself, which would cause the layout to produce h1, h2 or whatever depending on its contextual usage in the output. It’s a start, but there are still rough edges since RTF users have a limitation of needing to mix formatting with semantics intrinsically. I.e. how do you handle the ability to visually format parts differently from chapters, while making it possible for both parts and chapters to be “Heading 1”. I can think of some ideas, but nothing truly elegant.