Categories, Subcategories and Sub-Items Folders

[tajmone]

Parsing the source files' headers is the simpler part of this app:

• every file with *.pb or *.pbi extension is parsed,
• source files that yeld no <key>:<value> are ignored on the assumption that their are additional files included by some other resource.

The tricky part is how to go on about the project's structure: some directiories are categories, others are containers of multi-file resources. Usually every folder is a category containing single source-file independent resources, but sometimes a resource is made up of multiple files and gets a folder of its own.

For example, let's take the Gadget directory:

-+-/Gadget/                   <= "Gadget" Category
 |---/ButtonGadget/           <= Sub-Category
 |---/MultiGraph[Win]/        <= "Gadget" entry in subfolder
 |---[...]
 |
 |- GetGadgetClass[Mac].pbi   <= "Gadget" entries
 |- Hide_or_change_cursor_over_gadgets_without_OS-API.pb
 |- [...]
 |- Tooltip[Win].pbi
 |- TransformationOfGadgetsAtRuntime.pbi
 |- WindowManager_ParentGadget_ParentWindow_ScaleWindow.pbi

All the source files inside Gadget folder are resources of that category and should be indexed therein. As for the folders inside Gadget, some are subcategories that should be indexed through recursion (eg: ButtonGadget is a category), while other folders are just multi-file entreis of the Gadget category (eg: MultiGraph[Win]) and should be indexed therein.

How is the website builder going to distinguish between a folder that is a sub-category and one that is just a container of a multi-files resource? Also, some folders should be excludable from the indexing process (eg: the assets folder that will contain CSS stylesheets, images, and the website builder app itself).

The simplest approach would be to have a small configuration file in each folder, from which the app could obtain data about files and folders. But the cons of this solutions are:

• it pollutes the project with files that are of no interest to the end user
• configuration becomes scattered in multiple files

Another approach would be to have a single configuration file next to the website builder app: something like a JSON file replicating the project's folders strutcture, where each folder becomes a key with an associated value indicating whether the folder is:

• "excluded" form indexing and HTML rendering
• "category" folder
• "subitem" folder containing a multi-file resource belonging to the the category of the parent folder

This approach could be handled by the app retriving the JSON settings and comparing them to the actual folders present on disk, so that new uncategorized folders can be spotted and present the user with a choice to assign to it one of the above classifications.

The best solution would be, of course, if the app was able to automatically detect how to handle folders.

For example, we know that each category will also have a README.md file that will be used to build the introductiory text of each category in the final HTML page. A raw HTML comment could be placed at the beginnin of the README.md file, containing some <key>:<value> pairs settings to help the app decide how to handle the folder:

<!-- category: true
     whatever: xyz
-->

These comments wouldn't show up in the README.md preview on GitHub website, and they are a good alternative to having separate settings files in each folder. Alternatively, we could use YAML headers:

---
category: true
whatever: xyz
...

... GitHub accepts them, but they would show up in the README's preview online.

Folders that are containers to multi-file resource might also contain a README.md file — written specifically for that resource, and not intended for the creation of an HTML page in the website. But similar files would not contain parsable HTML comments.

Therefore, the absence of a README.md file inside a folder (or a README.md file without parsable comments) would be a tell-tale sign for the website builder that the folder is not a category folder, but either a multi-file container or a subfolder of a similar container.

The idea is to keep the configuration system as simple and as incospicuos (to the end user) as possibile; and at the same time, it should produce a website which is comfortable to navigate with a browser (both online as well as locally).

@SicroAtGit: Any suggestions on this? How does this approach seem?

I would much appreciate your feedback on this as you know better than me the current project's structure and the logic behind its organization, and how it might grow in the future.

[SicroAtGit]

every file with .pb or .pbi extension is parsed,

The file "CodeInfo.txt" should also be parsed. If the code consists of several files/subdirectories, the code header isn't in the code files, but in the file "CodeInfo.txt".

How is the website builder going to distinguish between a folder that is a sub-category and one that is just a container of a multi-files resource?

If the subdirectory contains the file "CodeInfo.txt", the subdirectory isn't a category/subcategory, but a container for a code consisting of several files/subdirectories.

In the container subdirectories, the license text is also not in the code files, but in the file "License.txt".

The subdirectory "MultiGraph[Win]" I think I should rename it to "MultiGraphGadget[Win]" to make it clearer.

The supported operating systems aren't only listed in the code headers, but also at the end of the code file names. If the codes consist of multiple files (container subdirectory), the container subdirectory name contains the list of supported operating systems and not the file names of the code files in them. I implemented this with the listing of the supported operating systems in the code file names and container subdirectory names, because I wanted to make it clear beforehand whether a code supports the operating system or not, without having to look into the code.

[tajmone]

If the subdirectory contains the file "CodeInfo.txt", the subdirectory isn't a category/subcategory, but a container for a code consisting of several files/subdirectories.

Great! this is a sufficient indicator! it will allow do to do without all the settings files or comments inside README files.

The supported operating systems aren't only listed in the code headers, but also at the end of the code file names. If the codes consist of multiple files (container subdirectory), the container subdirectory name contains the list of supported operating systems and not the file names of the code files in them. I implemented this with the listing of the supported operating systems in the code file names and container subdirectory names, because I wanted to make it clear beforehand whether a code supports the operating system or not, without having to look into the code.

This might also come handy.

Then I'll go for a fully automatic system that doesn't require settings, but just parsing comments headers, the "CodeInfo.txt" files, and files and folders names.

I could feel that there was more to it then the eye met, and that these organization elements could be exploited to keep the whole thing simpler.

Good. Now I have enough to go on for implementing most of the code structure. Once that is over, we'll check the details (usually the Devil is in details 😉).

[SicroAtGit]

Concerning the listing of supported operating systems in the code file name/container subdirectory names: If the code works under all three operating systems (Windows, Linux, Mac), there is no listing. In the code headers or in the file "CodeInfo.txt", however, the listing always exists - even if all three operating systems are supported.

[tajmone]

In the code headers or in the file "CodeInfo.txt", however, the listing always exists - even if all three operating systems are supported.

this is good, so the parser can rely fully on "CodeInfo.txt"'s headers, and ignore the folders/files names OS embedding system (currently, it seems I can achieve the task without having to examine the file/folder name for OS support).

I've implemented the first prototype of the project structure scanner: "BuildProjectTree.pb". It's called "Project Tree", but I've decided not to use a real Tree structure to store data, but use a structured List instead — after all, categories are independent folders for which the app must build an index.html page for. Using a Tree structure wouldn't add any benefits.

The List has an entry for each category, thus structured:

Structure Category
  Path.s
  List SubCategoriesL.s() ; Name/Link List to SubCategories
  List FilesToParseL.s()  ; List of files to parse (including "<subf>/CodeInfo.txt")
EndStructure

• Path.s — is relative to the project's root, and is where the index.html will be written to, and the README.md file looked for.
• List SubCategoriesL.s() — if a category has subcategories, it should list them at the beginning of the page (before or after the description) as links that allow navigation a further level down the categories tree.
• List FilesToParseL.s() — contains a ready-made list of the names of the PB source files and "CodeInfo.txt" files (of sub-foldered items) that should be parserd to extract info from header comments.

This is all the program needs in order to build an HTML page for each category. The README.md file in each category will provide the main description of the category, and each item of the category contains it's info and description in the header comments (or "CodeInfo.txt" file).

Now I need to join this code with the comments parser, and add the code that actually builds a full HTML page. Once we get to that stage, I can start working on an HTML5 template — I was thinking of something rather minimalistic. But I'll dedicate an Issue of it's own to the template.