Scrivener and technical manuals

Hello everybody,

May I ask you some help with technical writing with Scrivener? I know the app’s manual itself is a good example of this – and during the years I have explored it multiple times – but I’ve still some questions unanswered.

I usually start the early draft of long projects in Scrivener, used as a glorified outliner, an imaginative scratchpad, and a malleable word processor.

However, when it is time to mix text and images, for example to create illustrations with highlighted details, captions and referring lines, I have to switch to a page layout program (that is currently InDesign). I try to make this moment as late as possible, but it usually comes much too soon.

But I’ve just completed a long project that has made me realize once more how inadequate it is working in InDesign for this type of projects. In this project, ID proved itself extremely slow, buggy, prone to crash, even incredibly slow to (re)start.

And it unable to make one have a clear view on the project. It’s a linear things, and if you want sort of a general outline you have to print an extended ToC. Balancing far parts of a long project is incredibly complicate.

I would therefore like to go a step back, and see if I can do without some of the graphic tools offered by a layout program, and do everything in Scrivener. I’m not totally sure this can be done, but let me ask.

  • I seem to understand that linked image files have an absolute path, but it is easy to batch-relink them in case you move the images or the project to a different place.

  • When resizing images in Scrivener, their metadata is altered in the original file. Can this be catastrophic, if the image has to also be used by a different project? Is there a way to avoid the original file to be altered?

  • I don’t seem to see image styles. So, if I want to give all my screenshots a shadow, I can’t likely be able to do it, and to change it en masse at a later time.

  • The Scrivener’s manual starts each chapter with what looks like a full-page image, or at least a full-page fill with placed text (but it is probably the former). How is this done? Are multiple master pages possible? Or, can linked/imported images go up to the page border (or even further)?

  • I have to have my projects translated by external agencies. They work with CAT software, accepting some standard file formats. I need to receive back the project with its layout intact. With InDesign, I give them an IDML file, and they give me back a translated IDML file, that when opened in InDesign rebuilds the page as in the original.
    Can it be the same with Scrivener? How is it done? Can I just give them the Scrivener project, and the CAT software will just read the included RTF files, and treat them as any other RTF file? Maybe I should send them the (project)/Files/Data/ folder, asking them not to alter the folder structure?

  • While I’m still asked to make PDF files as the final output, and probably will still need PDF files for exchange with the proofreaders, I think it is time I switch to ePub as the output of things that will end being read on laptops, tablets and big smartphones. How’s Scrivener as an ePub generator? It looks fine on the paper (Ok, with no paper). My target file format will be ePub3.

  • Also, I will sooner or later output as webhelp. How is it HTML5 export, in Scrivener?

That’s it. I’m going now, because I have to experiment with exporting my text, images and styles from InDesign to Scrivener.

Paolo

1 Like

Paolo,

The source for the Scrivener manual is available as a Scrivener project at User Manuals | Literature & Latte (very last option on the drop down menu). The process they use involves LaTeX (and one or two other tools) to produce the PDF document. Search around on the forum - I seem to recall a post or two describing the process in some detail.

Just an observation … you seem to be trying to bend Scrivener to your will. As a first step, please realise that Scrivener is intended to be a tool for writing stuff. It’s got a lot of power to compile into something, but it’s not inDesign. It’s not Microsoft Word–which can put shadows on images :wink:.

You are doing that by starting the early drafts. I think you give it short shrift to use it only as a “glorified outliner …” But it’s not a tool to do a lot of tweaking of images which you have found out.

I’ve written numerous technical documents with text and figures in Scrivener. I do all my image manipulation in other packages (PowerPoint, OmniGraffle, Excel for tables, Numbers for Tables, … whatever suits). Admittedly the destination of my work is not into the publishing industry as you are doing, but it works well for me and my customers. I use the LaTeX template, tweaked it for my needs, and go with that. For you to follow that path to make LaTeX processing work for you will require some LaTeX expertise you may need to source. I’m not recommending that–just mentioning that’s a path and I use it.

Thank you for your answers!

Yes, I’ve studied it several times. A bit different from my style, but extremely useful to learn the deepest secrets of Scrivener.

