Better approach to preventing floating tables in ConTeXt output

Better approach to preventing floating tables in ConTeXt output

[T. Kurt Bond]

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

The ConTexT writer produces output that lets tables float to a following
location (often the next page)  while text that follows the floating object
in the source document appears before it.  This behaviour is convenient if
the floating object has a caption that can be referred to, since it allows
a page to fill up with text, but is very inconvenient when it does not have
a caption and the author expected the table would appear directly after the
text that preceded it, because the table then appears out of order with the
text.

A better approach would be to allow the author of the document to specify
whether tables are allowed to float.

My earlier try
<https://groups.google.com/g/pandoc-discuss/c/SKWzgqyLtSc/m/2-mRUXfZCwAJ>
at this required adding a command line option --no-table-float to pandoc,
and was not entirely correct, since it caused tables with captions to be
numbered.

After looking at the problem more, and a discussion
<https://www.mail-archive.com/ntg-context-wvrSQK3plZs@public.gmane.org/msg99211.html> on the
ConTeXt mailing list, I have come up with a better solution that doesn't
require adding a command line option to pandoc.  It requires changing the
default ConTeXt template and changing one line of ConTeXt.hs.

Currently, default.context contains the following line:

\setupfloat[table][default={here,nonumber}]


This attempts to specify that figures and tables should *preferably* appear
in the output at the location in the document where they appeared in the
input, and that figures and tables should not be numbered.  However, as the
discussion on the ConTeXt mailing list revealed, the default set here only
applies if no arguments are supplied for the location key in \placetable.
My earlier attempt first involved changing the location key for captionless
tables to "location={force,none}" and adding a "location={force}" for
tables with captions when the --no-table-float option I added was
specified.  However, since the location key was specified, the default set
for it in the \setupfloat[table][default={here,nonumber}] statement did
*not* apply, so tables with captions came out numbered, that is, the
caption prefixed with "Table" and a number.  (I'm not sure why ConTeXt uses
the location key to specify that a table is not to have a table number.)
Looking for why that happened is what led to a better approach to
preventing floating tables.

The discussion on the ConTeXt mailing list suggested using
\setupcaption[table][number=no] to turn off captioning for all tables
instead of specifying a default value for the location key with
\setupfloat[table][default={here,nonumber}].

So, my suggestion is to

   1. Turn off table numbering in default.context by specifying
   \setupcaption[table][number=no] instead of adding the nonumber keyword
   to the location key in the \setupfloat[table] command.
   2. Once that is done it  "location=none" should *not* be added to the
   \startplacetable command, since captions have already been turned off,
   so remove that from ConTeXt.hs.
   3. Change the line in default.context with

\setupfloat[table][default={here,nonumber}]

to

\setupfloat[table][default={$if(location)$$location$$else$here$endif$}]

to allow the user to specify "-V location=force" to pandoc, similar to
other items in default.context.  This also lets the user specify other
options for location if those are useful.


There is also a line in default.context

\setupfloat[figure][default={here,nonumber}]

that does the same thing for figures.  I *think* a similar change should be
made for figures as well:



   1. Turn off figure numbering in default.context by specifying
   \setupcaption[figure][number=no] instead of adding the nonumber keyword
   to the location key in the \setupfloat[figure] command.
   2. Change the line in default.context with

\setupfloat[table][default={here,nonumber}]

to

\setupfloat[table][default={$if(location)$$location$$else$here$endif$}]


However, during my testing I was unable to get figures to float.  I have
not figured out why.  The ConTeXt.hs code uses \placefigure instead of
\startplacefigure ... \stopplacefigure - perhaps that makes a difference,
although I see from contextgarden.net
<https://wiki.contextgarden.net/Command/_placefloat> that \placefigure
has much the same options as \startplacefigure and \startplacetable.

In any case, I've attached a patch that implements this.  I added
$if(number-figure)$ and $if(number-table)$ sections to default.context to
let the user choose whether figures and tables are numbered, defaulting to
not numbering them,  like the current default.context.
-- 
T. Kurt Bond, tkurtbond-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org, https://tkurtbond.github.io

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/CAN1EhV9nMZywVEqzgNcWJXWtaktHJLM1YDuRqgcs5vPzBDhQjA%40mail.gmail.com.

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

[-- Attachment #2: better-nofloat-tables-and-figures.patch --]
[-- Type: application/octet-stream, Size: 1505 bytes --]

diff --git a/data/templates/default.context b/data/templates/default.context
index df39130b2..660801661 100644
--- a/data/templates/default.context
+++ b/data/templates/default.context
@@ -101,8 +101,20 @@ $endif$
 \defineitemgroup[enumerate]
 \setupenumerate[each][fit][itemalign=left,distance=.5em,style={\feature[+][default:tnum]}]
 
-\setupfloat[figure][default={here,nonumber}]
-\setupfloat[table][default={here,nonumber}]
+% Turn off numbering of captions by default, but let the user choose.
+$if(number-figures)$
+$else$
+\setupcaption[figure][number=no]
+$endif$
+$if(number-tables)$
+$else$
+\setupcaption[table][number=no]
+$endif$
+
+% Allow the user to set location to force to prevent figures and
+% tables from floating.
+\setupfloat[figure][default={$if(location)$$location$$else$here$endif$}]
+\setupfloat[table][default={$if(location)$$location$$else$here$endif$}]
 
 \setupxtable[frame=off]
 \setupxtable[head][topframe=on,bottomframe=on]
diff --git a/src/Text/Pandoc/Writers/ConTeXt.hs b/src/Text/Pandoc/Writers/ConTeXt.hs
index 3cafcefba..49c0ac3aa 100644
--- a/src/Text/Pandoc/Writers/ConTeXt.hs
+++ b/src/Text/Pandoc/Writers/ConTeXt.hs
@@ -267,7 +267,7 @@ blockToConTeXt (Table _ blkCapt specs thead tbody tfoot) = do
     body <- tableToConTeXt tabl headers rows'
     return $ "\\startplacetable" <> brackets (
       if null caption
-        then "location=none"
+        then ""
         else "title=" <> braces captionText
       ) $$ body $$ "\\stopplacetable" <> blankline
 

AW: Better approach to preventing floating tables in ConTeXt output

[denis.maier-NSENcxR/0n0]

[-- Attachment #1: Type: text/plain, Size: 6616 bytes --]

Thanks for all your work on this. You’ve obviously put a lot of thought into this already.

I’m wondering whether this could be a per-table option, rather than per-document? What do you think? Ideally, we could come up with a solution that could work across target formats. Perhaps similar to unnumbered headings:

```
# My numbered heading
# My unnumbered heading {-}
# My second unnumbered heading {.unnumbered}
```

WDYT ?

All the best,
Denis

Von: pandoc-discuss-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org <pandoc-discuss-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org> Im Auftrag von T. Kurt Bond
Gesendet: Montag, 19. Juli 2021 19:07
An: pandoc-discuss-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
Betreff: Better approach to preventing floating tables in ConTeXt output

The ConTexT writer produces output that lets tables float to a following location (often the next page)  while text that follows the floating object in the source document appears before it.  This behaviour is convenient if the floating object has a caption that can be referred to, since it allows a page to fill up with text, but is very inconvenient when it does not have a caption and the author expected the table would appear directly after the text that preceded it, because the table then appears out of order with the text.

A better approach would be to allow the author of the document to specify whether tables are allowed to float.

My earlier try<https://groups.google.com/g/pandoc-discuss/c/SKWzgqyLtSc/m/2-mRUXfZCwAJ> at this required adding a command line option --no-table-float to pandoc, and was not entirely correct, since it caused tables with captions to be numbered.

After looking at the problem more, and a discussion<https://www.mail-archive.com/ntg-context-wvrSQK3plZs@public.gmane.org/msg99211.html> on the ConTeXt mailing list, I have come up with a better solution that doesn't require adding a command line option to pandoc.  It requires changing the default ConTeXt template and changing one line of ConTeXt.hs.

Currently, default.context contains the following line:

\setupfloat[table][default={here,nonumber}]

This attempts to specify that figures and tables should preferably appear in the output at the location in the document where they appeared in the input, and that figures and tables should not be numbered.  However, as the discussion on the ConTeXt mailing list revealed, the default set here only applies if no arguments are supplied for the location key in \placetable.  My earlier attempt first involved changing the location key for captionless tables to "location={force,none}" and adding a "location={force}" for tables with captions when the --no-table-float option I added was specified.  However, since the location key was specified, the default set for it in the \setupfloat[table][default={here,nonumber}] statement did not apply, so tables with captions came out numbered, that is, the caption prefixed with "Table" and a number.  (I'm not sure why ConTeXt uses the location key to specify that a table is not to have a table number.)  Looking for why that happened is what led to a better approach to preventing floating tables.

The discussion on the ConTeXt mailing list suggested using \setupcaption[table][number=no] to turn off captioning for all tables instead of specifying a default value for the location key with \setupfloat[table][default={here,nonumber}].

So, my suggestion is to

  1.  Turn off table numbering in default.context by specifying  \setupcaption[table][number=no] instead of adding the nonumber keyword to the location key in the \setupfloat[table] command.
  2.  Once that is done it  "location=none" should not be added to the \startplacetable command, since captions have already been turned off, so remove that from ConTeXt.hs.
  3.  Change the line in default.context with
\setupfloat[table][default={here,nonumber}]
to
\setupfloat[table][default={$if(location)$$location$$else$here$endif$}]

to allow the user to specify "-V location=force" to pandoc, similar to other items in default.context.  This also lets the user specify other options for location if those are useful.

There is also a line in default.context
\setupfloat[figure][default={here,nonumber}]
that does the same thing for figures.  I think a similar change should be made for figures as well:

  1.  Turn off figure numbering in default.context by specifying  \setupcaption[figure][number=no] instead of adding the nonumber keyword to the location key in the \setupfloat[figure] command.
  2.  Change the line in default.context with
\setupfloat[table][default={here,nonumber}]
to
\setupfloat[table][default={$if(location)$$location$$else$here$endif$}]

However, during my testing I was unable to get figures to float.  I have not figured out why.  The ConTeXt.hs code uses \placefigure instead of \startplacefigure ... \stopplacefigure - perhaps that makes a difference, although I see from contextgarden.net<https://wiki.contextgarden.net/Command/_placefloat> that \placefigure has much the same options as \startplacefigure and \startplacetable.

In any case, I've attached a patch that implements this.  I added $if(number-figure)$ and $if(number-table)$ sections to default.context to let the user choose whether figures and tables are numbered, defaulting to not numbering them,  like the current default.context.
--
T. Kurt Bond, tkurtbond-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org<mailto:tkurtbond-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>, https://tkurtbond.github.io
--
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org<mailto:pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org>.
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/CAN1EhV9nMZywVEqzgNcWJXWtaktHJLM1YDuRqgcs5vPzBDhQjA%40mail.gmail.com<https://groups.google.com/d/msgid/pandoc-discuss/CAN1EhV9nMZywVEqzgNcWJXWtaktHJLM1YDuRqgcs5vPzBDhQjA%40mail.gmail.com?utm_medium=email&utm_source=footer>.

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/e007dc3411d94d36933c074a6e491544%40unibe.ch.

[-- Attachment #2: Type: text/html, Size: 18815 bytes --]

Re: Better approach to preventing floating tables in ConTeXt output

[John MacFarlane]

This is all very helpful.

Preliminary observation: our current default output for context
disables table numbers: we just get the caption, not "Table 1:
The caption."

But in LaTeX and (now) Word output, we do get the table numbers
and the (localized) word "Table."

Shouldn't context output be brought into line with these others?

Another idea:  would it make sense to make location default to
"force" when a table has no caption (since then floating will
be confusing?)

Re: AW: Better approach to preventing floating tables in ConTeXt output

[T. Kurt Bond]

On Mon, 19 Jul 2021 16:21:21 -0400,
<denis.maier-NSENcxR/0n0@public.gmane.org> wrote:

        I’m wondering whether this could be a per-table option, rather than
        per-document? What do you think?  Ideally, we could come up with a
        solution that could work across target formats. Perhaps similar to
        unnumbered headings:
        ...
        # My numbered heading
        # My unnumbered heading {-}
        # My second unnumbered heading {.unnumbered}
        ...
        WDYT ?

I think that being able to specify whether individual tables float
would a much more extensive change.  It certainly would be nice to be
able to do that, though.

And remember, the ideal solution would allow this to work for other
readers as well.  I mostly use reStructuredText with pandoc, for
instance.

Hmm.  Ok, in reStructuredText, the table directive takes a :class:
option, and if I have a table like this:

========== Example Starts Here ================================================
.. table::
   :class: float

   ==== ====           
   R1C1 R1C2
   R2C1 R2C2
   ==== ====           
========== Example Ends Here===================================================

then the docutils implementation adds "float" to the class attribute
of the table it generates.

Right now pandoc appears to ignore the :class: option to the table
directive.  If it added that to pandoc's internal representation, then
any of the backends that can do floating tables could look there and do
something different for each table.

I don't see an easy way to specify that right off in markdown, though.
I guess that putting it in a div with the right attribute, which is
the way I'd do it if it was something I could do with a lua filter,
would not be as easy to work with in the pandoc writers.  (My
understanding with the pandoc source code is not great enough to say
this with any certainty, though.  I'm working on it.)

Does anybody else have any ideas?

-- 
T. Kurt Bond, tkurtbond-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org, tkurtbond.github.io and tkb.tx0.org

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/m2zgugpxa6.wl-tkurtbond%40gmail.com.

Re: Better approach to preventing floating tables in ConTeXt output

[T. Kurt Bond]

On Tue, 20 Jul 2021 12:14:01 -0400,
John MacFarlane <jgm-TVLZxgkOlNX2fBVCVOL8/A@public.gmane.org> wrote:
> Preliminary observation: our current default output for context
> disables table numbers: we just get the caption, not "Table 1:
> The caption."
> 
> But in LaTeX and (now) Word output, we do get the table numbers
> and the (localized) word "Table."
> 
> Shouldn't context output be brought into line with these others?

Probably.  In that case, using something like:

========== Example Starts Here ================================================
$if(no-number-figures)$
\setupcaption[figure][number=no]
$endif$
$if(no-number-tables)$
\setupcaption[table][number=no]
$endif$
========== Example Ends Here ==================================================

in default.context would default to numbering tables but would still
allow the user to turn of numbering if they wanted.

> Another idea:  would it make sense to make location default to
> "force" when a table has no caption (since then floating will
> be confusing?)

That... would probably work well as a default.

-- 
T. Kurt Bond, tkurtbond-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org, tkurtbond.github.io and tkb.tx0.org

Re: Better approach to preventing floating tables in ConTeXt output

[T. Kurt Bond]

On Tue, 20 Jul 2021 12:14:01 -0400,
John MacFarlane <jgm-TVLZxgkOlNX2fBVCVOL8/A@public.gmane.org> wrote:
> This is all very helpful.
> 
> Preliminary observation: our current default output for context
> disables table numbers: we just get the caption, not "Table 1:
> The caption."
> 
> But in LaTeX and (now) Word output, we do get the table numbers
> and the (localized) word "Table."
> 
> Shouldn't context output be brought into line with these others?

Yes, it probably should.

Using something (not tested) like

========== Example ============================================================
% Turn on numbering of captions by default, but let the user choose.
\setupcaption[figure][number=$if(number-figures)$$number-figures$$else$yes$endif$]
\setupcaption[table][number=$if(number-tables)$$number-tables$$else$yes$endif$]
========== End of Example =====================================================

in default.context would still let the user choose.

> Another idea:  would it make sense to make location default to
> "force" when a table has no caption (since then floating will
> be confusing?)

That... sounds like it would work well.


-- 
T. Kurt Bond, tkurtbond-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org, tkurtbond.github.io and tkb.tx0.org