Making TADS Friendlier

So there’s lots of things that could be said in this thread, but here’s an example. If you load up an introductory game, one of the comments says this:

  • Include the main header for the standard TADS 3 adventure library.
  • Note that this does NOT include the entire source code for the
  • library; this merely includes some definitions for our use here. The
  • main library must be “linked” into the finished program by including
  • the file “adv3.tl” in the list of modules specified when compiling.
  • In TADS Workbench, simply include adv3.tl in the “Source Files”
  • section of the project.

Now, as a new person, you might be wondering: so wait, do I have to do this “main library linking thing.” I have to include adv3.tl in the Source Files section? Seriously? Doesn’t TADS do that for me? The introductory source file is a huge turn off.

I’m also thinking that the way to create a new project could perhaps be streamlined. Inform makes this simple: name of story, location, and author. Why can’t TADS do that? The other stuff could be set later when needed. Or, better, just adhere to convention over configuration, provide sensible defaults that “just work,” and then allow more experienced people to tweak when they have more knowledge about even wanting to do that in the first place.

I already mentioned the Getting Started manual in another thread, but this thing really needs an editor and some proofreading if people are going to get much out of this. Example:

“Now open goldskull.t in your text editor of choice (either through Workbench or through the text editor – if you use the second method while compiling through Workbench you might find it a great relief to uncheck the option ‘Ask before reloading a modified source file’ on the Messages tab of the Debugger Options dialogue box that comes up through selecting View/Options from the Workbench menu).”

Put yourself in the mindset of someone who may be trying out Inform and TADS. Reading the above you immediately get a long sentence with nary a breath taken. Also, it seems inaccurate. That menu and that option does not seem to exist. Granted, this only matters if you are using an external editor and compiling from the Workbench. But that one paragraph has a bit of cognitive friction for someone looking for an easy and gentle introduction to their first experience with TADS.

I’ve heard comments about the Inform 7 documentation in that area but, from what I’m seeing, Inform 7 has no issues when compared with the documentation for TADS. Again, though, I’m looking at this from the standpoint of a variety of people with varying levels of experience.

Finally, while I like the TADS Workbench because it’s a development environment, that very same reason may turn off others. Something like the equivalent of Eclipse perspectives may help here. At the very least you have “Minimal Programmer” and “Maximum Programmer” perspectives that provide an appropriate level of detail. Those “minimal programmers” can always opt to turn on features as they learn they need them. If they don’t need them, they may appreciate not having all of it staring them in the face.

Bottom-line: I can totally see why many new people – or even just those who don’t want a “full programming experience” – will prefer Inform 7, regardless of the merits of one language over the other.

That’s on the front page of tads.org.

Now you can argue the merits of calling something a power tool for X, but I don’t think it’s fair to describe in detail how a power tool for X isn’t appropriate for beginners.

I basically agree with bukayeva.

Today I was looking at the docs for the Web/browser play system in TADS 3.1, and I had much the same reaction. Inform’s solution, while admittedly more limited in scope, is much easier for someone to deal with – especially if they’re new to IF authorship or if (like me) their main interest is in being an author, not in being a programmer.

Possibly I’m wrong about some details … I was skim-reading. But it appears the author who wants to allow online play of a conventional text-only T3 game has only one option: to have the game hosted on IFDB. This is not a great burden, but it’s a bottleneck. And you’ll still have to do a few things (and read a lot of quite intimidating documentation) to make sure that your game conforms to the limitations of the browser/interpreter setup.

Because the Inform system is less ambitious, the author of a conventional text-only game basically doesn’t have to do anything by way of separate compilation. The interpreter is loaded into the browser as Javascript code.

To me, one of the chief pleasures of writing IF is that I don’t have to be a heavy-duty programmer. I’m a hobbyist, and I’m happy that way. An authoring system that I can only use by going well beyond the hobbyist level is not a system that is very attractive to me.

What T3 needs, it seems to me, is not a high-end server architecture that maybe three people are ever going to use, and it’s not a stripped-down library (apparently on the drawing board, but not yet released) that eliminates a bunch of useful classes and functionality. The things that will save T3 from the dustbin of computer history are (a) a Macintosh version of Workbench, (b) an interpreter written in Javascript to allow for browser play of existing games without recompilation, and © as you’ve indicated, a fresh look at the whole range of documentation with an eye to the new user’s experience.

