Broken Captions for Binder–Linked & Embedded Images

I normally insert images manually using markdown notation: caption — but out of curiosity wanted to try to switch to the awesome binder-linked images (Insert ▸ Image Linked to Document). I wanted to attach captions to my binder-linked images, and there are several ways to do this (§21.4.1):

I tried straight quotes and brackets on the same line separated by a space, brackets on a following line and a caption style linked in the compile format and only the latter works — following is the compiled output:

Lorum ipsum…

![][arinokao] [Arinokao Illusion — there are 4 perfect circles in this image. BRACKETS.]  

Lorum ipsum…  

![][arinokao] "Arinokao Illusion — there are 4 perfect circles in this image. STRAIGHT QUOTES."  

Lorum ipsum…  

![][arinokao]
[Arinokao Illusion — there are 4 perfect circles in this image. BRACKETS NEWLINE]  

![Arinokao Illusion — there are 4 perfect circles in this image. Caption Style][arinokao]

Lorum ipsum…  

[arinokao]: arinokao.jpg {width=432 height=432}


Project that generated this markdown output:
Captions.scriv.zip (126 KB)

Note only the last image block (Caption Style) correctly has the caption in the right place. I tried the Default, Basic multimarkdown, and my own Scrivomatic formats without success. I also tried enabling/disabling the “Convert … to Multimarkdown” options in compile just in case they modified this behaviour.

Have I missed something?

Here is what the [BRACKETS] lines look like in the editor:


EDIT: this also affects embedded images.

I ran into this last night as well and was pulling my hair out for a bit. I think there must be a bug with using either of the square brackets.

But the version with straight quotes worked fine in my project – I downloaded your project and saw the same incorrect result. I think the issue there are the two stray spaces after your caption:

I deleted those and then compile gave me the correct result:

[code]# Test #

Lorum ipsum…

![][arinokao] [Arinokao Illusion — there are 4 perfect circles in this image. BRACKETS.]

Lorum ipsum…

![Arinokao Illusion — there are 4 perfect circles in this image. STRAIGHT QUOTES.][arinokao]

Lorum ipsum…

![][arinokao]

[Arinokao Illusion — there are 4 perfect circles in this image. BRACKETS NEWLINE]

![Arinokao Illusion — there are 4 perfect circles in this image. Caption Style][arinokao]

Lorum ipsum…

[arinokao]: arinokao.jpg width=432px height=432px[/code]

So straight quotes work, the “style” method works, but using square brackets does not seem to work (you had stray spaces there too, but deleting them did not help)

Ah, OK, I use Pandoc where I instinctively always add [space][space][return] after every paragraph to guarantee a hard line break… — ideally Scrivener shouldn’t be quite so sensitive to trailing whitespace (particularly in pandoc mode).

I can see your brackets are \escaped in your output, I think that comes from enabling “Convert rich text to multimarkdown”, and I’m also not quite sure why it would do this?

OK, I think this is solved. I removed all my trailing whitespace and made sure “Convert rich text to multimarkdown” was disabled and now the bracket syntax works:

[code]
Lorum ipsum…

![Arinokao Illusion — there are 4 perfect circles in this image. BRACKETS.][arinokao]

Lorum ipsum…

![Arinokao Illusion — there are 4 perfect circles in this image. STRAIGHT QUOTES.][arinokao]

Lorum ipsum…

![Arinokao Illusion — there are 4 perfect circles in this image. BRACKETS NEWLINE][arinokao]

Lorum ipsum…

![Arinokao Illusion — there are 4 perfect circles in this image. Caption Style][arinokao]

Lorum ipsum…[/code]

SO, the summary is Scrivener should not be so sensitive to trailing whitespace AND it should try not to escape the brackets before it tries to parse the potential captions. “Convert tables and lists to markdown” does not cause this problem; and I wonder why it needs to escape the brackets at all?

I think I am very confused by how “Convert rich text to multimarkdown” works. Don’t I need to select that option in order to get all the magic such as bold/italics converted into MD syntax? My hope here is that I could write in rich text, then compile the document out into markdown format. I don’t particularly want to use MD syntax in the document itself (if I was going to do that, I’d probably use a markdown editor that showed syntax highlighting and provided better shortcuts for md syntax).

I also want to write in rich text format so that I have the flexibility to compile into other formats — such as producing a PDF straight from Scrivener with proper formatting.

Anyway, I wasn’t able to get the square bracket method for captions to work — maybe I’ll take a look again tomorrow.

KB: So the questions still remaining here are why “Convert rich text to markdown” is escaping the brackets for captions, and why whitespace is not tolerated at the end of the line for caption conversion?

Brackets are for writing in Markdown, not rich text. So converting to MMD escapes them, given that brackets should be escaped. If you’re writing in rich text, don’t place brackets around the captions unless you want them there in the final output.

Perhaps this could be mentioned in the manual, or indeed the syntax removed as there are two other methods to do this and depends on a compile setting that a user may want (writing in rich text and have captioned figures is not an either/or)…

My original problem was to do with whitespace at the line end breaking the captions (both “” and ), which I think is a bug?

They’re certainly not either/or (I’m not sure why you think they would be considered so?) but writing in MMD or rich text is. Scrivener just provides a convenience for MMD users whereby they can place a caption after an image and place it in square brackets (either on the same line or on the next line) and it will be turned into a captain for that image when exporting to MMD. Users of rich text would have no reason to do that, though. If you’re writing in rich text, you just use a “Caption” style. If you set that as the “Captions style” in “MultiMarkdown Options” (as is done for the “Basic MultiMarkdown Syntax”), then when choosing to convert rich text to MMD, text of the Caption style following an image will be turned into an MMD image caption - no need for square brackets.

No, it’s not a bug - I’m not sure why you think it is? If you’re writing in MMD, you can add a caption after an image by placing it in square brackets following a space directly after the image, or by placing it in square brackets on the next line. It must be the only thing on the line for the latter case and it must be the last thing on the line for the former. If there is any whitespace after the caption, it will not work. This is not a bug, but intended behaviour.

All the best,
Keith

In light of this and the other thread, where we were discussing the RTF->MMD switch’s intentional function, I’ve done a little clarification in the manual. The switch itself now more clearly states that it’s going to primarily be of use to those not using Markdown (or Scrivener’s Markdown features, like bracket captions), and cross-references to the Treat as raw markup option for styles. That checkbox now also uses Markdown protection (with the RTF->MMD setting) as one of its applied examples, along with HTML.

Yes, that is what I meant — the user is not encouraged to mix some MMD syntax with some rich text (the Hybrid approach in §21.4). I suppose my feeling is that apart from enforced escaping, the mix-and-match approach can work well for some users. In Scrivener 2 I wrote with MMD exclusively, then with S3 I’ve switched broadly to styles. But for some features I can still see some users potentially wanting the best of both worlds. You are guiding the user to choose by forcibly escaping potential markup, which perhaps is fair enough for most users. Rather than allow a bit of mix-and-match, your view is you buy a box of (rich or markup) sweets and stick with it :smiley:

