Distribution and support
1. What is QDI
QD Includer (or just QDI) is a program for quick-and-dirty text insertion into source files, developed originally to facilitate maintenance of mid- to large-size Web sites, but usable also outside of that area. The program is free.
The HTML standard does not provide an easy to use code insertion facility (like, for example, one in the C programming language). Neither style sheets, nor server-side includes will replace this feature, the former being too limited in scope, the latter depending on the server software.
Some HTML development tools offer similar functionality, but many of us stay away from them, as the quality of HTML code generated by those tools ranges from very bad to abysmal, and the code is often difficult to manage and maintain. Many HTML writers (myself included) believe that hand-coding, if done the right way, is easier, faster, and results in better pages.
Regardless of all the above, it happens often that we would like the same fragment of code to be shared between a number of HTML documents. How simple would that be if the HTML standard allowed for something like
... some code ...
#include "my_metatags.txt"
... more code ...
#include "site_map.txt"
... more code ...
No way. The text if "my_metatags.html" has to be mechanically inserted in every page using it, and when it needs to be changed, the changes have to be carried out in all files. How stupid.
QDI fills this gap. It will take a directory tree, go through all HTML files in that tree, identify all insertion points and insert (or replace) the insertion text as needed. The whole process will take a minute or two.
2. How to code HTML for QDI
This is quite simple. If you want to insert the files "my_metatags.txt" and "site_map.txt"into a number of HTML files, you will have to modify each of those files like this:
... your old code before the first insertion point ...
<!-- #my_metatags.txt -->
<!-- # -->
... your old code between insertion points ...
<!-- #site_map.txt -->
<!-- # -->
... your old code after the second insertion point ...
Note that the text between "<!--" and " -->" is transparent to all Web browsers, being treated as a comment. QDI recognizes a comment text starting from "#" as the name of file to insert, and a single "#" — as the end of insertion (these markers can be changed when you run the program, if you need).
Now, if QDI finds files "my_metatags.txt" and "site_map.txt", the text from these files will be inserted between the markers like this:
... your old code before the first insertion point ...
<!-- #my_metatags.txt -->
... text copied from "my_metatags.txt" ...
<!-- # -->
... your old code between insertion points ...
<!-- #site_map.txt -->
... text copied from site_map.txt" ...
<!-- # -->
... your old code after the second insertion point ...
Important: all tags specifying the insertions have to be alone on their lines, and not split between lines. Thus, for example, this code will not work as expected:
<HR> <!-- #my_metatags.txt -->
and neither will this one:
<!--
#my_metatags.txt
-->
If at any moment you modify the insertion files and rerun QDI, the old inserted text between the markers will be replaced with the new version. Note that each insertion is a single file.
All insertion files are expected to be stored in the same directory. The default directory is "_i", placed in the local directory (i.e., the one from where you run QDI in the command line mode). This can be changed from the command line.
3. How to run QDI
To run QDI, open a command line interface (DOS session in Windows, or the Take Command shell from JP Software). You may have the location of QDI added to the path, or QDI copied to the directory you are in, or (if neither of these conditions is met), you will have run QDI specifying the full program path.
QDI takes a number of command line arguments, some of the form "/x" (switches), and some — "key=value". No spaces are allowed around "=", and if the value contains spaces, it has to be contained in double quotes which will be removed by QDI.
The switch-like arguments are:
/s — Process files in nested directories (i.e. ones inside the "root" directory, see below);
/q — Quiet mode (do not report files and directories processed);
/d — Use DOS line terminators (CR/LF) as opposed to the UNIX default (CR).
Here are the keyed arguments recognized by QDI. If an argument is not given, the default value will be used. The dot, "." denotes the current directory.
root — The root directory of the tree to modify;
idir — Directory with include files, defaults to
.\_i
files — Specifies the files to process. defaults to
*.html
open — The opening of insertion marker; the default is
<!-- with a trailing space;
close — The closing of insertion marker; defaults to
--> with a leading space.
For example, if you run QDI.EXE from your root HTML directory, and created a sub-directory "_i" there to store your include files, and if your files have an .html extension, you may run QDI just by entering the command line
qdi /s
If, however, your file extensions are .htm, and if you keep your include files just in the root directory, your command may be
qdi idir=. files=*.htm /s
Now, let us assume that, in addition to that, you want to use DOS line terminators (this is only a waste of space, as HTML recognizes the UNIX style under Windows just fine), and you do not want to process the nested directories. This way you have to type in
qdi idir=. files=*.htm /s /d
Notes:
The arguments are separated with single or multiple spaces, and may follow in any order. If an argument was specified more than once, the last definition will be used.
The "files" argument accepts any '*' and '?' wildcards in the customary DOS way. (If you do not know how wildcards work, then QDI is probably not a program for you.) For example, running
qdi files=*htm*
will process all files ending in .htm, .html, .shtm, .shtml, but also, for example a file html_manual.doc if you have it somewhere in your tree.
For additional safety, QDI will not run for files specified as * or *.*.
If any path or file name pattern contains spaces, it has to be enclosed in double quotes like, for example
qdi files="My stupid HTML code\New stuff"
If a path starts from a '\' or from a drive letter, it will be used as absolute, not relative to the current directory. Thus you may use, for example
qdi files="c:\My moronic name" idir=c:\docs\insert /s
If the system cannot find QDI, you may have to specify the full program path, as in
"\Program Files\qdi\qdi" files=c:\www idir=c:\www\_i
Explicit use of the "open" and "close" arguments is usually not recommended; rather use the defaults. The capability of overriding these defaults has been provided only for the adventurous, or for the desperate (for example, if you use QDI for non-HTML text files).
4. How does QDI work
QDI climbs your directory tree from the specified root. In every visited directory it processes all files matching the "files" command line argument.
The processing of a single file is relatively simple.
First, an output file with the same name appended with an exclamation mark, "!" is created. For example, if the processed file is "filename.ext", the output file will be "filename.ext!".
Then, the processed (input) file is read line-by-line (with CR or CR/LF sequences being recognized as line ends). Every line is then echoed to the output file, and terminated with CR or CR/LF, depending on the presence of the /d switch.
This procedure is interrupted if a line specifying an include file is encountered. That line is then copied to the output, but all subsequent ones, until the end-of-include mark, are ignored and the input will be switched to the include file. The latter will then be processed recursively as in (b) and (c), which means that nested includes are possible.
When an include file has been copied to the output, the end-of-include marker is also copied, and a line-by-line copy as in (b) resumes.
If a start-of-include or end-of-include marker is encountered in a wrong sequence, and error message will be issued, and the processing of the current file ends.
When an input file has been processed successfully without any errors (but only then!), the output file is closed. Then the input file is deleted, and the output file is renamed to replace it. This means that files with errors (unmatched or mistyped include tags) will be left unchanged.
Although this assures that no files will be damaged by a misplaced tag, it is still a good idea to backup the files in the directory specified as "root" into a zip file. I never lost any data using QDI (and I'm using it quite a lot to maintain a Web site with about 300 pages), but things happen when you least expect them.
5. Distribution and support
QDI is free to use. Shareware and freeware vendors may include it i their collections as long as this document is also included.
Updates (new features, bug fixes) are available at
http://www.wrotniak.net/works/qdi/index.html
where you can also find my email address.
Although the program is supplied on the "as is" basis, I will be glad to receive feedback: problem reports and enhancement suggestions. On the other hand, I cannot offer you any help in HTML coding, or regarding the Windows directory structure.