Organizing the source code and creating those beautiful HTML outputs of the code

Hello friends,

I dove right into inform7, thinking I’d create a small game, just to try this out. Well, I really enjoyed it, so I kept doing more, adding on, enhancing… and now I have a decent sized game. 92 rooms, 200 things, lots of stuff…

Unfortunately, I didn’t know about Sections, Volumes, Parts, Chapters, etc… relative to organizing the code. I just used comments like:

[— setup—]
[---- Oxford ----]
[— treasures—]

etc…

to do the organization. I’m embarking on organizing and cleaning up the code. I assume if one uses the official “sections” commands etc, you can somehow create these easily readable html websites like Emily Short’s Bronze site where you can pursue the code in a browser?

Any suggestions on (1) organizing (2) web enabling (3) references…

Thanks in advance,
Greg

1 Like

@simpsong00 - Here a thread on Restructuring code that might prove helpful.

If you Release along with an interpreter and source text. (see documentation “Writing With Inform” §25. Releasing) you will get an index.html page that will contain a Source Text link.

Clicking the Source Text link will display a clickable outline of your source code based on your use of Volumes, Books, Parts, Chapters, and Sections headings.

3 Likes

Definitely use the built-in headings. In the IDE, they give you syntax highlighting and a clickable table of contents, as well as being able to release as neat source code as shown above.

The way I see it, there are two main ways to organize code:

Chronologically: the code goes in order of when the player would (ideally) find it. So you might have something like:

volume - OUT OF WORLD

test me with "turn on sink / z / z / z".

volume - GAME

part - KITCHEN

the Kitchen is a room.

water level is a kind of value.
	the water levels are no water, half-full, lots of water, and overflowing.
	the sink has a water level.
	the water level of the sink is no water.
		
the sink is in the Kitchen.
	the sink is a device.
	the description of the sink is "A sink [if switched on]with a running faucet[else]waiting to be used[end if].".
	

every turn:
	if the sink is switched on:
		if the water level of the sink is not overflowing:
			now the water level of the sink is the water level after the water level of the sink;
		else:
			say "You rush over to the sink.";
			try switching off the sink.

By mechanic: each section is a category (scenes, rules, things, etc.)

volume - OUT OF WORLD

test me with "turn on sink / z / z / z".

volume - WORLD

part - ROOMS

the Kitchen is a room.

volume - OBJECTS

the sink is in the Kitchen.
	the sink is a device.
	the description of the sink is "A sink [if switched on]with a running faucet[else]waiting to be used[end if].".

water level is a kind of value.
	the water levels are no water, half-full, lots of water, and overflowing.
	the sink has a water level.
	the water level of the sink is no water.

volume - RULES

every turn:
	if the sink is switched on:
		if the water level of the sink is not overflowing:
			now the water level of the sink is the water level after the water level of the sink;
		else:
			say "You rush over to the sink.";
			try switching off the sink.

I personally use a mixture of the two, going mostly chronologically but with some sections separated by mechanic.

3 Likes

Perfect Thanks.

Oh yes… It already made it SO much better, just by changing all the comment dividers into volumes, books, chapters, sections, etc… The Index is GREAT.