Oh, no, just asking the best it can do for me! All considered, L&L themselves have shown that you can go past the initial goal (drafting), and made their own manuals with Scrivener.

While editing the raw image with dedicated editors, there are things that are more comfortable to do in the layout program. Take the shadow again: by adding this property to an object style, you can the make it lighter or darker en masse for the whole publication. Something that can’t be done by editing the original images, that would have to be edited one by one. (Batch processing may be a solution, but a dangerous one, since you don’t act on an object style but on the original data, and you might include unwanted ones).

I wouldn’t have particular problems in using LaTeX, since I’ve started experimenting with it decades ago. The real issue is that I’m not particularly convinced by the appearance of projects made with LaTeX. It is perfectly appropriate in some areas (mostly academic), but I feel it might be less convincing for a commercial product. So, I would like to explore alternative routes.

Paolo

1 Like

User Manuals & Print

@ptram: I wouldn’t have particular problems in using LaTeX, since I’ve started experimenting with it decades ago. The real issue is that I’m not particularly convinced by the appearance of projects made with LaTeX. It is perfectly appropriate in some areas (mostly academic), but I feel it might be less convincing for a commercial product. So, I would like to explore alternative routes.

On that, just in case it isn’t known, the Scrivener manuals are LaTeX. I do agree with you that most of the stock looks are very academic, as you put, which is appropriate for how it is used most often. But is quite flexible and I don’t know if there are too many things a GUI-based system can do that it can’t. I would say the difference between LaTeX and traditional DTP is more a matter of how one accomplishes the result, one being very visual and the other being not visual at all.

There are pros and cons with either method—you’ve mentioned one of the cons with visual editors: large works can cause instability and slowness. The Scrivener user manual on the other hand is not small, but it typesets to PDF without any intervention in around 15 seconds for the first run, and 5 seconds for incremental updates in proofing.

Oh, no, just asking the best it can do for me! All considered, L&L themselves have shown that you can go past the initial goal (drafting), and made their own manuals with Scrivener.

I use Scrivener for what it works best for: building structure, or for how Markdown+LaTeX works, building instructions. You mentioned the chapter pages for instance, which for me are just the name of a binder item at level 2 in the draft folder. I do nothing more than that while working, and I don’t see or work with any of the following text examples while working.

When compiling, Scrivener turns this into a simple Markdown level 2 heading:

## Interface in Overview

For how I have things set up, level 2 headings like this are chapters, so we get:

\chapter{Interface in Overview}
\label{interfaceinoverview}

So from that you get the full-page spread you see. As you can see, it is still about as abstracted from the final result as the implementation in Scrivener! It takes the name of the chapter and puts it in a text box in the upper left corner, and then takes the automatically generated number and puts it in a lower-right text box.

That all said, the way the user manual is put together does not require LaTeX. That’s 100% the compile format that I’ve built for it. I could turn around and develop and ePub format for that same project, or even InDesign! Again we are using Scrivener for its primary strength of producing structure rather than formatting, and structure as we can see from the above examples, is very far away from formatting. Markdown takes that structure it creates and turns it into document formats suitable for formatting, be that .tex, .epub, .odt or .icml.

Oh, no, just asking the best it can do for me! All considered, L&L themselves have shown that you can go past the initial goal (drafting), and made their own manuals with Scrivener.

To come back to this sentiment then, knowing the above, I wouldn’t say so much that I’m pushing Scrivener past the drafting phase—it’s more that the system I’m using with Scrivener greatly broadens the definition of drafting. I can get that user manual PDF by clicking the Compile button, but that’s not because Scrivener has anything to do with the PDF, rather it’s using a system that is really good at making PDFs, and is really good at taking structured text, from a system that is really good at producing structured text. It is in my opinion the ideal approach because it meshes a lot of mutual strengths.

You could take that approach and end up with an ICML file, yes, and with tweaking you could probably get pretty close to a “one shot” InDesign workflow that requires very little work after compiling. It’s not something I’ve ever tried myself, but knowing the extent to which this system works well for me with .tex files, given how it works, I feel it would have plenty of capability and flexibility.

While editing the raw image with dedicated editors, there are things that are more comfortable to do in the layout program. Take the shadow again: by adding this property to an object style, you can the make it lighter or darker en masse for the whole publication.

