The Project File

FillPouch requires one project file per site. Such a project file will contain pure instructions that FillPouch understands. They have to be written exactly as per the syntax of those instruction. The project file can be kept anywhere. It can have any file extension, but we suggest you give it the extension of .proj and it is normally kept in the same folder as the fillpouch executable.

FillPouch has to be "fed" this project file on the Windows command line (the black "cmd" window). Only then can FillPouch do its magic.

Meta-instructions and project instructions
The instructions placed inside the main project file are called "project instructions" or just "instructions" for short. They are different from the meta-instructions that you place in other files written for the project. The latter (i.e. meta-instructions) are processed during the build process; and FillPouch would use the data in the project instructions to provide the data and/or affect the working of those meta-instructions.

The following project instructions can be present in a project file. Each should follow the precise syntax we explain here and each such instruction must be separated from the next by a comma (i.e. it is comma-delimited). For clarity you can give white spaces (Carriage-return key). For readability, it is recommended to place one instruction per line.

Syntax of the project instructions:

     root(STRING rootfolder)
     directFiles(SLIST listofstrings)
     g(STRING name, STRING value)
     file(STRING filename)
     clone(INTEGER fileidx,STRING filename,NVLIST tmpGlob)

In the above list, the words given in UPPERCASE are the arguments to be provided for the respective instruction. The word next to it is just an explanation of what it stands for. You will understand it when we take a look at the project file for our own website here.

An example of our own project file:

     root("fillpouchwebsite\\www"),
     directfiles([".txt",".md",".crl",".html"]),
     g("header","fillpouchwebsite\\header.sd"),
     g("cpy","fillpouchwebsite\\footer.html"),
     g("title","Fillpouch!"),
     g("subtitle","A great design is just one hop away!"),
     g("home","https://fillpouch.com"),
     g("foot","fillpouchwebsite\\footer.sd"),
     g("head","fillpouchwebsite\\navbar.sd"),
     g("doctext","fillpouchwebsite\\intro.html"),
     g("talltale","fillpouchwebsite\\talltale.html"),
     g("pricing","fillpouchwebsite\\pricing.html"),
     g("onetiny.html","fillpouchwebsite\\onetiny.html"),
     file("fillpouchwebsite\\www\\index.sd"),
     file("fillpouchwebsite\\www\\docs\\index.sd"),
     file("fillpouchwebsite\\www\\pricing.sd"),
     clone(1,"fillpouchwebsite\\www\\docs\\Concepts.sd",[g("doctext","fillpouchwebsite\\concepts.html"),
                                                         g("tags","concepts,basics,reductionism,divide and conquer")]),
     clone(1,"fillpouchwebsite\\www\\docs\\editor.sd",[g("doctext","fillpouchwebsite\\editor.html"),
                                                       g("tags","vscode,editor,IDE")]),
     clone(1,"fillpouchwebsite\\www\\docs\\Folder_structure.sd",[g("doctext","fillpouchwebsite\\folders.html"),
                                                                 g("tags","structure,tree,generation")]),
     clone(1,"fillpouchwebsite\\www\\docs\\Project_file.sd",[g("doctext","fillpouchwebsite\\projectfile.html"),
                                                             g("tags","project instructions,meta-instructions,syntax,example")]),
     clone(1,"fillpouchwebsite\\www\\docs\\Generation_overview.sd",[g("doctext","fillpouchwebsite\\overview.html"),
                                                                    g("tags","simple example,pouch,generation")]),
     clone(1,"fillpouchwebsite\\www\\docs\\Main_files.sd",[g("doctext","fillpouchwebsite\\mainfiles.html"),
                                                          g("tags","main files,raw HTML,reductionism,divide and conquer")]),
     clone(1,"fillpouchwebsite\\www\\docs\\fragments.sd",[g("doctext","fillpouchwebsite\\fragments.html"),
                                                          g("tags","breadcrumbs,Bulma")]),
     clone(1,"fillpouchwebsite\\www\\docs\\Using_styles.sd",[g("doctext","fillpouchwebsite\\using_styles.html"),
                                                             g("tags","bifurcation,divide and conquer,reductionism,styles")]),
     clone(1,"fillpouchwebsite\\www\\docs\\clones.sd",[g("doctext","fillpouchwebsite\\clones.html"),
                                                       g("tags","imaginary file,pouch,meta-instructions")]),
     clone(1,"fillpouchwebsite\\www\\docs\\Meta_instructions.sd",[g("doctext","fillpouchwebsite\\metainstructions.html"),
                                                       g("tags","pouch,delimiters,directfiles,multiple")]),
     clone(1,"fillpouchwebsite\\www\\docs\\Auto_links.sd",[g("doctext","fillpouchwebsite\\autolinks.html"),
                                                          g("tags","file instructions,clone instructions,embed,iteration")]),
     clone(1,"fillpouchwebsite\\www\\docs\\advanced.sd",[g("doctext","fillpouchwebsite\\advanced.html"),
                                                         g("tags","curl,pandoc")]),
     clone(1,"fillpouchwebsite\\www\\docs\\troubleshooting.sd",[g("doctext","fillpouchwebsite\\troubleshooting.html"),
                                                              g("tags","bugs,bugasura")]),
     clone(1,"fillpouchwebsite\\www\\docs\\tags.sd",[g("doctext","fillpouchwebsite\\tags.html"),
                                                     g("tags","tags,javascript")]),
     clone(1,"fillpouchwebsite\\www\\docs\\About_us.sd",[g("doctext","fillpouchwebsite\\author.html"),
                                                     g("tags","Limen Leap Labs")]),
     clone(1,"fillpouchwebsite\\www\\docs\\License.sd",[g("doctext","fillpouchwebsite\\license.html")]),
     clone(1,"fillpouchwebsite\\www\\docs\\Feedback.sd",[g("doctext","fillpouchwebsite\\feedback.html")]),
     notes("This project is for the website of FillPouch")