I want to make it clear that in no way am I denigrating Eric Eve’s amazing work on the T3 documentation. Without Eric’s hard work, nobody would be using this system. Eric is a lucid and thoughtful writer. But confronted with three completely different books by Eric, all of which teach T3 from the ground up, how is the new user to know which book to use??? The Library Reference Manual is a great resource – but only for the knowledgeable TADS author, not for the newcomer. For the newcomer, it’s completely baffling. After writing several games in T3, I still couldn’t tell you which articles are in the System Manual and which are in the Technical Manual – I have to look it up every time. And there’s no overall index or search facility, so in order to find things, you have to already know where to look. [Edit: I was wrong about the search feature.]

On the other hand, I’m often more grouchy than is warranted. Maybe everything is just fine, and I ought to lighten up.

There’s a great search – in Workbench. Lacking Workbench on Mac/Linux, or use of a VM to put the WIndows version on same, maybe what T3 could use is full-text search of all the manuals on its website…

…oh wait.

tads.org/t3doc/doSearch.php

edit: maybe I’m the grumpy one tonight :slight_smile:.

That’s a fair point, I guess. But given the extremely small size of the user base, I think it’s fair to ask, is a power tool that fails to entice newcomers simply a dead end?

Personally, I like T3 a lot better than I like I7 – but I don’t think there’s any doubt why I7 is about 50 times more popular. And people who start out in I7 do sometimes go on to become power users. If you want to roll up your sleeves and dig into the I6 template layer, you can do so.

I don’t think anybody is suggesting that the power features of T3 be eliminated. That’s not the point at all. The point is, it would be terrific if some energy were devoted to making T3 as friendly for the newcomer as I7.

Perhaps this is not MJR’s job. Perhaps it’s not Eric’s job either. (Given the amount of time that would be required, and the absence of funding, “job” is a loaded word.) But if you’re a fan of T3, as I am, it’s hard not to feel a little frustrated at how marginal it has become – nor is it hard to see why.

A bit of a far fetched analogy, but trying to make T3 beginner-friendly sounds to me like trying to teach someone who studies math for the first time how to solve differential equations. They will allow the student to solve difficult problems, but it’s not going to be a great introduction to general concepts (like how to add, subtract, multiply and divide numbers.)

If you don’t already feel comfortable with algorithms, program flow, even memory management, then T3 is not going to look good to you. And even if you are comfortable with all that, but hate it, then T3 will also taste crappy.

I’m not sure I agree. At least, not completely.

I’ve written two or three games in T3 without ever devoting a moment’s thought to memory management. Flow control, yes. Algorithms … maybe, maybe not.

A great deal of work has been put into making T3 user-friendly. Why else would there be macros like failCheck, TIAction, and dobjFor? I’m pretty sure you could write a large and satisfying game without ever venturing beyond the basic functionality provided by the library. But it would be nice if the newcomer weren’t intimidated needlessly by things like that block of comment text that bukayeva quoted at the beginning of this thread.

Yes, if you want to customize a lister, that’s sort of in the same territory as differential equations. Memorizing the difference between specialDesc, initDesc, and initSpecialDesc … I’d have to look it up. But it is possible, or it should be, to get started and get some satisfying results without worrying about that stuff.

It is simply not true that IFDB is the author’s only choice for hosting. There is a section in the System Manual about it - Setting up a custom TADS Web server. If you want help with it, please just ask. Let us know what resources you’re working with and what your goal is, and we can advise you and walk you through the process.

Your other point, about the limitations of the browser setup, is a fair one. It’s not necessarily clean to switch from adv3 to adv3web. The more effort you put into the UI under the old system, the more pain there will be.

But I would turn it around and say that the new web format really opens up the possibilities. Your game can do anything a website can do, support any features that your web browser supports. TADS 3 doesn’t even have to know about it; it just takes the web files you give it and bundles them up with the game.

adv3web is to adv3 games what the HTML interpreters are to the text-only ones.

Authors have ambitions that go beyond what Inform offers. Look at Vorple. Imagine that you could have that functionality just by compiling your game with the “vorple” lib instead of the “webui” one.

Of course, someone will have to write that library. Ideally lots of people would write lots of libraries, and authors would have an assortment of web UI options. Until that happens, there’s just the one. Fortunately it’s pretty good and it works in nearly every browser.

