Including text from other project

Hi,
I´m trying to create documents to be reused in various projects.
if I use the <$include> placeholder, and use right click -->“link to document”, text from the linked document within a project is inserted correctly.
According to the manual it should also be possible to reuse documents from other projects.
I tried it the following way, but it just doesn`t work:

  • Open the other project that I want to include documents from.
  • Click on the document to be included.
  • Edit → copy special → Copy document as external link
    Open the project where I want to include the document
  • Insert <$include> into the text
  • select <$include>, Edit → add link (no prefix)
    Has anyone advice for me?
    Kind regards
    Tobias

The proper way to do it is to apply the link to that other document to the <$include> placeholder.

If that is what you actually did, then perhaps you need to apply the link as file rather than no prefix.


[EDIT] Nevermind. I don’t think it works.

These instructions are a bit awkward anyways… “or use <$include:docName>, where
“docName” is the name of the document you wish to be inserted.” ← Like the software is gonna take a guess as to its on-disk name and where it actually is ?


The only way I could get the placeholder to work is by linking it to a document that is already in the project.

Looks like otherwise broken (bug) to me.

Or perhaps by “external” what is meant is “external to the actual document” and not “external to the actual project” ??
Which would then lead to wonder what exactly is the Copy document as external link function for.


So, basically in your case, I’d say just drop the external document in your Research folder (or a specific folder outside the draft folder that you’d create for that) and link <$include> to it by selecting the placeholder and right click :

That is the only way I could get it to work.

Mind bender.

Hi Vincent,
thanks for your reply. I had already tried to apply the link to the placeholder and tried the links with different prefixes, the same way like you proposed. I just thought i did something wrong, but the problem seems to be with the program. So the only way it works seems to be to link to documents in the same projects.
Tobias

I managed to make it work.

Forget about Copy document link either from right click on the document or through the Edit / Copy special menu.

You need to export the document you want to use <$include> for in RTF:
File / Export / Files...
Put it somewhere easy to find.
Then select the placeholder, Edit / Add link..., “File” option and browse to the RTF file you just exported.

That works.
. . . . . . . .

Either the manual is kind of vague about it (don’t worry, we all love you Ioa), or that feature just don’t work as it should → I think that it is the link provided through Copy document link that is not coherent with the Add link function (?) ← , but I got it to work that way.
That would avoid cloning the file by inserting it in every project using it, therefor restoring the functionality where there is only one file to modify in order for it to be up to date in all instances of it being recalled (in any project) by the <$include> placeholder.

I suppose you could try and locate the proper “content.rtf” file from the source project’s folder using its super long id (ABEE123D-88C0-4194-A166-9DA68173E62C → I got that from using copy document as external link, then pasted it somewhere to extract the id (phew)),
but I have no idea how safe that would be. [ ← My guess is that it’d be fine, but I don’t want to be the one who encouraged anyone to damage his or her beloved project…]
Else, I suppose one has to constantly re-export the RTF file every time it gets to be modified. (I am pretty sure that ain’t what was initially intended… – especially since a project’s document is already an always up to date RTF file.)

@AmberV or @MimeticMouton or @kewms ??

[Section removed because I’m not actually sure that “external link” and “document link” are different.]

There’s a section on the <$include> placeholder in the manual with a lot more detail than appears in the placeholder tags list. I’m going to refer you there because I’m not sure how the functionality differs between Windows and Mac Scrivener.

The <$include> placeholder is not intended as a way to add the text of documents that reside within a different project. “External” means files outside the project but is referring to freestanding documents, if you will; files that you’d open in Word or Notepad or their ilk. Documents within Scrivener projects can’t be shared with other projects other than by copying the document into the second project—which is easily done via drag and drop, but there is no continued link between the two, so edits made to the document in the second project would have no effect on the copy in the original project.

That may be sufficient for you; and if the document needs to be used multiple times in compiling a single project, you would only need to have one copy in the binder, then use the <$include> tag to place its text throughout the compiled project. But if you want to have a master copy that you can edit and have those changes automatically reflected in all the projects that incorporate that document’s text, you’ll need to keep that as a distinct external file, not part of any project. You can then use the <$include> tag with the file path to add the document’s text into your various project compiles. If you prefer to use a link, select the placeholder tag, choose Edit ▸ Add Link..., then drag and drop the document from File Explorer into the link dialogue.

A semi-compromise between the two above methods would be setting up a shared documents template folder (see Shared Templates on Disk in the user manual). This is a folder outside of a Scrivener project wherein you can save files that then become available to projects via the Project ▸ New from Template... menu. This acts like importing the document, so a new, separate copy is created within the project, and edits you make to it within the project are not reflected elsewhere. Likewise, changes you make to the original in the shared documents folder won’t affect the copies already in your projects. However, any time you add a new copy of that document with New from Template, in any project, it will always be the most recent version of that central template file.

These instructions are within the context of the sentence, which begins “To insert the main text of any document in the current project”—Scrivener is just matching the document name you give with the name in the binder. But as also stated, using the document links is a more reliable method, since you could have multiple documents with identical names, but each document will have a unique link because it uses the item’s internal identifier.

Yes. And I had read it slowly twice before my last post, but unfortunately, the more I read, the more confusing it got as regard to what is “an external document”.
(I think that the fact that Scrivener has a function to “copy document as external link” only made it worse for me. Even more so that these two topics are consecutive to one another. 10.1.5 and 10.1.6 [See ※ at the bottom of this post])
[Keep in mind though that I initially thought that including a document from another project at compile was in fact a possible/intended use of the <$include> placeholder, and that for some reason it just didn’t work at the moment. → In other words: I started biased.]

For example:

that sentence (which is without italics in the documentation) could (and in my opinion should) be improved.
Because, as it is at the moment, it can be read both ways:

To insert the main text of → [any document in the current project]
(which I now understand as being the intended signification),
but also:
To insert [the main text of any document] in the current project
(to insert → in the current project → the main text of any document).

And “document” being what is internally to a project a file named throughout the manual, that can easily get someone on the wrong track in my opinion. (It sure confused me.)

I’d personally reformulate it: To insert the main text of any document from the current project, […].
Although not perfect, since that leaves out the fact that it is possible to link to a “freestanding” file. (As named it MM.)

Anyways, so all in all, what in my previous post I described to be the way I managed to make it work, is actually the very way the feature is in the end intended to. (?)

Although it still leaves the question as to why then, since a document in a project is already an RTF file on disk (and unconditionally up to date, to top it off), one couldn’t simply link <$include> to it.
Wouldn’t that be an answer to any user asking for or about “library” functions/features ?


※ Right off the bat, section 10.1.6 starts with:
image


At least now it is clear to me.
Not a big deal, I was only curious about why it wouldn’t work for @Tobias_technicalauth to begin with, and decided to give him a hand.
(At which, if I succeeded, was by failing. lol)

And thanks for the replies. :slight_smile: