Variables and variant filters available in Scrivener?

Hi,
we are a machinery company and currently looking for a software to write our technical documentation with. Im currently testing scrivener and I´m wondering whether it is possible to do the following things. I checked the scrivener manual, but didnt find anyhing about it, maybe you just call it different:

  • Is it possible to place variables into the documents and to fill these variables with predefined values when compiling a project?
  • Is it possible to filter the documents to be compiled for certain metadata, e.g. “Machine type A”/“Machine type B”, so that I would be able to create a distinct pdf for e.g. machine type A or B from the same project?
    Kind regards

if i understand:

for the first, look at the compile settings for replacements. set up a fixed nomenclature for the replacement words

for the second I do this by setting up collections and then doing the compile on the collections.

however, i am not sure how to connect a set of replacements with a collection.

Both of these concepts, replacements and collections, covered in the Scrivener Manual.

all that being said. I think i would look at doing some sort of database to hold relevant data and structure and then write some programs that pull that into a document. i have done that more than once in the past for this sort of technical documentation.

1 Like

I’m not an engineer and don’t write technical manuals; amongst other things, I edit Chinese→English translations. Often, the final document will be interleaved: paragraph of Chinese, paragraph of English—even if a “paragraph” is a heading of only one or two words. However, I want to be able to read the English as a complete text, without the intervening Chinese.

So, for what it’s worth, you could think about how I handle that … I use labels. Each “paragraph” is a separate document, labelled “Chinese” or “English” as appropriate. I then have saved search collections based on those labels. That way, while working, using Scrivenings mode as necessary, I can open the Chinese source in the left editor, and the English translation in the right editor. When it comes to compile, I compile the draft which has both texts interleaved.

So, for your purposes, you could use keywords rather than labels, as a document can have more than one keyword, but only one label. Create “Type A” and “Type B” keywords. Split the text up so that binder documents common to both have both keywords set, while documents concerning each one individually have only the appropriate single keyword. Then set up saved search collections based on each keyword, which will bring together all documents containing the given keyword. In the end, you would compile each collection, rather than the draft as a whole.

And I agree with @rms about researching compile replacements.

:smile:

Mark

3 Likes

Thanks a lot for your replies, I will try the possible solutions you proposed. :grinning:

Scrivener’s manual itself, if I am not mistaken, is a good example, as it was produced for both Mac and the Windows version from a single project.

In addition to the kind of document- down to paragraph-level variants that @xiamenese mentions, you can also engineer variants down to the level of words and phrases using defined styles.

If I have three different versions of a product and need to speak differently to each at certain points, I could define a custom style for each, and then apply the appropriate style to spans of text which apply to one product only. The “styling” of the custom styles does not matter here and will not be seen in the output (it would be usual to have the style defined simply to subtly highlight the text in the Editor, so one could see it had been applied). The point of doing this is that when you compile a version of your documentation, you can have the Compiler suppress all the text associated with certain defined styles. That way you can expunge all the text not appropriate to this particular product version.

2 Likes

While this is absolutely true, and I thought about it myself, I would add that the Scrivener manual is written by AmberV—who probably knows more about Scrivener than anyone apart from KB himself—is dependent on customised styles, and compiles through LaTeX. So if @Tobias_technicalauth is LaTex-savvy, then looking at the Scrivener project for the manual, would be of interest.

By the way, it seems the User Manual Scrivener project itself is not on the download list at this moment.

:slight_smile:

Mark

You have to scroll down.

Screenshot

https://www.literatureandlatte.com/learn-and-support/user-guides

2 Likes

Yup, missed it … duhh!!

I don’t know why it is so easy to miss…?
I completely went by it too, looking for it a few weeks back.

@xiamenese Unfortunately I have no idea about LaTeX, but I will take a look at the User Manual project :slight_smile:
Thanks for all your replies, I will test the procedures you proposed in the following weeks.
Kind regards from Bavaria
Tobias

I suspect getting any insights from the Scrivener Manual “source” will be not fruitful for you. It is indeed very complex, but in time might be of interest.

Re LaTeX … Scrivener provides “General Non-Fiction LaTeX” template which is pretty good. I use that all the time for a few of my technical documents. Yes, over the years have tweaked that into a few improvements (IMHO, of course). But I wanted to point out that if you create document based on this template, at the very top of the Binder list is an excellent summary of of how the template is setup and how to use. It got me started using LaTeX. I like LaTeX because it’s relatively easy to make automatic TOC’s (of contents, figures, and tables) and creating an index based on marked words. For my document deliverables that’s useful and doesn’t cause me a lot of extra work.