Suppose someone came out with an Undum-like web library, plus a stripped down TADS 3 library that only knew how to do the things that Undum does, plus a limited IDE that only knew about that one library and only worked with a single source file, and every time you compiled it would upload the file to a server and give you the link.

It would be easier to document, easier to port, and easier to use. It would be very different from the TADS 3 we know today, but underneath it would be the same language and the same infrastructure.

That’s the sort of thing that’s possible now. I can understand if it’s not quite what you had in mind, but maybe give it more than 24 hours before you nail the coffin shut.

What i think we really need are better vm specs. if we had those then a pure js tads terp would be definitely achievable, but as it is now we’d need to reverse engineer the standard terp for tads 2. tads 3 does have a spec but it’s very hard to make sense of.

Interesting thread - I always appreciate constructive feedback. I have a few comments…

First, I think there are two axes that are useful to distinguish when talking about friendliness. One is programmer-vs-non, and the other is newbie-vs-experienced. TADS is obviously pretty firmly planted at the extreme left programmer end of the first axis, and that’s not an accident; the thing about these volunteer projects is that you build what you want to build, and in this case what I’m interested in building is a developer-style tool set, because that’s what I’m interested in using. On the newbie-vs-experienced axis, though, I’m obviously sympathetic to trying to make it approachable. The place where the two axes get muddled is that programming is inherently intimidating to a lot of people, so it’s easy to start thinking of “newbie friendly” as meaning we hide the programming parts. I’m not too keen on that. If someone’s intimidated by programming, they’re probably going to like TADS less the more they get to know it, so there’s not much benefit in trying to lure them in. They’ll just get frustrated later. So my focus is on making TADS a good tool for me and for the kind of people who like this sort of thing, rather than figuring out how to attract people who like different sorts of things.

(That’s why I added the “programmer’s power tool” verbiage to the Web site. There are perfectly good C++ programmers who do that sort of thing at work all day and don’t want to spend their fun goofing-around-with-IF time balancing braces; and there are newbies who have a mind for programming and want something techie looking. Newcomers will be happiest with TADS if it’s the kind of thing they’re already looking for.)

Second, there’s a certain urge to think in terms of what some hypothetical newbie would find daunting about TADS - there’s some of that in this thread, but it’s something that shows up all the time, even in commercial software development. I’ve learned that it’s not a very useful approach, because you’re second-guessing a straw man. The thing is, it’s too easy to imagine newbies as dumber than they really are. It’s more constructive to think about what you personally have found daunting, or better still what’s actually standing in the way of what you’re trying to do. I don’t mean to suggest that rough edges shouldn’t be fixed; if you see something’s obviously an error, or if something was harder than it should have been and you know can clearly envision how it should have been, by all means report the error or suggest the improvement.

Third, and this is kind of a corollary of point #2, I don’t think the first priority needs to be expanding the user base. The first priority is making TADS useful to the people who are using it. If it’s useful to you, there are probably other people like you that it’ll be useful to as well. To a certain extent, it’s probably even preferable from my perspective to have a smaller and deeper group, since I don’t have the bandwidth to handle a ton of new feature directions and so on that a larger group would inevitably be demanding.

Fourth, sorry to repeat an old refrain, but this being a volunteer project that you can tell from the 18 months between releases is already kind of taxing on my available energy, the really constructive thing when you see an area that needs work is to do the work. I know that some of it’s technical work that not everyone is up for, but there are some good suggestions in this thread that look very doable without cracking open a C++ compiler - e.g., an alternative “getting started” guide or two, an improved game creation wizard process (even just mapping out specs for the contents of the initial game template, dialog pages, etc would help - that old game with the suit of armor and loaf of bread in the oven isn’t necessarily the last word in game starter templates), additions/revisions to any of the existing books (you’d have to ask Eric how he feels about that for the GSG et al, but for my portions, I’d be perfectly happy to work with anyone who wants to rework anything or write new chapters - I’ll want to have a say as editor and want to feel that contributions would actually be improvements, naturally, but I harbor no illusions that the bar I set for documentation quality is beyond mortal reach). Workbench for Mac OS would obviously be a more technical project, although remember that there already exists an old version of exactly that by Uli Kusterer, and I bet he’d be willing to let someone take it over as a starting point.

