IE-0003: Dividing source text into multiple files

[curiousdannii]

• Proposal: IE-0003
• Authors: Graham Nelson
• Language feature name: None
• Status: Draft
• Related proposals: None
• Implementation: Partial in v10.1

Summary

The ability to split a large source text across multiple text files.

[curiousdannii]

I prefer option 2:

Include source text in "Filename".

Option 3 is interesting, but the caveats make it seem more fragile than option 2. Does changing the level of a source file require changing it in both places? What about if you move code around, would it suddenly complain if there's a section after an external chapter? And who can ever remember the order of "book" and "volume" anyway!

And also, to be honest, the whole .inform/.materials split is weird and doesn't make sense outside of MacOS. If anyone is unaware, in MacOS .inform folders are treated like single files. You can't (easily) access their insides. This makes them convenient for hiding all the build artefacts. But they have the disadvantage that users can't then add other files to them. So we have the .materials folder. And in this proposal we'll then have two source folders! One in .inform which contains only the story.ni, and the other in .materials which contains additional source files. Necessary in MacOS, but kind of weird in the other OSes. Really the build artefacts should have just been in a hidden .build folder. I think it would be great if this .inform/.materials split was abolished in the future, but I know that's almost certainly not going to happen.

[dvanduzer]

I am also intrigued by the Explicit include sentences option because it gives me hints about what to learn, as a long-time Inform Beginner. I glean that the difference between Headings and Extensions is subtle, but crucial to mapping my understanding from other programming languages.

This summary of Kenneth Reitz's guidance on Python Structure is my best anchor. Software repositories of any programming language (or set of programming languages) all appear to share hierarchy and labels, aka folders and files. From here, languages diverge in conventions and requirements for their project structure. Along with all the finicky metadata involved, the core concepts of Python appear to be Modules and Packages, along with Objects and Classes.

IE-0001 proposes Extensions which can now bundle Resources which covers Source code, Documentation, and a variety of other artifacts often called "Assets" in the video game & web publishing industries. The collective noun Extensions is not new to inform, but IE-0003 drops the bigger conceptual bombshell: The Source Text can now contain two very different kinds of multitude. I believe a decent analogy between Python & Inform would be Package : Module :: Extension : IE-0003 Artifacts.

Is there a clear winner for collective noun of this new style of source text/subdivision?

As IE-0003 is currently written, I understand a (Primary) Source Text may include Headings that reference another (Secondary) Source Text. Further, I understand a hierarchy of Secondary Source Texts to be: Volumes, Books, Parts, Chapters, and Sections. Given this understanding, I appreciate intentional flexibility here: it appears it is left to the practitioner to decide whether this hierarchy of Conceptual Source Texts be reflected in the filesystem hierarchy.

[uecasm]

I also prefer explicit Include source text.

Regarding headings, the simplest initial implementation might be to report a Problem if there would be a conflict -- for example, if the Include itself is in a Chapter then the included file can only contain Sections, but if the Include is in a Part then the file can contain both Chapter and Section. Then it still forms a simple unified outline tree. Another option might be to treat them as independent, as already happens for extensions.

And also, to be honest, the whole .inform/.materials split is weird and doesn't make sense outside of MacOS.

I second this. It has long been a pet peeve of mine that the materials folder is not a subfolder of the project. I don't think there's any strong reason to hide the build artifacts; indeed it's quite necessary to look at some of them (such as the debug log) on occasion. And people are used to compilers making a build or obj folder that they can mostly ignore. The current convention is just cluttered, especially if a project doesn't have any materials of note.

It would be nicer if all of the source was in the single Source directory, although having them split is not unprecedented since this is how project-local extensions currently operate.

[zedlopez]

And also, to be honest, the whole .inform/.materials split is weird and doesn't make sense outside of MacOS.

Wholeheartedly agree. It's currently a pain that to track an Inform project in git one needs another directory above the .inform and .materials directories. This proposal comes so frustratingly close to obviating this and allowing one to track only the .materials dir. It would take just a few tweaks to get there:

modifying the IDEs to offer some scheme for letting Settings.plist live under project.materials (I'm personally indifferent to this one and would be elated by the measures below alone...)

modifying inbuild and inform7 to:

• allow specifying a story file (relative to project.materials/Source) in the project metadata; if one is specified it's taken to be the equivalent of project.inform/Source/Story.ni
• allow specifying the project's uuid directly within the project metadata in place of project.inform/Source/uuid.txt

e.g.,

"is": {
        "type": "project",
        "title": "St Anne Passion",
        "author": "Hermione Marmalade",
        "version": "3.2",
        "story": "Main.i7",
        "uuid": "92b2dc1a-b330-4da2-b119-116bd102c03a"
}

[neroden]

I just want to endorse Zed's and uecasm's request to retire the .inform / .materials distinction, merging the directories. It really doesn't play nice with source control or under Linux. If we could get everything into one directory, it would help a ton.

[curiousdannii]

There's been a substantial discussion on the forum the past few days: https://intfiction.org/t/informs-inform-materials-folders/66875