I think I’ll follow your advice and do a mixture of chronologically and mechanic… I put most of my people together rather than Chronologically, so not sure how that counts maybe a third degree of mixture. (:smile:

Thanks all. This is a great community.

Greg

1 Like

I don’t use the headings much. Source code doesn’t have the same innate structure as a book; why would I try to force it into that structure? Besides a search function will get you where you need to be faster in most cases.

I organize my code by putting different concerns in different extensions. I also use VS Code rather than the IDE, but that’s not required. I don’t find the section navigation in the IDE useful because it’s too slow and clumsy.

The fancy source code site is baffling to me — what’s the point? Code is to be run, not artistically appreciated, right?

Okay my rant is now over.

1 Like

I usually have this idea that I’d like to do general things up front. Variables, decisions, new actions, general clockwork. After that, I do the playable content: rooms and things.

If I have big amounts of data, I keep them at the end.

This is a high-level outline of a pretty big game. I don’t really use the clickable links within the IDE much. It’s the bolded headers that I look at while reading/searching

I also put huge comment spacers in things, and use searchable tags if I need to.

Though I feel things get out of hand after a while. In a big enough project, it can feel like the organization needs organization. I think my only game is like that. For my next big project I’ll keep some things in separate extensions so that I can have more windowpanes to look at without scrolling around.

A lot of what Phil says, basically, though I think it’s fine to like the HTML.

2 Likes

Maybe by that time the next Inform will be out with the support for multiple source files.

1 Like

Code is also to be read and studied to see how other people did things to add to your own projects. Like how did Emily Short implement GO TO [any room] in Bronze?

2 Likes

I’m hyped for new Inform and I hope so!

1 Like

Any idea when new inform is coming?

There have been no announcements, though there is some beta stuff that can be compiled. That’s all beyond reach for me, as I use the IDE and don’t compile… er… compilers.

If I’m even saying that right :smiley_cat:

1 Like

We’re hoping less than the eight years the last release took, but there’s no word yet.

1 Like

When I started collecting Cragne Manor source code, I certainly wanted it to be artistically appreciated. It’s a cross-section of well-known IF authors and their coding styles. Practically a museum exhibit.

Also, why not present the code to onlookers using (roughly) the same stylesheet as the Inform IDE?

2 Likes

I think that Steve Jobs used to stress the elegance of things like wiring and circuits on circuit boards. In his mind, the entire piece should have a quality of construction and an elegance that was there if you looked for it.

In my mind, code is both to be run and can be artistically appreciated.

1 Like

Inform’s philosophy is that any given line of code will probably be read more times than it’s written. So it’s important to think about readability! Your future self will thank you later.

3 Likes

And no software engineer would disagree with you there — but when we think about readability we’re thinking about collaboration, change, and maintenance, not about aesthetics. I’m not sure I find code beautiful. But that’s me. Everyone can value what they value.

1 Like

Yeah, Inform is a bit of an oddball in that department. But the idea is that we’ve got a lot of practice skimming English text, getting the gist of it, and finding the bit we want. So Inform’s designed to tap into that ability—hence the English-like syntax—but that also means presenting it with serif fonts, italics, and so on for better readability.

1 Like

I realize that this approach may not suit everyone (your code, your rules), but on my end, I heavily rely on headers. I divide my work into three parts:

  • Worldbuilding: In this first volume, I code the laws of my universe (light, passage of time, monetary system…), the declarations for property values, and the categories for rooms, persons, devices, backdrops…, as well as the management of scope, prompt, and status bar, all action processing rules, object libraries (unique or duplicated), etc.;
  • Worldsetting: In this second volume, I implement the elements that inherit from the first part and bring the world to life: regions, rooms, inhabitants, interest groups (using relations), mainly recurring events;
  • Story: In the third and final volume, I incorporate the narrative elements; primarily conditional events, everything related to the QBN, and the rules that allow the story to progress from one phase to another.

I code from the first part to the last. Naturally, I need a very precise hierarchy with this approach because, when I decide, for instance, to create a room in the second volume, I need to know all the configuration characteristics that must be filled in (which differ if it’s a library, a mountain pass, or a vegetable garden).

What makes me realize that this method works well for me and that heavy use of headers is useful is that, as the project progresses, the code becomes easier and faster to deploy, and it aligns more with the purely narrative aspects of the story. I also think that the first volume could event be reused for other stories in the same universe and might even have a version number.

Perhaps the use of private extensions could be another way to follow this path, but it’s a subject where my skills are still exceedingly limited (among others).

2 Likes

Wow, Cragne Manor is quite the collaboration! Amazing.