Thanks for the offer. You’re right that I need to investigate further before leaping to conclusions. That said, the article on setting up a custom Web server … well, I’m not going to say it’s completely over my head, because I could certainly spend a few months studying MySql and php, buy a new computer to be the server, probably upgrade my ISP account, learn Linux, and then be ready to ask you for help with setting up the game. Or maybe I could use my existing website host, if I knew what questions to ask them and was willing to upgrade my account. I’m smart enough to figure all that out, but that’s not my idea of fun. I would much rather devote my remaining time on the planet (which I hope will be many years yet) to playing music, writing, and possibly a little gardening.

Am I looking for a turn-key solution? Basically, yes. IFDB provides that, and that’s probably good enough for my purposes. But if Dannii says the bottleneck is understanding the specs of the VM, I’ll defer to Dannii, because I am not competent to write a JS terp, and never will be.

There are, at the moment, a few things I don’t understand about the Web setup. The trial version of “Mrs. Pepper’s” that Nikos uploaded a few days ago had this really weird pop-up box for the hint system, and I have no idea whether that’s the default, or whether it’s an experiment he was trying. So even if I’m content (as I probably am) to write a standard text game that will be playable on IFDB, I don’t exactly know what special steps I may need to take … and I may not know what the game will look like in a browser until I’ve released it, which, now that I think of it, may be a problem. If there are differences between the local version in my computer and the way it looks in Firefox, IE, or Chrome, I won’t know until it’s “live” on IFDB.

Let me think about that for a day or two. Maybe there are things I can do by way of tweaking or fluffing up the documentation. Eric has done a fantastic job, as have you, but my experience as a tech writer assures me that having a second set of eyes scrutinizing a tutorial is always a good thing.

My initial impulse is to feel that adding an entirely new getting started guide might only add to the confusion. But maybe a short “Guide to the Docs” would be useful.

It’s too bad Uli doesn’t want to update his version of Workbench. I asked him about that a year or two ago.

This is a fair point; and not only is the t3 spec a bit obtuse but it’s a little incomplete in light of the evolution of the project over the years. However, I think the core of it - namely the bytecode instruction set and the image file format sections - is actually up to date and pretty approachable. And the thing is, between those two sections, you practically have a spec for a VM; a whole lot of the rest is actually more like an implementation plan; it might be interesting as a source of ideas if you were creating a new implementation, but it wouldn’t necessarily be required reading.

But the big obstacle in my mind to creating a javascript T3 terp is the intrinsics. T3 has become a lot like all the other modern scripting languages in that it has a veritable ton of functionality imported through its native code extensibility interfaces, and that’s all effectively part of the language. That and the speed of a terp-in-a-terp are what daunted me when I initially looked at this a year and a half ago. It’s not just the thought of reimplementing the intrinsics in javascript that gets me, but also the ongoing work of keeping it all in sync, since in practice I’ve been actively expanding the intrinsics, and foresee continuing to do so because it’s so darned useful. It’s obviously the big downside of a rich VM design, but at this point I’ve given in to the idea that this is the sort of VM that T3 is and that there’s no point in trying to draw the line and say this is where the intrinsics are frozen in order to allow other implementations to catch up and stay forever caught up.

As for T2, the lack of a spec seems daunting to me too, but Jetty kind of surprised me by serving as a proof by example that reverse engineering it is doable. Or that Dan Shiovitz is a genius, or maybe both. And looking back at it now, with T3 as the new reference point, T2 really isn’t that complex a machine. As with T3, the important parts for the purposes of building a new implementation are the byte code instruction set, which is all in one big switch statement in one source file, and the .gam file format, which is likewise a fairly straightforward gob of code in one .c file.

The other thing about wishing for more formal specs is that, if you go through the canon of ANSI specs, you might find that C is not the most obtuse formal language that’s ever been devised for the purposes of specifying the behavior of a computer system. :slight_smile:

I can certainly understand that he’s moved on to other projects. Do you happen to know from that conversation if he’s also opposed to someone else taking it over? I’ve been assuming not, and even put a note to that effect on the tads.org download page where the old version is linked for historical reference; if he doesn’t even want anyone to take it over, I should remove that note.

