Overview
The Include File User Item adds text or HTML from an external file to the current chapter, the chapter that is the parent of the Include File User Item. The file's contents are added to the chapter when you make the book.
File Copy Options
- If Copy to Include Folder is checked, Gedcom Publisher will copy the external file to the Include subfolder of the Input (-i) folder.
- If Copy to Include Folder is unchecked, Gedcom Publisher will read the external file from its original location.
There are advantages and disadvantages to each choice.
- If you choose to have Gedcom Publisher copy the external file to the Include subfolder:
- The file will be insulated from inadvertent changes to it. The file's presence in the Include subfolder makes it clear the file is part of the book.
- If you use the Save As command to make a copy of the book, Gedcom Publisher will copy the Input (-i) folder and all its subfolders, including the Include subfolder and the files it contains.
However...
- Changing the version of the file in its original location will have no impact when you make the book.
- You cannot share a file between multiple books. You can share copies, but editing any one of the copies will not change any of the others.
- If you edit the original external file, the change(s) will not be reflected in the book contents. To use an updated version of the external file, you must open the Include File User Item and re-select the original file to update the copy.
- If you choose to have Gedcom Publisher read the external file from its original location:
- The file can be shared by multiple books, and changes to the external file will be included in any books the next time you make them.
However...
- When viewing a file in its original location, there is no way to tell the file is in included in one or more books. It may not be clear that editing the file will change the content of those books.
- Deleting the file will cause an error the next time you make the book.
Include Subfolder
Unlike other subfolders under the Input (-i) folder, the Include subfolder is not copied to the Output (-o) folder. The files in the Include subfolder are only included in the book via the Include User Item or other items that access the content of those files.
Properties
[File...]
Use the [File...] button to choose the file whose content you want to include.
After you choose a file, Gedcom Publisher shows the full path to the file under the [File...] button.
Copy to Include Folder
The Copy to Include Folder checkbox determines whether or not Gedcom Publisher makes a copy of the file when you click the [OK] button to close the Edit Include File dialog window.
If Copy to Include Folder is checked, which is the default, Gedcom Publisher will copy the external file to the Include subfolder of the Input (-i) folder and use that file when it makes the book. If you re-edit the User Item after clicking the [OK] button, the filepath shown underneath the [File...] button will reflect the Include folder location.
If Copy to Include Folder is unchecked, when you make the book, Gedcom Publisher will read the file from its original location. If you re-edit the User Item after clicking the [OK] button, the filepath shown underneath the [File...] button will reflect the original location of the file.
Changing Copy to Include Folder
If you initially set Copy to Include Folder unchecked and click [OK] to save the User Item, then later edit the User Item and change the option to checked and click the [OK] button to update the User Item, Gedcom Publisher will copy the file to the Include folder. When you subsequently make the book, Gedcom Publisher will use the version of the file in the Include subfolder.
If you initially set Copy to Include Folder checked and click [OK] to save the User Item, any subsequent Make Book command will use the version of the file in the Include subfolder. In other words, after saving the User Item with Copy to Include Folder checked, changing the Copy to Include Folder checkbox will not revert to use the file in its original location. To use the file in its original location, you have to use the [File...] button and reselect it.
The checked or unchecked state of the Copy to Include Folder checkbox only matters when you click the [OK] button to close the Edit window and save the changes. At that time, if the file is in its original location, i.e., not in the Include subfolder, and Copy to Include Folder is checked, Gedcom Publisher will copy the file to the Include subfolder and update the filepath to point to it.
Enabled
See Enabled in the Common Properties section of the User Items help page.
Title
The Title property identifies the User Item in the User Items list. The title is not included in the book. Gedcom Publisher updates the Title when you click the [File...] button and choose a file. You can accept the value that Gedcom Publisher creates, or key your own.
Clear
See Clear in the Common Properties section of the User Items help page.