Markdown and <$include> Tag

User avatar
Bridey
Posts: 390
Joined: Wed Nov 22, 2017 2:24 pm
Platform: Mac

Wed Nov 22, 2017 3:51 pm Post

I have created a new project in Scrivener 3 using the blank template.

It contains one file in Draft, called Scene, and another file in Research, called Boilerplate.

Scene contains some markdown and an include tag that references Boilerplate:

This is the text in Draft > Scene. This paragraph has markdown for *italics*, **bold**, and [a link to L&L](http://www.literatureandlatte.com).

This line has an include tag for text stored in Research > Boilerplate. This is the tag: <$include:Boilerplate>


Boilerplate also includes some markdown:

This is the boilerplate text, which also includes some markdown.

+ *Italics*

+ **Bold**

+ [Link to L&L](http://www.literatureandlatte.com)

When I compile using MultiMarkdown > Web Page, both the Scene text and the Boilerplate text are converted properly: italics, bold, and hyperlinks.

When I compile using PDF, RTF, ePUB, or any other format, the Scene text is converted properly, but the included Boilerplate text is left as raw markdown.

Markdown and Include Tag.jpg
Markdown and Include Tag.jpg (142.85 KiB) Viewed 2111 times


Are most compile formats unable to convert markdown included in <$include> tags, or am I making a mistake?

mi
mitchellm
Posts: 105
Joined: Tue Jan 20, 2009 2:10 pm

Wed Nov 22, 2017 4:03 pm Post

I believe the idea is this:

- if it's in the Draft folder (or re-named equivalent) then conduct compile settings (in your case: convert from Markdown).
- if it's in the Research folder (or re-named equivalent) then do nothing during compiling. Always leave "as is"

You could always create another folder in the Draft area for these kinds of things.
Last edited by mitchellm on Wed Nov 22, 2017 4:34 pm, edited 1 time in total.

User avatar
Bridey
Posts: 390
Joined: Wed Nov 22, 2017 2:24 pm
Platform: Mac

Wed Nov 22, 2017 4:31 pm Post

mitchellm wrote:I believe the idea is this:

- if it's in the Draft folder (or re-named equivalent) then conduct compile settings (in your case: convert from Markdown).
- if it's in the Research folder (or re-named equivalent) then do noting during compiling. Always leave "as is"

You could always create another folder in the Draft area for these kinds of things.


Thanks for the suggestion,

I have tried moving the boilerplate text into the draft folder, but the issue remains the same. Compiled to HTML, the markdown pulled from the <$include> tag converts properly, but remains as raw markdown when compiled to any other format.

mi
mitchellm
Posts: 105
Joined: Tue Jan 20, 2009 2:10 pm

Wed Nov 22, 2017 4:55 pm Post

Hmm . . . I'm afraid I can't help you then. I never use include tags so I don't know how they behave exactly. But I'm interested in hearing the full answer! I'm sure a more knowledgeable other person will be able to help you soon.

User avatar
AmberV
Posts: 23699
Joined: Sun Jun 18, 2006 4:30 am
Platform: Mac + Linux
Location: Ourense, Galiza
Contact:

Wed Nov 22, 2017 5:25 pm Post

Hmm, yes it looks like inclusion happens toward the end of the compile process, after documents themselves have been processed to RTF. So if a document never was processed, then the raw text is what you get.

It might be an oversight, I’ll check. There are as you can imagine some labyrinthian conditions where it comes to these placeholders. :)

As for using the MMD compile formats themselves however—it doesn’t matter what order any of this is done in since Scrivener doesn’t actually do any conversion in this case. All of your Markdown text is pass through the MMD engine and converted no mater when or where it gets included.
.:.
Ioa Petra'ka
“Whole sight, or all the rest is desolation.” —John Fowles

User avatar
Bridey
Posts: 390
Joined: Wed Nov 22, 2017 2:24 pm
Platform: Mac

Wed Nov 22, 2017 5:27 pm Post

mitchellm wrote:Hmm . . . I'm afraid I can't help you then. I never use include tags so I don't know how they behave exactly. But I'm interested in hearing the full answer! I'm sure a more knowledgeable other person will be able to help you soon.


Thanks, again. And the <$include> does work for compiled HTML even if the referenced file is in the research folder, but not for other formats.

This <$include> behaviour is new to S3. It promises to be very useful for repeated text, such as bios or advisories that need to appear in multiple documents. Saves copying and pasting and keeping in sync if only one master file is ever needed.

User avatar
Bridey
Posts: 390
Joined: Wed Nov 22, 2017 2:24 pm
Platform: Mac

Wed Nov 22, 2017 5:33 pm Post

AmberV wrote:Hmm, yes it looks like inclusion happens toward the end of the compile process, after documents themselves have been processed to RTF. So if a document never was processed, then the raw text is what you get.

It might be an oversight, I’ll check. There are as you can imagine some labyrinthian conditions where it comes to these placeholders. :)

As for using the MMD compile formats themselves however—it doesn’t matter what order any of this is done in since Scrivener doesn’t actually do any conversion in this case. All of your Markdown text is pass through the MMD engine and converted no mater when or where it gets included.


Thanks, Ioa. Yes, logic suggests it is something to do with the compile sequence. Clearly works in HTML, so hopefully it will be possible for other compile formats as well. Be interesting to hear Keith's insight.

User avatar
AmberV
Posts: 23699
Joined: Sun Jun 18, 2006 4:30 am
Platform: Mac + Linux
Location: Ourense, Galiza
Contact:

Wed Nov 22, 2017 5:40 pm Post

Do you mean when compiled to MMD->HTML? Because if so then that method doesn’t rely upon Scrivener to convert the MultiMarkdown to RTF internally—that would in fact mess it up. It does that for its own formats, like ePub and the HTML option up next to ePub, etc. For all of those options below the “MultiMarkdown” entry, Scrivener just assembles the text together as plain text and passes that result to MultiMarkdown, which then produces HTML or whatever.

This <$include> behaviour is new to S3. It promises to be very useful for repeated text, such as bios or advisories that need to appear in multiple documents.

It can be quite useful indeed! I just did a quick search and I used it over a hundred times in the user manual. Sometimes the way a menu command is described would be inserted into a bullet list elsewhere, where a group of menu commands are documented together. Sometimes a group of closely related preference panes would have a common “See Also” list they all share, that sort of stuff.
.:.
Ioa Petra'ka
“Whole sight, or all the rest is desolation.” —John Fowles

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

Wed Nov 22, 2017 6:00 pm Post

I have fixed this for the next update, but the <$include> tag will always have certain limitations. For instance, Scrivener won't be able to convert Markdown for text files that are stored externally and included - it can only do this for text files stored in the project itself.

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

User avatar
Bridey
Posts: 390
Joined: Wed Nov 22, 2017 2:24 pm
Platform: Mac

Wed Nov 22, 2017 6:06 pm Post

AmberV wrote:Do you mean when compiled to MMD->HTML? Because if so then that method doesn’t rely upon Scrivener to convert the MultiMarkdown to RTF internally—that would in fact mess it up. It does that for its own formats, like ePub and the HTML option up next to ePub, etc. For all of those options below the “MultiMarkdown” entry, Scrivener just assembles the text together as plain text and passes that result to MultiMarkdown, which then produces HTML or whatever.


Yes, MMD > HTML works. The separate compile to Web Page serves the <$include> text as raw markdown. Apologies for not being clear about this originally. I am mainly hoping to get the <$include> to work for output to ePub and Kindle, when the included file has markdown in it. Your explanation helps to explain the compile sequence. Wonder if it can/will be tweaked to work as I hope.


AmberV wrote:It can be quite useful indeed! I just did a quick search and I used it over a hundred times in the user manual. Sometimes the way a menu command is described would be inserted into a bullet list elsewhere, where a group of menu commands are documented together. Sometimes a group of closely related preference panes would have a common “See Also” list they all share, that sort of stuff.


I think it is a significant S3 feature. Makes managing repeated text so much easier. One master file for boilerplate copyright info, another for a biography, etc.

User avatar
Bridey
Posts: 390
Joined: Wed Nov 22, 2017 2:24 pm
Platform: Mac

Wed Nov 22, 2017 6:10 pm Post

KB wrote:I have fixed this for the next update, but the <$include> tag will always have certain limitations. For instance, Scrivener won't be able to convert Markdown for text files that are stored externally and included - it can only do this for text files stored in the project itself.

All the best,
Keith


That's great news.

Hadn't even thought about linking to an external file. Will have to experiment, especially to see what formatting an external <$include> file does take on.

Thanks.

User avatar
AmberV
Posts: 23699
Joined: Sun Jun 18, 2006 4:30 am
Platform: Mac + Linux
Location: Ourense, Galiza
Contact:

Wed Nov 22, 2017 6:20 pm Post

Yeah I was about to say, in terms of common copyright pages and "about this author" type stuff: external files!
.:.
Ioa Petra'ka
“Whole sight, or all the rest is desolation.” —John Fowles

User avatar
Bridey
Posts: 390
Joined: Wed Nov 22, 2017 2:24 pm
Platform: Mac

Wed Nov 22, 2017 6:30 pm Post

AmberV wrote:Yeah I was about to say, in terms of common copyright pages and "about this author" type stuff: external files!


Any tips on external file type (TextEdit, Pages, etc?) or font/paragraph formatting? Or do external files take on a variable compile section layout?

User avatar
AmberV
Posts: 23699
Joined: Sun Jun 18, 2006 4:30 am
Platform: Mac + Linux
Location: Ourense, Galiza
Contact:

Wed Nov 22, 2017 6:52 pm Post

It depends on what you need:

  • If you need formatting, then use RTF. TextEdit would work for that, but so would even Scrivener and then exporting the file from the binder. Pages isn’t much use as a format to anything but Pages. Apple never released the specs.
  • TXT if you don’t need formatting and want to ensure the injected text takes on whatever local formatting is around the injection point. Also if you’re using Markdown for that then TXT would work best.
The details of how all of this works—with regards to how styles are treated, formatting, compiling stage format overrides, and so on—are in §10.1.5, starting on pg. 208.

Given the flexibility, there aren’t a few simple rules. If you insert a plain-text snippet into an inspector footnote for example, something different is going to happen than if you import a ten page RTF file from somewhere. :)
.:.
Ioa Petra'ka
“Whole sight, or all the rest is desolation.” —John Fowles

User avatar
Bridey
Posts: 390
Joined: Wed Nov 22, 2017 2:24 pm
Platform: Mac

Wed Nov 22, 2017 7:42 pm Post

Thanks for all the advice.

AmberV wrote:Also if you’re using Markdown for that then TXT would work best.


Keith, above, says "Scrivener won't be able to convert Markdown for text files that are stored externally", but are you saying markdown is okay?

I have added an <$include> tag, selected it, and then chosen Edit > Add Link to link to a test RTF file on my desktop. I can't get that to compile. I also tried <$include:/Users/username/Desktop/RTF.rtf>, but that doesn't compile either.

<$img:/Users/username/Desktop/sample.jpg> does work for an image, so I assumed a file would work in the same away.

Will figure it out.