Since I’m a bit lost by this thread, and have the same question of the original poster, I’ll have to try a recap:

Scrivener can’t use user-defined variables (or placeholders), like <$protagonist_name> or <$edit_command_name>?

Paolo

Do you mean something like the attached?

uservariables.zip (77.5 KB)

1 Like

Sorry, sobs, but I can’t understand your answer. I see a Scrivener file simply mirroring my example above. What does it mean?

EDIT: Oh, I see, you used Replacements. While note exactly Text Variables, I can write them in a format that makes them unique, and therefore act as Text Variables. Thank you, I guess this is the solution I was looking for.

Paolo

1 Like

@sobs solution is using replacements, which are great. As is usual in Scrivener @ptram there are many solutions to any problem :nerd_face: and Custom Metadata is also a wonderful way to handle these substitutions. You define Custom Metadata using Project Settings, then for each document, add the values. In the editor or Compiler (Like Section Formats etc.) you can then use <$custom:protagonist_name>.

You can see these in great effect in the Scrivener Manual project:

Here, @AmberV is using the epigraph variables which will end up creating the quote you see on the cover page for Section IV of the user manual:

This allows you to use different Section Types / Formats to inject these at compile time. Custom metadata has the benefit that it can be used in the Outliner, act as filters for compilation, and other places; rather than hidden in the compiler settings…

3 Likes

The answer provided by @nontroppo is probably more what you want (I think).

Thank you both for your hints. Both look like viable and handy solutions.

  • Custom Metadata, being editable for each document, could be more flexible, in case I need some exceptions. At the same time, I don’t see a way to make them global, therefore allowing for a general definition for the full project.

  • Replacements are only global, so not allowing for exceptions in a document. This might not be a problem for me. Using unique name formats, there shouldn’t be any error in replacing the wrong string.

Apparently, Replacements could be what I’m looking for, for things like commands or parameter names to be translated into different languages, or adapted to different products.

Paolo

Something worth mentioning about the user manual project is that I wouldn’t necessarily refer to it as a LaTeX-only project. There are a few scattered LaTeX commands in the source, but they are all marked with a style and could be stripped out in a format meant for another target. The source itself would be more accurately described as Markdown, which is itself capable of being turned into almost every file type you would ever need, with Pandoc.

What I’m getting at is, one wouldn’t need to be at all savvy in LaTeX to use the manual as a reference for what the software can do. I’ve seen people use it to create ePub files and other things for their own purposes.

@ptram : Apparently, Replacements could be what I’m looking for, for things like commands or parameter names to be translated into different languages, or adapted to different products.

Yes, I would say Replacements can be thought of as global, but they are a bit conditional as well, in the sense that you can put them into a Format and thus make them evaluate to specific strings depending on which format you compile with. The result is still more like a constant than a variable for the running of a compile job, but if you need edition-specific variations, that’s where I’d put them.

To again use the user manual as an example, there are many placeholders in the LaTeX compile format that evaluate to LaTeX syntax. If I wanted to create an ePub, I would go through that whole list and turn them into HTML equivalents.

Project replacements, the ones in the tab on the right hand side of the compile overview area, are more truly global.

In combination with these two approaches, and the custom metadata approach for outline-specific output, I’d say most of the things one would need of this concept are addressed in Scrivener. And for plain-text and Markdown outputs, where one can add a post-compile script into the process, you can really go into conditional variables too. That’s also something I do with the manual, particularly with keyboard shortcuts, where sometimes I just want to say “Shift key” but other times I want to use the keycap symbol for Shift. Or sometimes I may want to use small-caps for abbreviations like “PDF”, but not if the abbreviation is found in a heading (where “pdf” looks silly in the sidebar ToC). So, if you need that kind of conditional stuff, you won’t find it anywhere in Scrivener’s interface save for the hook to enabling further scripting.

3 Likes

If you use List or Checkbox custom metadata, this is exposed in the Outliner and you can group select and set this for all selected values — this is from the Scrivener manual, which uses a list to define the platform used for filtering at compile, note I can select and change multiple document values:

But if you need free-form text values, I don’t know of an easy way to group edit all custom metadata fields (a default text value would be a nice upgrade here).

For replacements, you may already know, but there are two places to define them, globally for all compile formats, and specifically for each compile format. This gives you great flexibility for both format-specific and general replacements (edit: same point made by @AmberV :+1:)…

2 Likes