Current CSS engines far surpass in complexity anything that print requires. And while print is not the main focus for CSS, it does formally contain a full paged CSS 3 spec:
And some guides for it apart from the very helpful PrinceXML forums:
The biggest challenge to print layout I don’t think is technological at all, it is personal! Aesthetic and page specific decisions must be made about layout that algorithms cannot easily substitute, that is where a DTP program excels as it allows a visual analysis at the page level in a way that compile+refine code does not. Luckily for paged media CSS, I think you can get quite quick previews using browser engines, so this ameliorates the problem a bit…
I’ve unfortunately not been able to devote some time to testing the latest examples you sent me. I’ll have to try them after the rush I’m in has ended.
Something I’m considering, however, is how illustrations can be simplified in a project that has to be released as an ebook or as webhelp.
Text captions around an image would, for example, be better replaced by numbers referring to caption under the image, so that supporting multiple languages would be easy even in a workflow nearly entirely in Scrivener.
And effects could be added in batch to the image file itself, as a non-destructive layer of effects. Not as handy as an object style, but it can work. However, I’ll like to explore the “object style” solution proposed above, as soon as I can. It would leave maximum flexibility, when finally importing the Scrivener output to a page layout program for release in the final format.
My guess is, however, that making the project graphically as simple as possible would even make any third-party program redundant. Develop in Scrivener, output from Scrivener. Maybe just retouch the output with another program. And maybe just use that program (say, InDesign or its alternatives) as the source for translations.
Scrivener is excellent on its own for exporting to PDF, RTF, ePub. If you are happy with the results, and are able to do some customization to the output format, it may be all you need to produce a bare-bone technical manual.
The LaTeX workflow is more complicate, but reasonably easy. If you like to use the available LaTeX formats, and you want to put your fingers into some LaTeX code, it is a powerful option.
Going to the ‘industry standard’ file format, InDesign, is possible and not too laborious. You can use the Pandoc integration to output ICML files, that will be then imported into blank InDesign files. This preserved, in my tests, at least links to images and paragraph styles.
IDML files are not supported. Translating the final document with the help of tools supporting IDML files can be done by exporting from InDesign. You don’t translate the Scrivener files, but the finished project.
Finishing touchup operations in InDesign can be minimal.
If you want to edit the original Scrivener files for a new version of the project, you have then to repeat all the Scrivener → ICML → InDesign procedure. If only part of the project is changed, you can import/export just that part.
Exporting the final project from InDesign to Scrivener doesn’t seem easy, if even feasible at all. Scrivener can’t import IDML files, that are InDesign’s interchange file format. RTF loses too many features to be viable. I must add that I’ve not been able to import RTF files with the paragraph and character styles intact. Linked images are not supported on export from InDesign to RTF.
In summary, I would think the Scrivener → InDesign process to be even easy. Importing into Affinity Publisher is at the moment not feasible, since Publisher doesn’t import ICML files, and Scrivener doesn’t export IDML files. I can’t see alternative solutions that can preserve features like external links intact.
Going the other way round seems to be too hard to be considered feasible. This is a real issue if wanting to reuse an existing InDesign project in Scrivener. I don’t know how it is if wanting to update a project born in Scrivener and finished in InDesign; maybe the two can be kept in sync, and a major revision from Scrivener wouldn’t require exporting/importing from InDesign.
Maybe some more import and export features in Scrivener could make the whole process faster and easier for the uninitiated.
After some learning and trying, I fear the type of huge, illustration-rich, user manuals I deal with can’t be done with Scrivener + LaTeX. There are too many images, and composite images, that make it a design work, more than a text work. And Scrivener + LaTeX seems to excel in text-heavy documents, with minimal attention to graphics.
My user manuals are mostly made of procedures with text and images. Images are usually screenshots, cut and resized for a particular step. The base image is masked and blended with other images and figures, to highlight a detail. The full assembly has then to get the desired effect (usually a dropped shadow, only applied to the containing frame).
With a page layout program, like InDesign or Affinity Publisher, all the assembly is made right there, in the same document containing text, images, effects. If an image, that is used in several composite images, is updated, one has simply to open the page layout document, and everything is automatically updated.
If working in Scrivener, the composite images have to be made with a drawing program (like Affinity Photo). If a base image linked from several images is updated (say, a screenshot linked in various images highlighting a different detail), one has to open all the relevant images in the drawing program, to let them be updated. But since one can’t know where all the images are linked, it is likely that all the images have to be reopened from time to time, to be sure they are up to date.
I don’t see this latter very easy or comfortable to do. The alternative is to use easier images, with no masking, and separate images for each detail. But this would in any case require constant updating of the extracted details. Then, this would remove the details from context, and this would make for less clear instructions, and – frankly – visually a bit boring.
Maybe I should admit that user manuals are, in any case, quite boring.
I think the overall thrust of what you’re saying is that LaTeX isn’t as good for doing things how you would do them in a visual desktop publishing tool, and this is seemingly leading you to state therefore LaTeX is not very good at making books like this, but I don’t entirely agree that follows. These are two distinctly different things in most cases—there could be exceptions, yes, strengths and weaknesses that the two different systems play to—but overall I think the result is rarely uniquely defined by the process.
Whether we greatly prefer one process to another is separate, in other words, from what we can do with that process.
To get a little more specific, you describe a workflow that is uniquely efficient and useful in a visual layout environment. That’s fine, and that’s probably the best way to do things if that is the type of tool you are using. But we could achieve the same end result with a different process: for example using a design program to create the composites, which are themselves flattened to vector and placed into the text flow as finished pieces in a mostly automated fashion—rather than, if I understand you correctly, attempting to composite in LaTeX and somehow orchestrate that from Scrivener.
I think the Scapple user manual is a good example of that approach at this point, though you may not guess it by looking at it, as it does use a more traditional layout. While I am not using that approach to diagram around the screenshot so much, as you describe—that is essentially irrelevant because the way in which Scapple screenshots are assembled are essentially just that: they are vector representations of what a Scapple board looks like, saved to a composite format (PDF) and included as that in the LaTeX document. There are very few raster screenshots in that manual. Everything else is essentially an illustration much like you’re describing, just with a very specific and constrained design goal to make the illustrations mimic Scapple’s design to the point that most will never notice.
If I need to add something to an illustration, or wiggle something a few pixels down, I can very easily open the original SVG and export it back to PDF. I can even do that from within Scrivener given its toolset (bookmarks, hyperlinks, linked images that can be refreshed, etc.)
That, from what I understand, would be six or seven different assets for you—assembled on a canvas that is a DTP. That’s what I mean by catering to the strengths of the platform with the process, that would be a very inefficient way to use LaTeX—but in both we can achieve the same sort of result.
And I don’t even think that would be different if the illustrations were a more dominant component of the layout, with less text, rather than being the simpler single-row + caption elements as they are in the Scapple manual—that’s just a design choice really. Say if I wanted to go for a more magazine style look with the manual, with text flow and full-page spreads, etc. I could still easily do so with LaTeX, particularly if I had around half a dozen core layout designs that assets were slotted into. Then it becomes more a matter of semantics, which LaTeX is good at. This image is a “top-left asset” in a “three-screenshot page”. We can articulate things like that with \layout-threescreen{tl}{filename.pdf}. It’s far from visual, but if you know the “language” you built to describe these layouts, that doesn’t matter too much, and Scrivener is going to do a good job of helping us build that kind of structure (assuming we don’t just type it in, as it really wouldn’t be so hard to do so).
The caveat I spoke of earlier is probably where a design tends to diverge from any semblance of procedural design at all. I don’t know how common that would be in book format, or even magazine, given how intensive the workload becomes for each page. Like I said above, you’d more typically have six or ten layouts that you select from to suit the material, with a few exceptions here and there perhaps, rather than having each page be a hand crafted art piece. But if it is, well yeah, GUI DTP is probably the best way to go.
As for Scrivener’s role, it’s less of a factor here I would say, save for the fact that it works better with a system like LaTeX than it does with a visual system as the output. At least with the former you can typically get all the way to the final layout with a single compile. I don’t think there would ever be any way of doing that for DTP, and Scrivener would 100% become a more “first draft” tool that you only use for an early part of the process. Where Scrivener excels, in my opinion, is in generating instructions for typesetting engines. That can be LaTeX, but it doesn’t have to be, there are other systems that work within that realm, that are perhaps better suited to more freeform designs.
To return to the top though: I think most of this comes down to preference. I would be very inefficient and out of my element in a visual DTP, and prefer text-based methods of describing layout. So the manner in which I use Scrivener, and how I build automation around it for the assets, is all catered to that way of working. That, were I to apply my process directly to a DTP workflow, would probably me more of a hindrance than anything.
@AmberV , thank you for your detailed answer. I can’t say that I disagree with what you say. On the contrary, the type of workflow I’m trying to achieve is the one you are describing.
But I should probably describe a bit better how I deal with the images in my manuals.
Capture the screenshot in a raster drawing program.
Import it in the page layout document, as a floating frame/box mixed with text. Import at in any occurrence you need it.
Add to the same floating box a second imported raster image, text, connecting lines, right in the page layout program.
This is an example of a floating frame with captions around the image:
When a new version of the software/product is out, grab a new screenshot, that will automatically replace the older one at any occurrence in the page layout program.
When translating the document, the translator will only have to translate the text in the captions, without having to deal with the images.
I could replace, as you seem to do, steps 2-5 with work done in a vector drawing editor, instead of the page layout program itself. The end result, after this assembly is created, will look the same when imported into Scrivener. I would even gain more flexibility in masking and effects.
(a) However, when having to replace the screenshots, you can’t expect them to be replaced in every assembly you inserted in Scrivener. You have to open the original assembly in the vector drawing program, and update the screenshot from there.
(b) Another issue is that you have to ask the translators to translate the text in the assembly, image by image. Keep in mind that I can end up with over 1,000 images in a manual, even without having to cut the separate details.
A viable workaround to (b) is to remove any caption from the image assembly, and replace it with referring numbers (not letters, or they would have to be translated in some languages). Captions will end up under the imported image, right into Scrivener. I like it less, but it works fine.
So, I would love to find a way to replace my workflow with something that gives me, at the same time, a clean workflow in Scrivener, but that at the same time could be visually something “popping out” of the page. And, at the same time, keeping detail and context together.
This is not only an issue I have with the LaTeX + PDF output, but obviously also with the Pandoc + HTML and Pandoc + ePub output. These all seem to call for the simplest visuals. Unless one wants to follow an extremely expensive and time consuming workflow in editing the image assembly to preserve the visuals, and at the same time get the comfort of Scrivener.
Page layout programs are not the right tool for manuals. They can do a part of the work really well (the visuals), but simply ignore all the work on structuring and text editing. Editing text in a page layout program is a hell. That’s why so many dedicated programs exist. At the same time, none of them have the same kind touch of Scrivener.
I’ve gone on doing hypotheses on how to change my workflow. There are some more considerations I had to do. Sorry if it may sound like a rant, but it is just a series of personal considerations on my personal workflow and convenience.
LaTeX is something that is too alien to me, but more that this it would be alien to my collaborators. As a consequence, it could be very ineffective during the fast production cycles we have to follow.
There are basic concepts that seem to come from a different world than the one in which someone grown in a print shop or in an IT industry can move with ease. It’s something that is embedded in a system that at first didn’t even consider accented characters, didn’t consider the existence of ‘foreign’ languages, didn’t allow free use of fonts more modern than the one used in the academia during the early 20th century, and forced the use of a predefined page margin calculated in inches.
LaTeX has for sure grown a lot, but it looks like a patchwork on a natively inflexible and impenetrable system. There is a reason why desktop publishing has been developed. I could make an analogy with LylyPond and Dorico in music engraving: both are very powerful systems, but I’ve seen software engineers give up with LylyPond, when having to do some ‘real’ work, and switch to MuseScore.
If going the LaTeX route, having to do simple edits, like adjusting an object position in page, or making a paragraph start in the next page, looks like a lot of typing and recompiling.
The final .tex file would also be very hard to use at the offices around the world. I can find Word experts everywhere; InDesign experts in most places; but hardly a LaTeX expert anywhere.
My best bet seems to be going for the Pandoc md —> ICML route, and using InDesign/Publisher to do the final adjustments to the output. While Scrivener —> LaTeX sounds like the most direct output (you only have to use a LaTeX editor, like TeXShop, to do the typesetting and the final retouching), it looks like going to a page layout program is not much more work.
From Scrivener, output to MultiMarkDown.
Use Pandoc to convert it to an ICML file.
If using Affinity Publisher, paste the ICML output into an IDML template.
Open the IDML file into InDesign/Publisher.
Do the final layout edits. If everything has been done correctly, the IDML file should result in a clean page layout document.
Generate the Table of Contents.
The master seems to be still the Scrivener project, with the InDesign/Publisher document only being the document prepared for print or PDF production. The InDesign/Publisher document would also be an effective way to send the source material out for translations, in a file format that is universally accepted and can be edited even without my support.
You can preview LaTeX side-by-side while you edit using synctex, this makes visualising your changes easy for those LaTeX users.
At least for Academics there are always experts in TeX lurking around your department, but yes I imagine apart from Academic publishers TeX knowledge is far from common.
I also find TeX incredibly impenetrable in terms of understanding how to fix a problem. It usually involves a package you find via stack exchange, but how that package solves your problem is mostly voodoo! But to be fair, there is nothing like LaTeX for solving complex and specific problems in publishing, some of the packages are so specialised it amazes me…
As a general point, it may be worth investigating the use of HTML + CSS for layout. There are millions of professionals conversant in HTML + CSS for web layout, and several tools like PrinceXML that offer layout to PDF specifically for technical publishing. CSS is much more intuitive in terms of layout, you really get an understanding of the page model, the box model, spacing, floats etc. in a way unparalleled by any other system. With scripting you can automate many repetitive jobs.
Since I foresee that I will have to go toward HTML as the main output format, and PDF will only remain as a residual one for those users who prefer it, and for the mandatory basic documentation that has to be included in a product as printed paper, this looks like the way I should explore with most attention.
Quarto looks like the most promising way of making websites out of Scrivener. In general, it looks like the most promising way of making online manuals.
There are clever templates/scripts that can make the Scrivener-Quarto workflow automatic. At the moment, none of these seem to be able to generate a multi-page website.
By following the workflow described here, and Ioa’s script, a Scrivener project can be output as separate markdown files. These can then be assembled in a Quarto project, and output as a multi-page website.
The index in the sidebar has, at the moment, to be compiled manually. I’ve yet to explore the automatic generation features of Quarto. These, however, can only generate an alphabetically ordered index, that would in any case have to be manually reorganized.
This latter looks, at the moment, the most promising workflow for what I want to do (authoring technical manuals in Scrivener, and making a website of them).
Despite KB’s intention not to implement this workflow in Scrivener, third-party templates/scripts are evolving, and may make the procedure easier in the future.
I’ve gone one step further with my experimentation. Here is what I’ve found.
Compiling for web, starting from the customized MultiFile Output templates, does work great. Editing the _quarto.yml file in Visual Studio Code is easy, and rendering is immediate. Minor edits can be tested immediately from there. I’m making the template grow to be more and more automated.
Using the same template modified to generate a PDF file is not working for me. The output ‘smells’ LaTeX, and there is no third-party template that would let me achieve a satisfactory look with a more modern scent (or, put in a fairer way, not conceived for academic works). I’m after something completely different.
Editing a template in LaTeX would be a very long task, and in the end I would still get something containing what I find to be limitations in that system (from the inability to generate accessible PDFs, to the idiosyncrasies with modern fonts).
I’m reverting to generate PDFs with Scrivener’s direct PDF compile option. With it, I can use the powerful styling system in the compile format editor. What I see is what I get. The final look can be good enough for what I want to do (technical manuals, not an elegant art book).
I have to deal with two parallel systems of linking images. One is based on the markdown syntax ({parameters}), the other on Scrivener’s internal one (<$img:link;parameters>). Choosing the one or the other for the output is semi-automatic, after having assigned to them a different character style (PDF Only, or Web Only), and excluded one of the two from the compile format. Actual captions have to be moved out of the markdown formula, and put under the image as a separate paragraph.
I would be happy of the early results, wasn’t if for the scary discovery that Scrivener can’t probably use SVG files as placeholder tags. At least, there is no way to make them compile, while PNG files are there.
Am I right? Can’t SVG files be included as placeholder tags, if the output is direct PDF? Is there a workaround? Is there any chance this will be added in a very near future? The alternative is to use something like a master Affinity Designer file, an exported PDF file for PDF output, and an exported SVG file for Web output. A bit maddening.
I’ve tried to use Typst as the print format with Quarto. Alas, Quarto doesn’t support books with Typst, only individual files.
I’ve gone back to the XeLaTeX format, hoping to be able to edit the template. But here is a first problem: a default installation of LaTeX (the one made by MacTex) doesn’t support SVG files.
The error message says that I should install rsvg-convert. However, this would make the system even more a patchwork. And then, I see that this extension would convert SVG files into PNG ones, rasterizing them.
I’ve incredibly often found people suggesting that high-resolution bitmaps are equivalent to vector images. They aren’t, if not for the heavy size of bitmap images, to be multiplied by hundreds.
Franky, I feel a bit out of my place, each time I fall back into the LaTeX world. I can’t deny to feel sort of a panic terror.
Something to keep in mind: Scrivener should be being rewritten to comply with Apple TextKit 2. This is a very high-quality typesetting engine. Maybe using the direct PDF is a good choice not only for its simplicity, but also for the good results it will get in the near future.
As I wrote above: I could already be happy, for my job, of the current text engine. Now, if I only could solve the issue of the running headers based on headings in the text…
How does that help Windows users? As a macOS user myself, I have no idea whether QT or whatever toolkit(s) the Scrivener for Windows development team are using but to retain feature parity in the event of a switch to Apple TextKit 2 on Macs, iPhones, and iPads there had better be some equivalent.
Actually, this is a problem I have with compiling. I know how to include variable text in the running headers from each document title, but this would be useless for me. I need the Binder ‘document titles’ to remain in English (to preserve the structure’s readability), and the actual translated titles to be part of the document’s text, as text headings (H1, H2…). The variables offered natively by Scrivener can only refer to document titles, not to heading elements in the text. At the moment, I don’t see how to build custom variables that can be converted, when compiling, to variable running header text.
The post of kewms in the link is referring to a different issue I have with exporting metadata together with the main text. That one is indeed an issues related to exporting.
Not directly, but it might be a trigger to switch to an equivalent system in Windows, if available. This is really one of the parts where the two versions are forced to diverge.
The tools used to build the two versions may differ, yes. But having put quite a lot of effort into achieving (near) feature parity, we’d like to keep it that way.
There is the svg package: CTAN: Package svg – but alas it seems to require a custom command so would need some post processing. It uses Inkscape to convert SVG to PDF so it should retain vector’ness’ at least (totally agree that vectors are essential in technical work).
Certainly agree, LaTeX can be so obscure and unclear. EVERYTHING is possible in LaTeX, but to get there can require such specific knowledge and endless searches. I am a geek, I can code stuff to solve problems, but in LaTeX I’m often left to other people to solve my problems always. This is the draw of a system like Typst, so much more transparent and elegant (if currently still too limited). Again if I was making technical works, I would invest in HTML + CSS + JS solutions as CSS is orders of magnitude more understandable than LaTeX and JS + HTML so much more tweakable than the closed behemoths like InDesign etc. PrinceXML + Pandoc should be able to do most of what LaTeX can…
At this point, I think I’ve decided to keep separate folders for
original Affinity files (.afdesigner), where I can automatically updated images containing linked images;
files that can be shared by the Web and PDF versions of the project, or are exclusive to the Web version (in .png and .svg format);
additional files for PDFs (in .pdf format, replacing the SVGs)
I don’t like this proliferation of files, but I fear there is, and never will be, an alternative.
At the moment, it looks like I can be happy producing Web sites from Scrivener with the Pandoc MMD → Quarto → Visual Studio Code workflow. They seem to work fine – better yet, surprisingly well. Customization seems relatively easy with MMD code in the Scrivener project, the _quarto.yml configuration file, and CSS.
The remaining problem is that I want/have to also produce a PDF and an IDML version of the Scrivener project. And I want/have to do it in a way that allows easy interchange of data with people using more common tools (typically, a DOCX-compliant word processor or a text editor).
At the moment, I’m stopped by some limitations in the direct PDF output of Scrivener faced to what I want it does (a workflow that I would probably prefer, due to its linearity), and by my inability to dive deep into the LaTeX code. In brief: I’m not paid enough to cover the amount of time I’m devoting to this task, and I’ve not been composing music for too long. I want to make music, not code.
IDML is another heavy task: the Pandoc ICML converter is very bare bone, and probably not good enough to generate a file that I can share with people wanting/having to continue working in InDesign. This may stop my plans entirely. But I’m still mumbling around it.
I could really continue making manuals in InDesign, maybe waiting for Publisher to become a viable and accepted, replacement, or simply compatible to the point to be able to generate files for InDesign users. But I feel that continuing to make manuals in PDF is something already on the obsolete side. Worse, writing manuals in InDesign is pure madness. Working in Scrivener is like removing a blanket from one’s mind. I would like to be able to do it.