I would not say that’s a characteristic that is unique to visual layout programs—rather it’s just one of the thousands of reasons why Scrivener is not a production tool! We can after all get something like that in ePub with a very simple declaration, pasted into your compile Format’s CSS pane:

figure img {
	box-shadow: 6px 6px 15px rgba(0, 0, 0, 0.42);
}

Done and dusted. Maybe you want it to be fuzzier, so you change it from 15px to 25px, and the whole book updates. You have the same kind of power with LaTeX too, of course.

But with Scrivener by itself, using no other technology and trying to replace an entire workflow? There is nothing for that, and I don’t know what it would take to make that efficient.

ePub

So speaking of CSS, and to return to something you mentioned in the first post, I think maybe we are getting hung up on the PDF a bit much, and the technology that goes into making those. For print (or digital similar), I would not ever consider using Scrivener for production. It is to my mind uniquely unsuitable for that task, while it is uniquely amazing at working with tools aimed at production. It’s a quintessential early link in the chain, not the chain—and whenever I see people trying to make it act like the latter, it seems to produce nothing but frustration (much like writing a book in InDesign itself must surely be a nightmare, I just don’t understand why anyone would try so hard to avoid using the best tool for each aspect of the job).

For ePub though, this is another matter. Ebooks do not have a very high bar when it comes to production because there is no production to speak of, from the creation side of things, outside of the manual and technical labour of assembling HTML, CSS and a few simple XML files. That part of the job is so simple that you can create an ePub file with nothing more than Finder and a coding editor.

So for that, Scrivener does quite well, not only because it is a simpler matter to produce an ebook, but again because it is really good at creating structural stuff: and ePub is all about structure.

Would I use Scrivener’s built-in ePub generator? No, mainly for these reasons:

  1. I prefer writing using Markdown in general, to messing around with palettes and toolbars.
  2. Scrivener’s ePub production actually converts the rich text source to Markdown, and then uses that to generate the HTML. So why would I rely upon machine conversion to produce source I can get just by typing? I would have to really prefer clicking on toolbars to take that approach.
  3. The compiler has integration for Pandoc’s ePub generator, and on the whole I would say the quality of it is cleaner and less “quirky” than the complexities that come from all of that machine-generated output. I’m not ever going to get a <span style="color: #351799ff ">Blah blah</span> in my output, unless I myself create such a thing, whereas with Scrivener native I might very well get that and struggle to override it simply because that’s how I chose to depict some text in the editor.

Pandoc’s ePub generator takes a little more work up front, and it doesn’t have Scrivener’s CSS-generator front end that is essentially the majority of the compile settings—you have to know your CSS design to get a good result. But if you do, then having direct control over the result rather than “fighting the GUI” (how it feels for me), is preferable.

I would stress though that either Scrivener’s ePub or Scrivener+Pandoc’s is going to be great, and you will be hard-pressed to find a better ebook production platform anywhere. There are easier ones for sure (typically at the expense of flexibility, with template-driven stuff), but if you’re serious about making the best book you can, and are willing to invest time into learning HTML/CSS to do so, either of its routes will be deeply rewarding.

Also, I will sooner or later output as webhelp. How is it HTML5 export, in Scrivener?

It doesn’t. :slight_smile: See the bullet point above: we use MultiMarkdown to generate the HTML for ePub3, because the Mac’s HTML converter is stuck in the year 2002.

4 Likes

If you want more than one output, then the advantages of using a markdown intermediate increase significantly. Pandoc for example supports ICML.

As others have mentioned, LaTeX is supremely powerful. Scrivener’s manual is a great example of using styles for a lot of the heavy lifting, but it uses hand-rolled custom LaTeX post-processing. LaTeX, while powerful, is almost impenetrable to understand and usually requires a lot of searching for obtuse answers online. CSS is leagues better in terms of understandability, and while originally used for online layout can be used for Print.

