Forum How do I...?


I did not see it in the documentation, but I thought I would ask, just in case. Does Prince support (or plan to support soon) the CSS3 'sidenotes' concept?

CSS Sidenotes doc

Many of the document types I create need sidenotes instead of footnotes.

If Prince does not explicitly support css sidenotes idea. Can anyone thing of a way to create a sidebar of text that will always appear on the same page as some mainline text that it is associated with?

I can easily create a sidebar to contain notes, but I have not been able to figure out a way to tell prince that I want a side bar only on certain pages, or (as mentioned above) tied to certain main line text.

Thanks much,

The standard mechanism for sidenotes at the moment is to use floats with negative horizontal margins to pull them out of the body text. Have you tried this?
Not yet. I will do so.

Thanks Mike!
On second thought, I'm not exactly sure what you mean by this Mike. Can you explain in just a little more detail?

I have seen some examples that show pulling sidenote text out into a permanent margin on the side of the page. I think this is what you are talking about. Please correct me if I'm wrong.

What I need to do that these examples do not show, is that I do not want the margin on the page for pages that do not happen to have any sidenotes.

Many thanks,

Harding Marking Corp.
That's a bit trickier. Does that mean that the width of the main body text will actually vary, depending on whether or not there are sidenotes occurring on the page?
That is correct. Just like the footnote section takes no room in a given page when there are no footnotes, we need a 'sidenotes' section on the page that takes no room when a given page has no sidenotes.

I have a successfully created test documents that do each of the following. None of which is acceptable to our customers.

- Have a fixed border section for sidenotes.
- Have a sidenote box that appears next to the paragraph in which the sidenote is referenced. The box causes the referencing paragraph to shift over to make room.
- Have a full page height sidebar box, that I can define/undefine as needed in the html. The problem with this is that the sidebar box must be positioned exactly at the top of what would be a new page in the html, or it forces a new page and puts the box there.

It does not appear that Prince supports the proposed @sidenote directive. I was hoping that I might be able to accomplish something similar with a named flow, but have not yet been able to get it to do what I'm after. I can move the elements in a named flow off to one of the margin areas (ie @left-middle. But I have to permanently make room for this on every page.

At the moment this isn't possible, only the footnotes area can behave in this variable manner for each page. We can add support for a variable sidenotes area in the future, but it is more complicated than footnotes, as you can imagine with a simple thought experiment: if you are halfway through a page and you hit a sidenote, suddenly the page width will shrink, requiring the page to be repacked from the beginning at the new width. However at the new width the sidenote may be pushed down to the next page, leaving the sidenote area empty, and redundant! This issue can occur in rare circumstances with footnotes as well, but sidenotes may make it more common. This is one of the reasons we are grateful that many layouts with sidenotes leave a permanent margin on every page. :)
That kind of layout works for me with tables and images, though.

Wouldn't it be possible to do this with
display: table
float: outside
Interesting idea! Tables are pushed aside by floats. That might be worth a try...
Thanks for posting the idea. Unfortunitely I can not seem to get that to work. Here is what I have.

	margin: 72pt 36pt 36pt 36pt;
	size: US-Letter;

    float: outside;
    right: 0px;
    top: 0px;
    height: 800px;
    margin: 5px 5px 5px 5px; 
    padding: 5px 5px 5px 5px;

With content looking like:
	<p>1 Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam nonummy nibh euismod tincidunt ut laoreet dolore magna aliquam erat volutpat.  Ut wisi enim ad minim veniam, quis nostrud exerci tation ullamcorper suscipit lobortis nisl ut aliquip ex ea commodo consequat. Duis autem vel eum iriure dolor in hendrerit in vulputate velit esse molestie consequat.</p>
		<span class="sidebar">This is a new sidebar. Ut wisi enim ad minim veniam, quis nostrud exerci tation ullamcorper suscipit lobortis nisl ut aliquip ex ea commodo consequat.</span>
	<p>2 Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam nonummy nibh euismod tincidunt ut laoreet dolore magna aliquam erat volutpat. Ut wisi enim ad minim veniam, quis nostrud exerci tation ullamcorper suscipit lobortis nisl ut aliquip ex ea commodo consequat. Duis autem vel eum iriure dolor in hendrerit in vulputate velit esse molestie consequat.</p>

Remember I want the sidebar to be full page and on the same page as both paragraph 1 and 2 (the sidebar is between the two paragraphs to illustrate that it can come in anywhere in the content).

If the height is set to 800px, then things seem to place fine, but the sidebar is not full page in size. If I increase the size of the sidebar, then it gets pushed to the next page.

We have received approval from our customers for an alternative layout. But it would still be nice to know how to implement what we want, as I know this will come up again.
Right, it looks like this isn't quite enough to get the effect that you are looking for, and it's going to have to wait for implementation of the @sidenote area.
Thanks Mike.