That’s fair enough and a good point. I’m not talking about the language, though. I’m talking about the artifacts that surround the language and make it usable. But even us programmers may get tripped up when we read a comment in the auto-generated file that says this:

  • Note that we aren’t required to define any vocabulary or description
  • for this object, because the class Actor, defined in the library,
  • automatically provides the appropriate definitions for an Actor when
  • the Actor is serving as the player character. Note also that we don’t
  • have to do anything special in this object definition to make the
  • Actor the player character; any Actor can serve as the player
  • character, and we’ll establish this one as the PC in main(), below.

There is no main() below. But as programmer, I’ve heard of main() before. So it must be there. So does this mean a different file that was generated? (I already know the answer; my point is that power programmers also like to feel confidence that they trust what’s being displayed to them.)

Likewise, I read in another comment (again, on the auto-generated starter file):

  • Our game credits and version information. This object isn’t required
  • by the system, but our GameInfo initialization above needs this for
  • some of its information.

What “GameInfo initialization above”?

So if I’m a power programmer, I may not have read the manuals yet because, after all, I’m learning from code and comments in it. Yet from these comments, I now have to read the documentation. And thus I ran into my other issues already mentioned.

Again, though, not dismissing your point: I realize TADS has positioned itself as the “programmer’s power tool for IF authoring” but how the tool can be used and how the tool can be intuited in order to be put to use are two different things. “Newbies” to a system can be power programmers as well; they don’t have to be newbies in the sense of never had programming experience. But they are new to this particular system and that’s more what I was speaking to.

“Weird pop-up box”? Interesting; it’s just meant to look like a dialog window, and yes, it is the default. But this is a v0, obviously; if it’s not what people want, it can be fixed. It’s also one of those cool new endlessly malleable javascript things that’s totally fixable per game - anything and everything you see in the UI is under your control as an author regardless of what the library wants to do. Of course, there’s a small matter of javascript programming, but that’s an area where there are about 10^15 competent programmers in the world, so it might be relatively easy to find someone to help out with that part if you’re not into it yourself.

You can see exactly how it looks locally without setting up any web servers or anything else. The default setup locally is to seamlessly launch an encapsulated IE, and in fact when you’re building under Workbench that’s what you’ll see in every test run. So just by pressing F5 you’ll see exactly what the IE rendering looks like. Right now there’s an extra manual step per run to look at it under other browsers, but you don’t have to set up an Apache or anything like that - all you need is t3run and the browser you want to test with. Now that you mention it, though, this would be a good thing to automate through Workbench - I did a lot of it in my own testing but it didn’t really occur to me that authors would need to do so much of it as the webui lib is supposed to give you browser independence; but of course part of my whole sales pitch is how you can write all this cool javascript code (I just did it ten seconds ago in the upper paragraph of this post, for heaven’s sake), so of course you’ll want to be able to test under different browsers.

Thank you for your kind and courteous appreciation of my efforts, but there seems to be a slight misunderstanding here. There are only two books intended to teach T3 from the ground up: Getting Started and Learning TADS 3. The Library Reference Manual isn’t by me (it’s computer-generated from the comments in the library source code) and it certainly isn’t intended as a tutorial. As its name implies, it’s for reference. The introductions to the other two books try to give some guidance on the different approaches to take, so that new users can select whichever is more likely to suit them.

I reckon I feel pretty much the same as Mike on this subject. I’d also be happy to take constructive suggestions on improving the GSG myself. If I were writing it from scratch today I’d probably take a very different approach, but in sense I already did that when I wrote Learning TADS 3, so I’m not sure I can face writing another tutorial manual from scratch (by which I mean I’m quite sure I can’t), and I get the impression (which may be mistaken) that there are some people who still find the GSG helpful. But I’ve long felt that the introductory sections of the GSG might not be as newbie-friendly as I’d ideally like, so if anyone would like to help me improve them (or offer practicable positive suggestios on how they could be improved) do please let me know.

– Eric

I knew that. That was a bad segue on my part. I was referring to the Tour Guide (implicitly) as number 3, and then segueing to a different topic.

I’ve done a tiny bit of JS programming myself (emphasis on “tiny”), so that part doesn’t scare me. But will I be able to customize the appearance of the box using JS while also writing a vanilla text-only game to be run on IFDB? My guess, based on a very sketchy understanding of the system, would be “no.”

What was weird was the blue banner across the top. Why blue? A nice gray or brownish gray would be less jarring. Other than that, the only weird thing was the missing output filter, which I think you know about.