View source for Add INCLUDE instruction support for EditPlus files

== Summary ==
Include external file contents in STX, ACP or CTL files.

== Users ==
This instruction pack are for STX, ACP or CTL authors.

== Purpose ==
Sometimes we have to maintain some STX or ACP files which are superset of other STX or ACP files.

Example 1, the XSD file type (W3C XML Schema) and XSLT file type (eXtensible Stylesheet Language of Transformation) are the same time of the XML file type. Thus, XSD or XSLT file types can inherit the syntax definitions from the XML file types.

Example 2, when we compose XSLT files, we usually need to input XSLT instruction elements and HTML output elements. An ACP file for XSLT instructions can benefit from existing XML ACP file and HTML ACP file (if they exist). Currently when we need those ACP definitions for XSLT file type, we have to copy the XML and HTML ACP file content into the XSLT ACP file. If we modify the XML or HTML ACP file, we have to copy them once again, in order to make those changes available for the XSLT file type.

== Solution ==
To avoid manual copying of files, #INCLUDE instruction pack in developed.

The #INCLUDE instruction tells EditPlus to load an external STX or ACP file to the file containing the instruction. So once we define STX or ACP content for the basic file type, other decendant file types can borrow them without the manual copy process.

For example, in the XSD STX file, you can use:

<pre>
#TITLE=W3C XML Schema 1.0
#INFO
....

#INCLUDE=xml.stx

#KEYWORD=Tags
xs:schema
... other definitions of XSD
</pre>

And in the XSLT ACP file, you can use:

<pre>
#TITLE=XSLT 1.0
#INFO
....

#INCLUDE=xml.acp
#INCLUDE=html.acp

#T=xsltransform
<xsl:transform>
    ^!
</xsl:transform>
... other ACP stuff for XSLT.
</pre>

Once you define the #INCLUDE instruction, the included file is automatically merged into the main file.
However, currently EditPlus does not support this. That's the reason for writing this support pack.

== Scripts ==
The pack can be downloaded from EditPlus's Website, http://www.editplus.com/dn.php?n=include.zip.

The pack contains two script files.

==== include.js ====
The first script, include.js, consumes STX or ACP file contents, and process the #INCLUDE instructions by replacing those instructions with contents of the corresponding file.

In order to support reversal operation, the include.js script not only replaces the content, but leaves some hints to indicate contents are taken from the other file. Those hints are formed with a pair of ";<include>" tags. For example, the following two tags encompass contents loaded from xml.stx file.

<pre>
#TITLE=W3C XML Schema 1.0
#INFO
....

;<include file="xml.stx">
CONTENTS from the xml.stx file
;</include>

#KEYWORD=Tags
xs:schema
... other definitions of XSD
</pre>

To generate the included content:
# Use EditPlus to open the STX or ACP file you want to include external files.
# Execute the tool.
# The #INCLUDE instructions will be replaced by the external file content.
# Simply save the file. EditPlus will consume the included content along with the original content.
;NOTE: Don't forget to execute the Refresh STX/ACP command.

==== exclude.js ====
When you want to edit the STX or ACP file. You might need the second script, exclude.js, to revert the content file back to original.

The Exclude.js will find the previously introduced ";<include>" tags, and remove contents between them, then inserts back the #INCLUDE instruction at the beginning of the original file for STX files, or at the place where the ";<include>" tag once resides.

To revert to the original state:
# Use EditPlus to open the STX or ACP file you want to revert.
# Execute the exclude.js tool.
# The output will replace the file content. Simply save it.

== Tool Setup and Usage ==
For the first file include.js.
# Create a new user tool and assign a name for it.
# Command=CScript.exe
# Argument="$(AppDir)\filters\Include\Include.js" //NoLogo
# Initial directory=$(FileDir)
# Action=Run as Text filter (replace fixed cursor)
# Save=None
# You may optionally use the include.ico as the tool icon.


For the second file exclude.js
# Create a new user tool and assign a name for it.
# Command=CScript.exe
# Argument="$(AppDir)\filters\Include\Exclude.js" //NoLogo
# Initial directory=
# Action=Run as Text filter (replace fixed cursor)
# Save=None
# You may optionally use the exclude.ico as the tool icon.

== KNOWN ISSUES ==
* For STX file types, it is recommended that #INCLUDE should appear before any #KEYWORD instructions.
* For ACP file types, #INCLUDE can appear typically anywhere in the file.
* Cicular references are not fully detected.
* If the ";<include>" tags are broken, it may lead to undesirable results.
* If you use the Cliptext panel to load and edit the CTL files, ";<include>" tags will be removed when the cliptext is saved through the panel's Save command, consequently it will be impossible to revert to #INCLUDE instruction with the exclude.js script. So, do not save CTL files with the Cliptext panel.
* Please make a special causion before you save the file.

Special thanks: Fugue Icon http://p.yusukekamiyamane.com for those two icons.