If/When you do implement @sidenote, I would be happy to help test out the feature as you are working on it.

Andy Goar
Harding Marketing
I tried the float: outside ; to simulate @sidebar but I had places where two floats were close together and one covered part of the other float.

	  float: outside;
	     background-color: grey ;
	     margin-outside : -6pc ; 

Jim Albright
Wycliffe Bible Translators

hi mike, any news on sidenotes?
The next release of Prince will allow you to absolutely position the footnotes area to the side of the page, which is almost like sidenotes. But they won't vertically align with the footnote call in the text, so not quite.
hi mike, that'll do the trick -- can you tell me when next release is due out?
We hope to have a tech preview release ready soon.
I used Jim's trick to "simulate @sidebar", and it works wonderfully (thanks Jim!). But I ran into the very same problem: where two floats are too close together, they overlap each other. Is there, maybe, a special prince css-property one could use to avoid overlapping, which then would move the "later" elements below the "previous" ones?

Remark: I can live with a permanently visible sidebar which is empty on some pages, so I declared corresponding margins to @page:left and @page:right, which would make "moving down" (if necessary to the next page) a perfectly acceptable solution.

A simple "prince-overlap:avoid|allow" would do; others might prefer additional options like "left|right|top|bottom". When rendering the (currently overlapping) section, it should be possible to detect it and then react correspondingly. Maybe this could even be made the default behavior for (this kind of) floats.
I was able to help myself around, by introducing some manually applied "helper classes" to move the overlapping element down:

.down05 { margin-top:  5mm; }
.down10 { margin-top: 10mm; }
.down15 { margin-top: 15mm; }

However, independent from that, I sometimes encounter the strange behaviour that the object moved to the sidebar leaves "gaps" in the place where it had been when not moved to the sidebar, as you can see in this screenshot:

This does not always happen, and I could not yet identify a pattern. Also, in the attached example the last paragraph of the first page gets "split". While it's clear there's a "shift" needed, I had expected it to move the entire paragraph, and not to leave two words behind.

In case it matters: I'm running the latest version (8.1.5) on Ubuntu 12.04 64bit. If the source HTML is needed, just let me know and I'll create a ZIP including the images as well, so you could test this for yourself. Snipped for the screenshot:

<P><IMG SRC='screenshots/widget_ds.jpg' ALT='DroidStats Widget' CLASS='imgleft'>Widgets von <SPAN CLASS='qr' STYLE='width:25mm'><IMG CLASS='qr' ALT='QR' SRC='qr/playstore/nitro.phonestats_DroidStats.png'>DroidStats</SPAN><A CLASS='extern'  HREF=''>DroidStats</A>, die Informationen zu aktuellen Statistiken (hier: Telefonminuten und SMS) geben – und bei "Antippen" die App gleich auf der zugehörigen Detail-Seite öffnen (links).</P>
<P><IMG SRC='screenshots/widget_mi.jpg' ALT='MiniInfo Widget' CLASS='imgright'>Widgets von <SPAN CLASS='qr' STYLE='width:25mm'><IMG CLASS='qr' ALT='QR' SRC='qr/playstore/com.dynotes.miniinfo_Mini-Info.png'>Mini-Info</SPAN><A CLASS='extern'  HREF=''>Mini-Info</A>, die über diverse System-Informationen auf dem Laufenden halten (rechts). Tippt man sie an, wird die App (ganz normal) gestartet.</P>

Relevant CSS:

