[NTG-context] placement of marginals at \placesidebyside

[NTG-context] placement of marginals at \placesidebyside

[Henning Hraban Ramm]

Hi,

if I call a marginal before a \placesidebyside (don’t know how to call 
that more generally), it gets placed only at the bottom, and sometimes 
on the next page (couldn’t reproduce that in the MWE).

If I use the voffset option, I can move it up, but only manually, since 
I don’t know the height of the following construct – in my book, that’s 
a code example beside the result. And voffset doesn’t help if the 
marginal moved to the next page.

Do you have a solution?


"""
\starttext

\ininner{MARG}
\input{ward}

\dorecurse{7}{
%\ininner[voffset=-3cm]{MARG}
\ininner{MARG}
\placesidebyside
{\blackrule[width=3cm,height=3cm,color=orange]}
{\blackrule[width=3cm,height=2cm]}

\input{ward}\par
}

\stoptext
"""
___________________________________________________________________________________
If your question is of interest to others as well, please add an entry to the Wiki!

maillist : ntg-context@ntg.nl / https://mailman.ntg.nl/mailman3/lists/ntg-context.ntg.nl
webpage  : https://www.pragma-ade.nl / https://context.aanhet.net (mirror)
archive  : https://github.com/contextgarden/context
wiki     : https://wiki.contextgarden.net
___________________________________________________________________________________

[NTG-context] Re: placement of marginals at \placesidebyside

[Jean-Pierre Delange via ntg-context]

[-- Attachment #1.1: Type: text/plain, Size: 2665 bytes --]

Hraban,

 From what I understand, the marginal is an insert attached to a line, 
and |\placesidebyside| is a vertical block; without a reliable line 
anchor, ConTeXt pushes it away. A solution? Either force a line anchor 
(|\dontleavehmode ... \par|), or (better) encapsulate |\placesidebyside| 
in a box and apply a |voffset| calculated on |\ht| of the box (so the 
marginal follows the block, even if it jumps from page to page). I don't 
know if the following MWE is the most elegant or effective (or robust) 
approach, but it seems to work (at least for me, the test is functional, 
even though I haven't tested it beyond two pages). I don't know if 
that's really the goal you're looking for either...You'll tell me !

Best//JP

\starttext


\def\SideBySideWithInnerMarg#1#2#3{%

\begingroup

\setbox0\vbox{%

\placesidebyside{#2}{#3}%

}%

% On place le marginal "après", mais on le remonte d'une hauteur de box

\ininner[voffset=-\ht0]{#1}%

\box0

\endgroup

}


\input{ward}


\dorecurse{7}{%

\SideBySideWithInnerMarg

{MARG}

{\blackrule[width=3cm,height=3cm,color=orange]}

{\blackrule[width=3cm,height=2cm]}

\par

\input{ward}\par

}


\stoptext





Le 18/02/2026 à 18:33, Henning Hraban Ramm a écrit :
> Hi,
>
> if I call a marginal before a \placesidebyside (don’t know how to call 
> that more generally), it gets placed only at the bottom, and sometimes 
> on the next page (couldn’t reproduce that in the MWE).
>
> If I use the voffset option, I can move it up, but only manually, 
> since I don’t know the height of the following construct – in my book, 
> that’s a code example beside the result. And voffset doesn’t help if 
> the marginal moved to the next page.
>
> Do you have a solution?
>
>
> """
> \starttext
>
> \ininner{MARG}
> \input{ward}
>
> \dorecurse{7}{
> %\ininner[voffset=-3cm]{MARG}
> \ininner{MARG}
> \placesidebyside
> {\blackrule[width=3cm,height=3cm,color=orange]}
> {\blackrule[width=3cm,height=2cm]}
>
> \input{ward}\par
> }
>
> \stoptext
> """
> ___________________________________________________________________________________ 
>
> If your question is of interest to others as well, please add an entry 
> to the Wiki!
>
> maillist : ntg-context@ntg.nl / 
> https://mailman.ntg.nl/mailman3/lists/ntg-context.ntg.nl
> webpage  : https://www.pragma-ade.nl / https://context.aanhet.net 
> (mirror)
> archive  : https://github.com/contextgarden/context
> wiki     : https://wiki.contextgarden.net
> ___________________________________________________________________________________ 
>

[-- Attachment #1.2: Type: text/html, Size: 7616 bytes --]

[-- Attachment #2: Type: text/plain, Size: 511 bytes --]

___________________________________________________________________________________
If your question is of interest to others as well, please add an entry to the Wiki!

maillist : ntg-context@ntg.nl / https://mailman.ntg.nl/mailman3/lists/ntg-context.ntg.nl
webpage  : https://www.pragma-ade.nl / https://context.aanhet.net (mirror)
archive  : https://github.com/contextgarden/context
wiki     : https://wiki.contextgarden.net
___________________________________________________________________________________

[NTG-context] Re: placement of marginals at \placesidebyside

[Jean-Pierre Delange via ntg-context]

[-- Attachment #1.1: Type: text/plain, Size: 7265 bytes --]

Hi,

I'll answer to my own contribution! After isolating the cause of the 
problem (making a line coexist with an insert), we can see that the 
solution does not completely solve the problem, since we can see in the 
PDF output of the MWE that there is something wrong with the transition 
between page 1 and page 2.

After applying the macro that measures the height of the 
|\placesidebyside| material and places the marginal with 
|voffset=-\ht<box>|, most of the original problem is solved: the 
marginal is correctly aligned with the side-by-side block and no longer 
drifts to the bottom of the page. However, there is still a residual 
issue at a page boundary. In the PDF output, one can observe that at the 
transition from page 1 to page 2, the side-by-side material (the 
orange/black rules) is placed at the bottom of page 1, while the 
marginal (|MARG|) is deferred and appears at the top of page 2. This 
happens only at the page break and breaks the visual association once.

This behavior is still consistent with ConTeXt’s page-builder logic. In 
the current macro, the order is essentially:

 1.

    register the marginal as an insert,

 2.

    then add the measured box to the vertical list.

In my opinion if the page is nearly full at that point and the box does 
not fit, the page builder decides to break /before/ the box. The box is 
moved to the next page, but the insert has already been registered for 
the current page and is therefore separated.

In other words: measuring the box is not sufficient if the insert is 
emitted before the page decision is final.

I may be mistaken here, but after looking at the remaining page-break 
behavior, it seems that the core issue might not be the measurement 
itself, but /when/ the marginal is emitted with respect to the 
page-builder’s decision. My current hypothesis is that, as long as the 
marginal is registered as an insert *before* the page break is 
finalized, it can still be separated from the following material — even 
if its vertical position is computed correctly. This would explain why 
the alignment works in most cases, yet still fails exactly at a page 
boundary. If that reading is correct, then the only way to guarantee 
that the marginal and the side-by-side material are never separated 
would be to make them belong to the same placement unit from the page 
builder’s point of view.

One possible approach would be to construct a single |\vbox| that 
already contains both the marginal and the |\placesidebyside| material, 
and then let ConTeXt place that box as a whole. For example:

|\def\SideBySideWithInnerMarg#1#2#3{%\begingroup\setbox0\vbox{%\ininner{#1}%\placesidebyside{#2}{#3}%}%\box0 
\endgroup} |

In this setup (assuming my understanding is correct):

  *

    the marginal is emitted /inside/ the box,

  *

    the page builder no longer has the option to place the insert and
    the block independently,

  *

    either the whole unit fits on the current page, or it is moved
    entirely to the next page.

Regarding positioning and alignment, once the marginal is inside the 
|\vbox|, it seems that manual |voffset| on the insert itself should no 
longer be the right tool. Instead, alignment would need to be handled by:

  *

    adjusting the internal layout of the box (e.g. struts or vertical
    spacing),

  *

    or, if necessary, by measuring and shifting the /box as a whole/.

If this reasoning holds, the important point is that any recalculation 
now applies to the |\vbox|, not to an insert whose page placement has 
already been decided. I would be very interested to know whether this 
matches how others understand the page-builder behavior, or if I am 
missing something obvious here.

Best//JP


Le 18/02/2026 à 21:45, Jean-Pierre Delange via ntg-context a écrit :
>
> Hraban,
>
> From what I understand, the marginal is an insert attached to a line, 
> and |\placesidebyside| is a vertical block; without a reliable line 
> anchor, ConTeXt pushes it away. A solution? Either force a line anchor 
> (|\dontleavehmode ... \par|), or (better) encapsulate 
> |\placesidebyside| in a box and apply a |voffset| calculated on |\ht| 
> of the box (so the marginal follows the block, even if it jumps from 
> page to page). I don't know if the following MWE is the most elegant 
> or effective (or robust) approach, but it seems to work (at least for 
> me, the test is functional, even though I haven't tested it beyond two 
> pages). I don't know if that's really the goal you're looking for 
> either...You'll tell me !
>
> Best//JP
>
> \starttext
>
>
> \def\SideBySideWithInnerMarg#1#2#3{%
>
> \begingroup
>
> \setbox0\vbox{%
>
> \placesidebyside{#2}{#3}%
>
> }%
>
> % On place le marginal "après", mais on le remonte d'une hauteur de box
>
> \ininner[voffset=-\ht0]{#1}%
>
> \box0
>
> \endgroup
>
> }
>
>
> \input{ward}
>
>
> \dorecurse{7}{%
>
> \SideBySideWithInnerMarg
>
> {MARG}
>
> {\blackrule[width=3cm,height=3cm,color=orange]}
>
> {\blackrule[width=3cm,height=2cm]}
>
> \par
>
> \input{ward}\par
>
> }
>
>
> \stoptext
>
>
>
>
>
> Le 18/02/2026 à 18:33, Henning Hraban Ramm a écrit :
>> Hi,
>>
>> if I call a marginal before a \placesidebyside (don’t know how to 
>> call that more generally), it gets placed only at the bottom, and 
>> sometimes on the next page (couldn’t reproduce that in the MWE).
>>
>> If I use the voffset option, I can move it up, but only manually, 
>> since I don’t know the height of the following construct – in my 
>> book, that’s a code example beside the result. And voffset doesn’t 
>> help if the marginal moved to the next page.
>>
>> Do you have a solution?
>>
>>
>> """
>> \starttext
>>
>> \ininner{MARG}
>> \input{ward}
>>
>> \dorecurse{7}{
>> %\ininner[voffset=-3cm]{MARG}
>> \ininner{MARG}
>> \placesidebyside
>> {\blackrule[width=3cm,height=3cm,color=orange]}
>> {\blackrule[width=3cm,height=2cm]}
>>
>> \input{ward}\par
>> }
>>
>> \stoptext
>> """
>> ___________________________________________________________________________________ 
>>
>> If your question is of interest to others as well, please add an 
>> entry to the Wiki!
>>
>> maillist : ntg-context@ntg.nl / 
>> https://mailman.ntg.nl/mailman3/lists/ntg-context.ntg.nl
>> webpage  : https://www.pragma-ade.nl / https://context.aanhet.net 
>> (mirror)
>> archive  : https://github.com/contextgarden/context
>> wiki     : https://wiki.contextgarden.net
>> ___________________________________________________________________________________ 
>>
>
> ___________________________________________________________________________________
> If your question is of interest to others as well, please add an entry to the Wiki!
>
> maillist :ntg-context@ntg.nl /https://mailman.ntg.nl/mailman3/lists/ntg-context.ntg.nl
> webpage  :https://www.pragma-ade.nl /https://context.aanhet.net (mirror)
> archive  :https://github.com/contextgarden/context
> wiki     :https://wiki.contextgarden.net
> ___________________________________________________________________________________

[-- Attachment #1.2: Type: text/html, Size: 17511 bytes --]

[-- Attachment #2: Type: text/plain, Size: 511 bytes --]

___________________________________________________________________________________
If your question is of interest to others as well, please add an entry to the Wiki!

maillist : ntg-context@ntg.nl / https://mailman.ntg.nl/mailman3/lists/ntg-context.ntg.nl
webpage  : https://www.pragma-ade.nl / https://context.aanhet.net (mirror)
archive  : https://github.com/contextgarden/context
wiki     : https://wiki.contextgarden.net
___________________________________________________________________________________

[NTG-context] Re: placement of marginals at \placesidebyside

[Henning Hraban Ramm]

Salut Jean-Pierre,

thank you for your in-depth analysis!

I’m a bit overwhelmed to integrate Pablo’s last-second corrections into 
my book which is already overdue and must get completed tonight.

I could use the idea from your first mail, my real code looks now like this:

"""
\definebuffer[CodeExampleS]

\define\stopCodeExampleS{%
\begingroup
\setbox0\vbox{%
   \placesidebyside%
   {\NarrowFramed{%
     \typeCodeExampleS[option=tex,lines=yes,numbering=line]}}%
   {\CodeExampleNarrowFramed{\start\getCodeExampleS\stop}}%
}%
\starttextdisplay
\doifnotmode{print}{\ininner[voffset=-\ht0,]
   {\comment[space=yes,buffer=\thedefinedbuffer{CodeExampleS}]{}}}%
\box0
\stoptextdisplay
\endgroup
}
"""

That works at least better than before.
Yes, it’s convoluted and not a complete MWE, but you get the idea.

I could solve most page breaking issues with inserting empty paragraphs 
and manual page breaks.

Hraban
___________________________________________________________________________________
If your question is of interest to others as well, please add an entry to the Wiki!

maillist : ntg-context@ntg.nl / https://mailman.ntg.nl/mailman3/lists/ntg-context.ntg.nl
webpage  : https://www.pragma-ade.nl / https://context.aanhet.net (mirror)
archive  : https://github.com/contextgarden/context
wiki     : https://wiki.contextgarden.net
___________________________________________________________________________________

[NTG-context] Re: placement of marginals at \placesidebyside

[Jean-Pierre Delange via ntg-context]

[-- Attachment #1.1: Type: text/plain, Size: 2418 bytes --]

Hi Hraban,

yes, this makes perfect sense, and it’s very close to the first idea we 
discussed. Measuring the |\placesidebyside| material in a box and 
compensating the marginal with |voffset=-\ht0| already solves the main 
anchoring problem, and your use of |\starttextdisplay| definitely helps 
stabilizing the vertical placement. Under time pressure, manually 
helping page breaks is a perfectly reasonable trade-off. The fully 
“atomic” solution (insert inside the same box) would require a bit more 
restructuring, and that’s not something you want to risk at the very 
end. From a conceptual point of view, your current approach is sound, 
and much better than fighting the page builder blindly.

Good luck with the final stretch!

Best//JP

Le 19/02/2026 à 22:00, Henning Hraban Ramm a écrit :
> Salut Jean-Pierre,
>
> thank you for your in-depth analysis!
>
> I’m a bit overwhelmed to integrate Pablo’s last-second corrections 
> into my book which is already overdue and must get completed tonight.
>
> I could use the idea from your first mail, my real code looks now like 
> this:
>
> """
> \definebuffer[CodeExampleS]
>
> \define\stopCodeExampleS{%
> \begingroup
> \setbox0\vbox{%
>   \placesidebyside%
>   {\NarrowFramed{%
>     \typeCodeExampleS[option=tex,lines=yes,numbering=line]}}%
>   {\CodeExampleNarrowFramed{\start\getCodeExampleS\stop}}%
> }%
> \starttextdisplay
> \doifnotmode{print}{\ininner[voffset=-\ht0,]
>   {\comment[space=yes,buffer=\thedefinedbuffer{CodeExampleS}]{}}}%
> \box0
> \stoptextdisplay
> \endgroup
> }
> """
>
> That works at least better than before.
> Yes, it’s convoluted and not a complete MWE, but you get the idea.
>
> I could solve most page breaking issues with inserting empty 
> paragraphs and manual page breaks.
>
> Hraban
> ___________________________________________________________________________________ 
>
> If your question is of interest to others as well, please add an entry 
> to the Wiki!
>
> maillist : ntg-context@ntg.nl / 
> https://mailman.ntg.nl/mailman3/lists/ntg-context.ntg.nl
> webpage  : https://www.pragma-ade.nl / https://context.aanhet.net 
> (mirror)
> archive  : https://github.com/contextgarden/context
> wiki     : https://wiki.contextgarden.net
> ___________________________________________________________________________________ 
>

[-- Attachment #1.2: Type: text/html, Size: 4185 bytes --]

[-- Attachment #2: Type: text/plain, Size: 511 bytes --]

___________________________________________________________________________________
If your question is of interest to others as well, please add an entry to the Wiki!

maillist : ntg-context@ntg.nl / https://mailman.ntg.nl/mailman3/lists/ntg-context.ntg.nl
webpage  : https://www.pragma-ade.nl / https://context.aanhet.net (mirror)
archive  : https://github.com/contextgarden/context
wiki     : https://wiki.contextgarden.net
___________________________________________________________________________________