I normally insert images manually using markdown notation: ![caption](binder_link) — 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):

When images fall upon their own line, you can supply a caption to them using one of the following techniques:— Place the caption within straight (not typographic) double-quotes, or in matched square brackets, on the same line after the image, separating the image from the caption text with a space.— Alternatively, place the square bracketed caption on the line directly following or preceding the graphic.— Use a designed caption style on the line directly preceding or following the image. Refer to MultiMarkdown and Pandoc Options (section 24.14) for further information on mapping styles to functions.

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:

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.

![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…

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.

KB wrote: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?

nontroppo wrote: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)...

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.

nontroppo wrote:My original problem was to do with whitespace at the line end breaking the captions (both "" and []), which I think is a bug?

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.

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.

.:.Ioa Petra'ka“Whole sight, or all the rest is desolation.” —John Fowles

KB wrote: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*.

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

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.

KB wrote:No, it's not a bug - I'm not sure why you think it is?

OK, not a bug exactly, lets call it a design specification that can be optimised! 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):

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...

AmberV wrote: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.

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.

Last edited by nontroppo on Fri Dec 08, 2017 6:22 am, edited 2 times in total.

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.