.imgright { float:right; margin-left:0.5em; }
.imgleft { float:left; margin-right:0.5em; }
span.qr {
  width: 2.5cm;
  font-size: 11px;
  text-align: center;
  /* the following works as long as QRs are not to close together ( -- otherwise they overlap each other */
  /* with Prince 9.x+ @footnotes might be able to float-left ( ) and we might use "float:footnote" for QR */
  float: outside;
  display: table;
  right: 0px;
  top: 0px;
  margin-outside: -2.5cm;
span.qr img { width:1.8cm; margin-right:4mm; }

A second issue with this: If on a right page there's already an image with the ".imgright" class (or correspondingly on a left page ".imgleft"), the "sidebar content" gets hidden below the image instead of being moved outside of the page, watch the green QR in this screenshot:

Relevant HTML:

<P><IMG SRC='screenshots/appaware.jpg' ALT='AppAware' CLASS='imgright'> Freunde sozialer Netzwerke werden <SPAN CLASS='qr' STYLE='width:25mm'><IMG CLASS='qr' ALT='QR' SRC='qr/playstore/com.appaware_AppAware.png'>AppAware</SPAN><A CLASS='extern'  HREF=''>AppAware</A> zu schätzen wissen. Hier bekommt man u.&nbsp;a. die Apps seiner Freunde angezeigt (so diese mitmachen), in der eigenen Umgebung besonders intensiv genutzte Apps, und mehr. Erfahrungen lassen sich mit der Community teilen und diskutieren, es gibt aus der Community berechnete App-Listen, und auch Bookmarks sind möglich. All dies soll bei der Suche der optimalen Apps für den eigenen Bedarf helfen.</P>
<P>Für die Suche nach alternativen Apps sei schließlich noch <SPAN CLASS='qr' STYLE='width:25mm'><IMG CLASS='qr' ALT='QR' SRC='qr/playstore/com.mapsaurus.apps_Mapsaurus.png'>Mapsaurus</SPAN><A CLASS='extern'  HREF=''>Mapsaurus</A> empfohlen. Diese App hat sich auf die Suche nach „ähnlichen Anwendungen“ spezialisiert. Ist man etwa mit einer App nicht so wirklich zufrieden, hilft vielleicht ein Blick auf Alternativen mit Mapsaurus: Die bekannte App aufgesucht, führen vier „Fäden“ zu Apps, die dieser ähneln. Wie ein Spinnennetz erweitert sich diese Ansicht, sobald man auf eine dieser Alternativen tippt – der Screenshot veranschaulicht dies recht gut.</P>

Any hints what could be done from my side -- or is this rather a rendering bug?

I have to add that the first case (gaps) only happens occasionally, say in about 10..20% of the cases, while the second case with the "sidebar hidden below images" is 100% reproducable. I'd attribute the former to a rendering bug, and the latter to imperfect CSS from my side -- as the solution chosen admittedly is a work-around to emulate a sidebar. So I'd be happy about hints to the latter -- and hoping for a solution to the former :)
  1. prince_sidebar_gaps.jpg102.5 kB
    Moved objects sometimes leave gaps
  2. prince_sidebar_hidden.jpg46.1 kB
    sidebar content hidden by image

Edited by Izzy

I will have to take a look at this next week and get back to you, as it's a complex situation. If you do have a sample document you can post that would help us to reproduce the layout and see what we can figure out.
Thanks for your fast response, Mike! Sure I can provide a sample document. The PDF is about 4.5 MB, zipped-up source (including images) will be about 3 MB. I've just attached the latter (after all, it's all free -- licensed under CreativeCommons BY-NC-SA :)), feel free to remove the attachment after downloading in case it's too big. I didn't use any special command line parameters to generate the PDF.
  1. cat.zip3.0 MB
    source HTML, CSS, and images

Edited by Izzy

Thanks, I'll check that out.
Okay, the unexpected line breaks seem to be caused by the span.qr having "display: table". I'm not sure why yet, but removing this is sufficient to stop it happening. This is unrelated to the overlap issue, caused by negative outside margins on the floats.
Thanks, Mike! I took that "display:table" from apgoar's post above -- indeed, it seems not to be needed, and a quick look seems to approve that removing that from the CSS solves the "gaps" issue. As a funny side-effect, the QR codes which were hiding under images ("overlap issue") are now sitting on top of them :)

Can you think of any automated solution to the overlap issue? While I could work-around that using an additional class to move them by "image width plus current negative outside", for each manually, that makes the code less maintainable: As soon as some text is inserted somewhere, it might break something then (and e.g. move one of those floats outside the page).
The table issue turns out to be actually quite simple: because tables are blocks, it breaks the line at that point. If the element needs to be formatted as a table, using "display: inline-table" will work without breaking the line. I was confused because floating an element usually changes its display value, but not in the case of tables. It makes sense now. :)

I'm not sure how to fix the float overlap automatically, unless we make some major changes to the way Prince does float layout. We may need to do this anyway, but it's a big job and will take time.
Thanks again, Mike! I took the "display: table" only from above examples, so table layout is not really needed in my case. But good the culprit is identified: if I should need it, I will have to remember about "inline-table" :)

So for the overlap it seems I will have to manually adjust for now. The idea with the footnote area moved to "outside" (when it becomes available) does not work with me, as the footnotes area will be used for, um, footnotes (not yet enabled in the sample code I sent last time, but built-in afterwards). As adding the footnotes shifted pages, it introduced new strange things in the sidenotes context:

As said above (and included in my sample code), I shift overlapping sidenotes up/down, which seemed to work somehow -- but I already expected a little trouble when adding/removing text. Just not this:


The second QR-Code Div (bottom right of the screenshot) is moved down by 20px, the first (top left) just float:outside with negative shift. What's causing the pagebreak are rather the two graphics in the middle. As the entire paragraph is moved to the next page, I had expected it taking the heading along. It simply looks strange to have the page ending with a headline plus QR :) I've attached you the updated HTML and CSS, in case you need them to reproduce the issue.
  1. catp.zip211.8 kB
    updated source HTML + CSS
  2. prince_sidebar_pagebreak.jpg62.7 kB
    Sidebar Pagebreak Issue
