Clones

By now you may have got an idea of how FillPouch works: You would create index.sd in the main root folder. That finally gets built as "index.html" in the build folder's root folder. Similarly any .sd file in any folder beneath the project's root folder, would get built as its equivalent .html file in the respective folder under the build folder's root folder.

At some point, you may stop and ask: How is this helping if; for every file that is built, we have to write an equivalent .sd file? Huh?

That is where the concept of "clones" come in. Clones are very useful for generating files that has the exact look and feel of other equivalent .html files. For example; you may be writing a blog. You don't want to write an .sd file for each blog article. Instead you create an .sd file only for the first one. And then ask FillPouch to clone the rest from that one file!

How do clones work?
A clone is a file that we do NOT write manually, but pretend that it is there somewhere under the root folder of the project. We only have to spell out a "clone" instruction in the main project file for the project. In that instruction we instruct FillPouch to pick out the correct "file(...)" instruction that is to be used for the cloning.

But we also spell out the full filename of the imaginary file at the correct location, in the clone instruction.

For example; this particular topic in our documentation has been specified in the Project file of our own project for this website as follows:

    ... 
    clone(1,"fillpouchwebsite\\www\\docs\\clones.sd",[g("doctext","fillpouchwebsite\\clones.html")])
    ...

Let us dissect the above clone(...) instruction. Firstly, notice that it has 3 arguments.

1. The Index
The first argument to the clone(...) instruction is an index number. This refers to that particular file(...) which FillPouch will clone. Let us examine those file(...) instructions now. That part of the project file is shown below:

    ...
    file("fillpouchwebsite\\www\\index.sd"),
    file("fillpouchwebsite\\www\\docs\\index.sd"),
    file("fillpouchwebsite\\www\\pricing.sd"),
    ...

Internally, FillPouch will place those file(...) instructions in a list. In true "programmers'" convention; the first element of that list is given an index of 0. That file would be "fillpouchwebsite\\www\\index.sd" But in the aforesaid clone(...) instruction, it had referred to index number 1. That means, FillPouch will take the 2nd element from the file(...) list: Which means this file: "fillpouchwebsite\\www\\docs\\index.sd"

At this point in time, FillPouch would come to know the file that is to be cloned. Now that particular file happens to be an ".sd" file. Which means, that file could have "pouch" meta-instructions in them. That in turn means that file can pull in contents of fragment files into those pouches.

If you examine that file; sure enough, you would see a "pouch" meta-instruction of this type inside the file!

    ...
    [[i("!doctext")]]
    ...

We'll be explaining how such meta-instructions are to be written a bit later in this documentation. What is interesting to note is that the said pouch actually does not have the name of the fragment file. Instead it refers to a variable specified by a g(...) name/value instruction.

Hmmm...where to find that?

FillPouch will return back to the main project file, searching for the value of the variable named "doctext" (BTW, the exclamation mark "!" tells FillPouch that when it does get the value of the variable, please treat that as a filename to be used).

Now in the main Project file, it will find a global g(...) instruction where the variable called "doctext" is defined. And that has a value of "fillpouchwebsite\\intro.html" But there is there is another place where the exact same g(...) instruction is given. That is in the 3rd argument. But before that, let's discuss the 2nd argument of the clone(...) instruction.

2: The cloned filename
The 2nd argument, as you may guessed, is the name of the file that the clone instruction automatically generates. You don't write this file yourself. You just give the path ("fillpouchwebsite\\www\\docs\\clones.sd") and FillPouch will use the referred file ("fillpouchwebsite\\www\\docs\\index.sd") as a "template".

3: A list of g(...) instructions
The 3rd argument is where the "switch" takes place. Instead of using the first g(...) instruction from the project file, FillPouch would use this one instead for the "doctext" variable. So now FillPouch uses a fragment file named "clones.html" from the parent folder of the root and deposits the content of that instead of the original fragment file, which was "intro.html". Why a list you may wonder? That's because you may want to supply more g(...) instructions to FillPouch which specific to that clone, that will replace earlier global g(...) instructions.

So finally, FillPouch puts all this together. It finds out which file(...) has to be cloned, but uses the overridden fragment file, to generate the build.

And that is exactly how this particular topic in this documentation got generated! In fact, we wrote ONLY ONE index.sd in the docs folder for the documentation. Rest of the doc files were cloned correctly by FillPouch!