If I were a technical writer this would be my workflow:

  1. Scrivener to manage my media using styles to generate Pandoc markdown.
  2. I would use Pandoc filters for layout tweaks that could not be solved by Scrivener’s styles.
  3. I would use “live” figures where possible using Pandoc-plot
  4. I would not use LaTeX for PDF, but focus on HTML. I would probably use PrinceXML, a HTML+CSS > PDF engine that can do a lot of print-friendly layout tasks.

Focussing on CSS means using CSS for BOTH EPub + PDF workflow is much more streamlined than LaTeX for PDF and CSS for EPub or online manual.

There is an interesting new technical publishing system called quarto:

It has some cool layouts, including Tufte style sidenotes, supports multiple outputs including all those you mentioned and could be easily hooked into Scrivener.

4 Likes

Thank you very much for your answers and tips!

I’ve been exploring the various additional instructions, and learnt something more. And I have some unresolved doubts. Here are my considerations on a possible workflow:

  • The original manual will be made in Scrivener. This must remain the reference document, the one to which to return for revisions.

  • Outputting to a DTP program must be immediate: compile to Pandoc, convert to ICML, load in the DTP program (InDesign, Publisher). Do this for separate chapters. But with no further editing in the DTP program.

  • In Scrivener all images will be linked. They should remain linked when exporting to a DTP program. Is this possible? Are links preserved?

  • Images and captions will have to be made in the graphic program. Add to the original image layers with circled numbers and referring lines. Captions as text must be avoided, since they can’t be freely placed around the image in Scrivener, and are difficult to translate if in a separate graphic program.

  • All translations will have to be made in the IDML files exported from the DTP program. Scrivener will not be considered in this phase.

  • Updating the original has to be done in Scrivener.

  • Updating translations have to be done on the IDML files: the CAT tools will compare the new source IDML with the existing translated IDML files. This will appear exactly as now to the translators.

  • Annotations and sketches will remain in Scrivener. This will be incredibly more practical than doing it with fake-stickies on InDesign’s pasteboard.

  • Made free from annotations, the layout file will be always perfectly clean.

  • Proofreading will happen on the PDF exported from Scrivener. If a more final version will be asked, a draft will be made by exporting from Scrivener to the DTP program via Pandoc. Corrections will be made in Scrivener. Replacing or retouching obsolete images will happen by choosing the Reveal on Finder (or equivalent) command, and opening the image from Finder.

If this worked, maybe it wouldn’t be all that complicate.

Paolo