Thanks, but any suggestion about qr code creator?
How about Zxing bar code?
@longwest I simply use a web service for that:<url>&size=200x200&color=<color>&bgcolor=<bgcolor>
Thanks, lzzy
Mike, will there be a separate sidenotes area any time soon? Moving things outside (like my QR codes) is a permanent hazzle, for two reasons:

* on a left page next to a list item, the negative margin has the wrong relation (indent of the LI)
* same with images (relates to their inner borders, or rather to the outer text border)

This means whenever I insert a text block on page 4 (or 5, left/right doesn't matter here), I need to adjust all the following 300 pages to assure no QR code sits on an image or inside a list. I can't fix the latter, but for the former I have to move the images from left to right and vice versa. Not only a lot of work, but I never can make references like "screenshot to the left".

For the lists, even a way to adjust it via css would be appreciated; "@page:left li { margin-outside:…}" doesn't work or I'd simply increase it there… My current CSS is attached to topic 4139 in case you want to check.

Before you ask: No, I cannot use the floating footnotes for this as footnotes are already in use for… well, footnotes …

There will be a separate sidenote area, although I hesitate to say "soon". :D

Is there a reason you can't use negative margin to pull the content to the outside? I'm not quite sure I understand the limitation that makes this impossible; the usual problem is that occasionally two floats with negative margin can overlap, which is another issue on our roadmap to fix.
Well, light at the end of the tunnel (and I sure hope it's not just an oncoming train :)

I currently use negative margins, but that has two major flaws:

* vertical adjustment needs to be done manually
* horizontal position gets messed up, e.g. on a left page next to UL/OL, or negative margin seems "ignored" and the object overlaps with an image (that's most likely what you refer to as being "on the roadmap to fix")

I'd prefer simply to push my "objects" (it's QR-Codes for links in the text) to a side area, where they "stack up" nicely until the page is full – so the only thing I had to care for is not to have too many of them :)
Right I see, it might be possible to fix the horizontal position with some suitably devious CSS selectors but the vertical stacking really needs proper sidenotes to work (and you are already using the footnotes area so that trick is unavailable).

We'll get there in the end! :D
If you had a CSS selector (like "@page:left li sidenote" – which for obvious reasons doesn't work) I'd be very thankful for that! Of course a real side area would be preferred (as it solves both issues), but such a selector would already mean a huge improvement.

And yes, footnotes are already in use by, erm, footnotes (mostly the very same URLs in the clear, for the print and people not using QR codes).
Unfortunately those kinds of CSS selectors can lead to annoying circular dependencies, like pushing something to a right page if it would occur on a left page, which means that the rule no longer applies.

It's possible with JavaScript, but it takes considerable effort.
Thanks again Mike! I just thought I might have missed some simple work-around for at least half of it. Will have to wait for the "real side-notes" then. I'm stuck at Prince 11.4 anyway (see the other issue I've opened a few days ago).
Prince 14 supports "multipass" layout which makes it possible to add quite sophisticated sidenotes to your documents.

Here's a sample document with several types of sidenotes: (1) baseline-aligned sidenotes (2) top-of-page-aligned sidenotes, and (3) sidenotes placed above or below full-width figures. The script tries to detect and avoid overlap in the margin area, and images are (slightly) resized to align with the text. This solution is not fully battle-tested yet, but it shows potential.

To format yourself, run:
prince -j -o hg.pdf

Remember to use Prince 14 for this. The "-j" command-line option is a new shorthand to turn on JavaScript.

Edited by howcome

Thanks howcome – nice, but nt exactly the kind of side-notes we're discussing here. Yours are using a column inside the text-area. The question here is rather about notes pulled "out of the body text" (see 2nd comment, see QR codes in my screenshots). Still, interesting variant ;)
The example provided also pulls notes out of the body text. Here's a revision where I have replaced textual notes with QR images.

The JavaScript in that example can be simplified if you only need one type of sidenote (and not, say, the figure captions).

Edited by howcome

Yes, of course – all a question of how you define "side" ;) And probably your approach could be applied to my use-case as well, in a modified manner. I might give it a try when time permits, thanks!
Here is a script-free alternative:

It uses the @footnotes area for sidenotes. To also support footnotes, it uses page floats. This approach requires one extra HTML element per footnote (for footnote calls) but should otherwise be seamless. It relies on the new "float-policy" property in Prince 14.

Edited by howcome

Prince 14.2 introduced support for "sidenote areas", which allow many commonly seen sidenotes and figures to be achieved with a line or two of CSS. Here's a quick guide: