Broken Captions for Binder–Linked & Embedded Images

User avatar
nontroppo
Posts: 748
Joined: Mon Mar 05, 2007 5:22 pm
Platform: Mac
Location: Airstrip One

Thu Nov 23, 2017 7:25 am Post

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:

Code: Select all

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.13 KiB) Downloaded 7 times


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:
Screen Shot 2017-11-23 at 15.21.57.png
Screen Shot 2017-11-23 at 15.21.57.png (86.3 KiB) Viewed 266 times


----
EDIT: this also affects embedded images.

ss
sschertz
Posts: 8
Joined: Fri Nov 09, 2012 9:35 pm
Platform: Mac

Fri Nov 24, 2017 6:40 am Post

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:

Screen Shot 2017-11-23 at 10.31.47 PM.png
Screen Shot 2017-11-23 at 10.31.47 PM.png (282.82 KiB) Viewed 228 times



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

Code: Select all

# 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


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)

User avatar
nontroppo
Posts: 748
Joined: Mon Mar 05, 2007 5:22 pm
Platform: Mac
Location: Airstrip One

Fri Nov 24, 2017 6:50 am Post

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?

User avatar
nontroppo
Posts: 748
Joined: Mon Mar 05, 2007 5:22 pm
Platform: Mac
Location: Airstrip One

Fri Nov 24, 2017 6:59 am Post

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: Select all

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…



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?

ss
sschertz
Posts: 8
Joined: Fri Nov 09, 2012 9:35 pm
Platform: Mac

Fri Nov 24, 2017 7:26 am Post

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.

User avatar
nontroppo
Posts: 748
Joined: Mon Mar 05, 2007 5:22 pm
Platform: Mac
Location: Airstrip One

Sun Dec 03, 2017 12:37 pm Post

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?

User avatar
KB
Site Admin
Posts: 19175
Joined: Tue Jun 13, 2006 11:23 pm
Platform: Mac
Location: Truro, Cornwall
Contact:

Thu Dec 07, 2017 3:59 pm Post

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.
"You can't waltz in here, use my toaster, and start spouting universal truths without qualification."

User avatar
nontroppo
Posts: 748
Joined: Mon Mar 05, 2007 5:22 pm
Platform: Mac
Location: Airstrip One

Thu Dec 07, 2017 4:15 pm Post

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?

User avatar
KB
Site Admin
Posts: 19175
Joined: Tue Jun 13, 2006 11:23 pm
Platform: Mac
Location: Truro, Cornwall
Contact:

Thu Dec 07, 2017 7:35 pm Post

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.

All the best,
Keith
"You can't waltz in here, use my toaster, and start spouting universal truths without qualification."

User avatar
AmberV
Posts: 20600
Joined: Sun Jun 18, 2006 4:30 am
Platform: Mac + Linux
Location: Santiago de Compostela, Galiza
Contact:

Thu Dec 07, 2017 10:13 pm Post

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

User avatar
nontroppo
Posts: 748
Joined: Mon Mar 05, 2007 5:22 pm
Platform: Mac
Location: Airstrip One

Fri Dec 08, 2017 1:51 am Post

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 :D

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

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.

User avatar
AmberV
Posts: 20600
Joined: Sun Jun 18, 2006 4:30 am
Platform: Mac + Linux
Location: Santiago de Compostela, Galiza
Contact:

Fri Dec 08, 2017 2:05 am Post

Oh that was part of the revision, no worries. 8)
.:.
Ioa Petra'ka
“Whole sight, or all the rest is desolation.” —John Fowles

User avatar
nontroppo
Posts: 748
Joined: Mon Mar 05, 2007 5:22 pm
Platform: Mac
Location: Airstrip One

Fri Dec 08, 2017 2:26 am Post

AmberV wrote: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!!! :D RTFM? With pleasure!

User avatar
AmberV
Posts: 20600
Joined: Sun Jun 18, 2006 4:30 am
Platform: Mac + Linux
Location: Santiago de Compostela, Galiza
Contact:

Fri Dec 08, 2017 2:34 am Post

You're definitely a bit batty in that case! Many thanks though. :D
.:.
Ioa Petra'ka
“Whole sight, or all the rest is desolation.” —John Fowles

User avatar
KB
Site Admin
Posts: 19175
Joined: Tue Jun 13, 2006 11:23 pm
Platform: Mac
Location: Truro, Cornwall
Contact:

Fri Dec 08, 2017 10:57 am Post

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.
"You can't waltz in here, use my toaster, and start spouting universal truths without qualification."