Note that images and captions are exported into “named paragraphs” by pandoc, for example my sample workflow project (https://github.com/iandol/scrivomatic/blob/master/Workflow.scriv.zip) that uses inline images linked to binder images and caption style for the captions compiled to ICML gives:

<ParagraphStyleRange AppliedParagraphStyle="ParagraphStyle/Figure">
  <CharacterStyleRange AppliedCharacterStyle="$ID/NormalCharacterStyle">
    <Rectangle Self="uec" StrokeWeight="0" ItemTransform="0.25295 0 0 0.25381 296.5 -427">
      <Properties>
        <PathGeometry>
          <GeometryPathType PathOpen="false">
            <PathPointArray>
              <PathPointType Anchor="-296.5 -427" LeftDirection="-296.5 -427" RightDirection="-296.5 -427" />
              <PathPointType Anchor="-296.5 427" LeftDirection="-296.5 427" RightDirection="-296.5 427" />
              <PathPointType Anchor="296.5 427" LeftDirection="296.5 427" RightDirection="296.5 427" />
              <PathPointType Anchor="296.5 -427" LeftDirection="296.5 -427" RightDirection="296.5 -427" />
            </PathPointArray>
          </GeometryPathType>
        </PathGeometry>
      </Properties>
      <Image Self="ue6" ItemTransform="0.25295 0 0 0.25381 -296.5 -427">
        <Properties>
          <Profile type="string">
            $ID/Embedded
          </Profile>
          <GraphicBounds Left="0" Top="0" Right="2344.32667" Bottom="3364.7797" />
        </Properties>
        <Link Self="ueb" LinkResourceURI="file:xkcd_brain_hemispheres.png" />
      </Image>
    </Rectangle>
  </CharacterStyleRange>
</ParagraphStyleRange>
<Br />
<ParagraphStyleRange AppliedParagraphStyle="ParagraphStyle/Caption">
  <CharacterStyleRange AppliedCharacterStyle="CharacterStyle/Bold">
    <Content>Figure 1</Content>
  </CharacterStyleRange>
  <CharacterStyleRange AppliedCharacterStyle="$ID/NormalCharacterStyle">
    <Content> — This is a fascinating caption (source and explanation: </Content>
  </CharacterStyleRange>
  <HyperlinkTextSource Self="htss-9" Name="" Hidden="false">
    <CharacterStyleRange AppliedCharacterStyle="CharacterStyle/Link">
      <Content>XKCD</Content>
    </CharacterStyleRange>
  </HyperlinkTextSource>
  <CharacterStyleRange AppliedCharacterStyle="$ID/NormalCharacterStyle">
    <Content>).</Content>
  </CharacterStyleRange>
</ParagraphStyleRange>

Note the image is exported by scrivener and linked to the same folder as the ICML, surely this should work when imported? I’ve never used InDesign but the fact is this ICML is semantically identified and so can be parsed and transformed by tools.

I attach the full ICML file for you to look at, you could see hoe this loads into InDesign compared to the PDF seen here: https://github.com/iandol/scrivomatic/blob/master/sample-output/workflow.pdf

ICML.zip (45.3 KB)

1 Like

Yes, it is, and it works correctly:

Thank you for pointing to the Workflow.scriv file, and the corresponding ICML file. This should give me a good idea of how things are converted. I will also be able to do some experiments with file paths.

For example: Will the link path be something like “/Links/”, instead of the same directory as the ICML file?

Another point I forgot to mention: Is is possible to create table styles? So that one can have a different style for a table dedicated to parameters, and another for separate notes? And, also, have different styles for table headers and body cells?

Paolo

By default the folder is the same as specified for Compile, so that the markdown and images will all share the same folder. I’m not sure if you can change this in the compiler (at least I don’t see an option and have forgotten if it is possible). But you could write a script to do that, again the XML is quite easy to parse…

Styles can be applied using Pandoc’s custom style blocks for ICML – Pandoc - Pandoc User’s Guide

::::: {custom-style="SpecialTable"}
| **Table Head 1** | **Table Head 2** | **Table Head 3** |
| ----- | ----- | ----- |
| Item 1 | Item 2 | Item 3 |
| Item 4 | Item 5 | Item 6 |

: This is a table caption
:::::

and table headers and body do receive different styling:

  <Cell Name="2:0" AppliedCellStyle="CellStyle/Cell">
    <ParagraphStyleRange AppliedParagraphStyle="ParagraphStyle/TablePar &gt; TableHeader">
      <CharacterStyleRange AppliedCharacterStyle="CharacterStyle/Bold">
        <Content>Table Head 3</Content>
      </CharacterStyleRange>
    </ParagraphStyleRange>
  </Cell>
  <Cell Name="0:1" AppliedCellStyle="CellStyle/Cell">
    <ParagraphStyleRange AppliedParagraphStyle="ParagraphStyle/TablePar">
      <CharacterStyleRange AppliedCharacterStyle="$ID/NormalCharacterStyle">
        <Content>Item 1</Content>
      </CharacterStyleRange>
    </ParagraphStyleRange>
  </Cell>
1 Like

Thank you for pointing out to these instructions!

But I apologize for asking the obvious – isn’t this just a custom paragraph style? What I can’t see is a way to create table styles (and, as an aside, object styles).

With table styles I mean a style that will apply predefined border, fill, alternating row coloring, paragraph styles, to a table. This could include row styles, where these properties are applied to an individual row (like a sub-heading row in a table).

And a similar question is the one I was going to ask for object styles – for example, the one deciding how an image or a text frame is placed in page, if it has a border and a shadow, how it will float on the page.

Just hinting here: maybe some CSS code can do it? Can this be entered right in Scrivener? Can it be compiled to a DOCX or ICML document through Pandoc?

Paolo

Pandoc only offers block (aka paragraph or div) and inline (aka span) style labels…

… and so special table styles are IMO too specialised to be represented. So that is the only solution that can be offered. If you can envisage it as a block or a span, you can apply semantic labels that can align to styles. So you could use inline styles within the table rows; but that will only work for the contents, not the cell itself (tables are complex hierarchies of blocks inside blocks after all)…

But more complex logic like alternate rows requires the actual layout engine to intervene… My suggestion was to allow you to “label” the table so that a custom script could transform the XML after pandoc finishes and before it is imported to Indesign. Pandoc also allows Lua filters to run and another route would be a filter that could generate the raw XML itself based on the style tags, but that is a non-trivial programming job.

What is an “object” semantically; like a block? This is very specific I think to the way InDesign documents are constructed?

Again, pandoc represents two kinds of labelled things, blocks and inlines. It does not represent any kind of layout or styling, that is the job of the output processor. So yes, you can semantically label something like an [info box] block and then in CSS you can float that box, wrap text around it, make borders etc. I did suggest that HTML+CSS using something like PrinceXML can generate any kind of final layout you desire. I do not know anything about InDesign, but in general GUI programs are always more limited when it comes to automating complex transformations, unless you can use some sort of scripting language in InDesign or you can rewrite the XML using rules.

1 Like

My idea is that Scrivener could export blocks marked with a class like “ParameterTable”. If Pandoc can convert this into an ICML table style, when opening the ICML file in InDesign, this latter could associate the imported style with one of the table styles already in its template.

Maybe this is a test I can do. Let’s see if I can add some CSS code that might work. I must understand better how the “fenced syntax” works. My guess is that it continues to be a paragraph styles, and not an object style.

Feature suggestion to the Scrivener developers: add table, cell and object styles next to paragraph and character styles!

Paolo

Yes, a block with a custom style like this:

:::{.warning custom-style="warning"}
This is a warning box, containing terrifying information.
:::

becomes this:

<ParagraphStyleRange AppliedParagraphStyle="ParagraphStyle/warning &gt; Paragraph">
  <CharacterStyleRange AppliedCharacterStyle="$ID/NormalCharacterStyle">
    <Content>This is a warning box, containing terrifying information.</Content>
  </CharacterStyleRange>
</ParagraphStyleRange>

This mapping is “hardcoded” by the ICML writer. But what advantage does an “object” afford, this seems to be specific to ID? HTML also has only two fundamental types of containers: blocks and inlines, and everything else is a variant of these (<p> is a type of block, <i> a type of span etc.) — CSS can of course override this logic using display: to make inlines float, and blocks flow. I think everything is possible just with generic containers, remembering that blocks can be nested…

An important concept to understand is that pandoc uses a semantically universal intermediate for any conversion (called the Abstract Syntax Tree or AST); it is like if you had 10 human languages and you wanted to translate any pair, instead of building many unique mappings, you would use 1 intermediate and so you wouldn’t need to translate every possible every pair. But if the AST does not represent it, the translation will fail (for example markdown doesn’t support underline and so the AST did not represent it).

The fenced syntax is just the way of assigning parameters to block or inline chunks of content, so for example [This is *some text*]{.myclass mykey="myval"} will assign the myclass class to this span of text and a generic mykey parameter. custom-style is a “special” parameter that gets converted into DOCX or ICML styles. Again you could create a pandoc filter that would take a named parameter and rewrite that thing into some specific output. For example pandoc does not natively support turning fenced divs into custom environments in LaTeX, but a pandoc filter could search for all fenced divs and convert them into the correct LaTeX markup.

1 Like

I would think that the equivalent of object styles are classes in CSS. An example of their use is to have images aligned in a particularly way (inline, or relative to the page), with a particular visual effect (shadow, transparency…).

Table and cell styles would add attributes to the table parts that are not only relative to text. Fill color, border size and color, horizontal and vertical content alignment.

I wouldn’t personally want all these properties in Scrivener, but it would be very useful to be able to attach this class to an element, and have it translated into an InDesign document. Details would be set by the styles in InDesign.

Paolo

Feature suggestion to the Scrivener developers: add table, cell and object styles next to paragraph and character styles!

Alas, all of that is is probably way outside of anything Scrivener can do. Styles don’t even play well with simple bullet lists, let alone tables. Both are essentially “black boxes” in the text engine.

I wouldn’t personally want all these properties in Scrivener, but it would be very useful to be able to attach this class to an element, and have it translated into an InDesign document. Details would be set by the styles in InDesign.

So I take it InDesign can’t do the things you would like for it to do if the image+caption is found within a paragraph that has a particular class attached to it, it has to be the image object itself that is styled?

I don’t know what is happening behind the scenes, but in InDesign you have object styles separated from paragraph styles.

Therefore, you can have a paragraph with an “Image” paragraph style applied, setting a particular text alignment and upper/lower spacing. In this paragraph you could place an image, to which you apply an object style setting things like transparency, shadow, text runaround, and so on.

Object styles can be applied not only to images, but also to text frames. This is particularly useful for complex layouts, like magazines, where you have floating text boxes containing different articles or subsidiary text.

I would guess object styles have an analogy to classes applied to divs in HTML. So, maybe it is already possible to do them in Scrivener, and even have them converted by Pandoc.

Paolo

It’s pretty rare to see an HTML layout with anything approaching the complexity of a magazine or a technical textbook, though. Technical ebooks are usually distributed as PDF files. (As is, for instance, the Scrivener manual.)

My HTML skills are rudimentary, but that says to me that using HTML to build complex layouts that will be portable across devices is difficult enough to offset the obvious benefits.

Apple releases their manuals as ebooks. Not a complicate layout, but not a banal one either. At the same time, there are several companies releasing manuals as web pages (the ones I’m thinking myself are Microsoft, Adobe, Steinberg and iZotope).

Paolo

To speak purely of what the HTML markup language is capable of, and even CSS, that can be settled with a practical implementation that already exists. I think it was even mentioned above, but here is a publication system that is based upon HTML and CSS.

Scrolling through those examples is more like looking through a show-case of what a DTP can do.

So really the question is more: what can the rendering engine do. Stuff like InDesign and LaTeX are naturally suited toward print layout, but the syntax used to store those formats is roughly on par with what HTML can store—structurally speaking. After all ICML is XML, and so is properly formed HTML.

At the level of implementation though, stuff like PrinceXML aside, most HTML+CSS rendering engines are not on par with print layout engines—but that’s mainly because they have a different purpose, a different set of challenges to face. Print doesn’t need to conform to a huge variety of different displays. It doesn’t need to reflow dynamically in real time as you resize a viewing window. Print rendering can take more time to get a perfect look because of that. Sacrifices have to be made to the quality of the typesetting in order to keep things fast and capable of being recalculated on very resource-limited devices like a Kobo.

After all, HTML+CSS are used to create software these days. Complex layouts like the user interface in your web browser, all go back to these technologies.

@ptram: I would guess object styles have an analogy to classes applied to divs in HTML. So, maybe it is already possible to do them in Scrivener, and even have them converted by Pandoc.

Yes, if that’s the kind of thing you need then that should be possible. This is very “WIP”, and largely built for one use case, but this compile format will create an ebook using Pandoc:

Bracketed Design.scrformat (53.8 KB)

If you scroll through the Section Layout previews in the compiler, you’ll see this “fenced block” technique being used to mark parts, chapters and various other types of sections. Editing the Format, you’ll see styles are being used similarly in some cases (like Transcript), which are used to enclose blocks of text in the book with some form of class.

Without thinking of implementation at all, this is how Scrivener can help with defining the structural content of a document. I don’t have to put the fence codes into the text, I can just mark some text as “Transcript” and leave how that looks for later (although in this case the format has CSS for all of these special containers I’ve created).

That concept is how we could create the tip box example above, without having to put the codes for it into the editor. That is of course a very similar concept to how the user manual structurally defines its text, though in that case the compile format is designed to produce LaTeX rather than HTML. The same could be used to general more expressive ICML structure.

The question remains though of whether or not the tools it provides for doing that are sufficient for what you would need to effectively apply a look to the document in InDesign. That part I have no experience to answer the question. I know I can do just about anything I would need to do with LaTeX and HTML, but cell level formatting without a lot of apparatus may be “noisy”, or require a lot of style usage in Scrivener to reduce that noise. Or it just might not be able to do exactly what you need because Pandoc isn’t set up for precisely that problem. I’d say it’s worth trying though.

1 Like