Let us go through each of the instruction. You may have already noticed that some instructions were given only once. But some other instructions were repeated multiple times (with different data). Also note that long lines can be split up using carriage returns.

General Notes
One critical point is that each instruction is separated from the next using a comma. Do not forget that delimiter! But also note that there is NO comma after the last instruction has been written down.

Note that absolute folder locations are not given. It is assumed that the path start from the main project folder. (Which, by default, is the "projs" sub-folder present in the folder where the FillPouch executable resides ) That is main folder where all the projects have their respective sub-folders.

The subfolder we used for this project (i.e. this website) is called fillpouchwebsite and that is the first folder you see on the paths. Once FillPouch does its work, the actual site will be placed in folders of the same names as those in the project folder; but created in the build folder.

Note also that strings are identified ONLY by quotation marks. (Not by apostrophes!) If there are backslashes inside strings such as the delimiter for folders in Windows; those must be doubled-up!

These instructions can be written down in any order in an text editor. But for clarity, it is recommended that you follow the aforementioned order and in case there are multiple instruction of the same time, please put them one after another instead of mixing other instructions inbetween.

Now here are the explanations for the Project instructions. We have given our entire website files in the zip file that you download for FillPouuch. Keep the "fillpouch.proj" file (the one that was used to ) open in a text editor when reading the explanations below:

root(STRING rootfolder)
Only one such instruction should be present in the project file. This instruction specifies the root of the site tree. i.e. the 'www' folder.

directFiles(SLIST listofstrings)
Only one such instruction should be present in the project file. The list of strings given to this are those file extensions whose file contents would be used by FillPouch directly. i.e. you should NOT put meta-instructions in those files, and if they are present, they would be ignored. Note that the .md files are first silently processed by pandoc to .html and then used. Similarly, the .crl files would be sent to the curl program, and curl is expected to return some HTML fragment back to FillPouch.

g(STRING name, STRING value)
You can have any number of these "g" instructions. They are global "name-value" pairs. The first argument is a variable name. The second is the value that variable represents. This is used to store some commonly used values, such as title of pages, sub-titles, etc. They can later be overridden by individual meta-instructions found in the files of the project.

file(STRING filename)
You can have any number of such "file" instructions. One such file instruction should be present at the very least! That should be resulting in the "index.html" in the project's root folder when building, else the site will mostly not open in most servers. These are the "main" files of your site. Each file here is an actual file that exists in the correct location under your project folder. FillPouch collects the entire list of these "file" instructions, and starts from the first and proceeds till the list is empty. Each such file can contain "pouch" meta-instructions FillPouch will read each character of each file, and deposits the same in the .html file being generated in the equivalent folder under the build folder. When FillPouch encounters one of those "pouch" meta-instructions, it will act as per those instructions and return back to process the rest of the file accordingly.

clone(INTEGER fileidx,STRING filename,NVLIST tmpGlob)
You can have any number of such "clone" instructions. The 1st argument is the index number referring to the list of "file" instructions present in the project folder.

The 2nd argument is the name of the cloned file that FillPouch would use. You do NOT create such a file yourself. FillPouch will use the referred file from the "file" instruction and use that instead. Along with that, you can also specify a list of "g" name-value pairs (as the 3rd argument of this instruction). If there is a variable defined earlier as one of the "g" instruction, FillPouch will silently override that with the one given here.

This is very useful to create multiple pages quickly from one template. The documentation of our own website was created using such instructions.

In the above example; the 0th file would be fillpouchwebsite\\www\\index.sd and the file instruction would be for fillpouchwebsite\\www\\docs\\index.sd has an index number of 1. So if you notice the clone instructions, the cloning was being done for that file, and this how the files in the docs folder in the build were generated. Even though we wrote only 1 file: index.sd in the docs folder of the project, it cloned the rest of the files from it; and changed the internal contents.

tags(INTEGER index, STRING tags)
Tags is an optional instruction that you can give. You can have any number of such instructions. The tag(...,...) instruction takes two arguments, and it is used to help you create tag clouds for your website. This instruction is explained in more detail, in another chapter of this documentation. Note since version 0.5.3 it is better to give tags as g("tags",...) in the last argument of the clone(...,...,...) instruction!

notes(STRING description)
This is an optional instruction that can be given in the project file. You can write a note about this project here. Only one such instruction should be given.