EDIT: Yet there are several features, like bibliographic citations ( like [#ref] in MMD and [@ref] in Pandoc), or glossaries (MMD) that a user would have a very good use case to want to use with rich text, and will I think break with your current escaping of brackets… Preserve formatting may work around it, but with several hundred bibliographic references this would get incredibly tiring.

OK, not a bug exactly, lets call it a design specification that can be optimised! :wink: Pandoc syntax specifically enforces block-content breaks using a two-space rule at the end of the paragraph (the paragraph breaking rule applies to all block content):

The rules for figure with caption (implicit figures in syntax speak) states it must sit in its own paragraph, which can be enforced by the two-space rule after the caption:

Scrivener nominally supports Pandoc, and so it seems allowing paragraphs clearly separated using two-spaces would be a compatible parsing rule for Scrivener’s conversion? Very slightly relaxing the line end rule shouldn’t negatively impact the parser for MMD I think…

Thanks Ioa! Clarifying the specific rules that the Hybrid approach you discuss in §21.4 should follow (such as the effects of rich text conversion) is great.

Oh that was part of the revision, no worries. 8)

Look forward to it. Probably something wrong with me, but i quite enjoy reading the Scrivener manual in the evening as a way to unwind!!! :smiley: RTFM? With pleasure!

You’re definitely a bit batty in that case! Many thanks though. :smiley:

Indeed, the idea is that you write in either rich text or MultiMarkdown. I wasn’t aware of any hybrid recommendations in the manual, but I never planned for any hybrid uses in Scrivener via the code, and that is certainly not part of my plan.

I don’t see a reason to relax the caption rules - it will work fine with Pandoc if you don’t add the extra spaces, which is the Scrivener rule.

OK, this reinforces to me that using semantic styles (strong / emphasis vs. bold / italic etc.) rather than rich text is a robust option for more technical users (they are still hybrid, but the style mechanism jumps over the limitation of rich text translation). I will do a final pitch that for a user who wanted to use rich text in general but still generate a bibliography, or include maths, or generate a glossary, then this simple option would solve the problem:
Screen Shot 2017-12-08 at 14.24.45_SMALL.png
I think you may still disagree, but worth a try…

No spaces for captions: understood! 8)

EDIT: And just to be fair to the manual — as I infer above the hybrid approach can done by using styles, so with a bit more clarity in what the limitations of mixing rich text and markdown are (which Ioa has done), the hybrid is still a very scrivener-like workflow… :mrgreen:

I would argue that one can already fine-tune the behaviour of this mechanism with the “Treat as raw markup” style option. If you really want the compiler to treat your document as an RTF source file—but only here and there occasionally use a little markup, you can.

And it’s worth noting that you can throw such a style around Scrivener’s in-house caption syntax and have it processed into an MMD caption without the brackets being escaped.

Ultimately it is probably better to use a caption style though, since the purpose of this checkbox is for those that want both Scrivener’s .docx type stuff and Pandoc’s stuff or whatever—and with the former you’d have very little use for this:

I completely agree, for my personal use I only use semantic styles (and markup as I only convert lists and tables).

For a more casual user who wants minimum fuss they will use rich text (Scrivener’s default), but what happens if they happen to be an academic and want to create a bibliography — they either cannot convert their rich text or have to use character styles or preserve formatting blocks for every citation which is quite fussy. This problem will affect users of MMD,Pandoc and Endnote as they all use brackets for citations… Screen Shot 2017-12-08 at 22.32.45_SML.png. Having an option to cater to that use case (and other features like glossaries) makes some sense to me.

Well that’s not a bad point—though I tend to see curly brackets being used more for bibliography placeholders than square brackets, I think I have seen examples of both in the past.

The problem as I see it, and you’d know more about this than I would, is that Pandoc makes heavier use of both styles of braces in the text, does it not? Would there be cases where a bibliographic placeholder could end up being accidentally processed as a CSS class, identified or something?

But Scrivener escapes everything, both square and curly brackets, so no type of citation will survive the “convert rich text” onslaught, nor will any maths or other features that MMD / Pandoc supports that RTF doesn’t.

Pandoc has pretty specific rules for brackets, for example { } for attributes must come after specific markup without intervening whitespace or it will not be recognised. So I really think the chance of a rogue punctuation causing unexpected conversion is limited (being plain text the design takes into account generalisation, and features can take ages to be added to Pandoc while all the side effects are discussed).

So, for Scrivener with my settings tweak you could set the default to escape, which keep’s the enforced removal of possible markup, but lets users who want to be able to bold text and cite an author do so (again I am not the target audience as I use styles).