TADS 3.1 released!

Time to get excited! :slight_smile:

tads.org/ov_tads31.htm

Fantastic! Some of the new features are high-end stuff that Iā€™m not likely ever to use, but there are some enhancements that (if I were writing a game) Iā€™d use every day, including one thatā€™s obviously borrowed from a certain other popular IF authoring system. Very handy indeed.

The web server features look extremely muscular, but as Iā€™m not really a programmer, Iā€™m not sure yet what to make of them.

Congrats to MJR and the team!!!

Yeah!
The new Layout looks great!
The new features look awesome!
Thanks to all the people who contributed!

Greetings,
ā€“ MI

This is great stuff. Iā€™m finally going to give TADS more than a passing glance.

That brings me to an observation, not necessarily related to this version.

I decided to start going through the users guides. And I can maybe see why TADS wouldnā€™t appeal to new people. I was reading (local reference of installed docs): file:///C:/TADS3/doc/gsg/creatingyourfirsttads3project.htm.

This is a really convoluted intro to new people getting started with TADS 3. I could easily see this turning off newbies or people with little experience setting up tools. It mentions too many specifics (like ā€œIf youā€™re using Windows NT, 2000, or XPā€¦ā€) that shouldnā€™t be there; if someone is adding to their environment PATH, they know this stuff. For those that donā€™t want to, this is just noise that makes things seem complicated. Thereā€™s also: ā€œIf youā€™re on Unix, for example, youā€™d type mkdir obj.ā€ Well, yeah, it would be the same on Windows as well. (It feels like this one page was written by two entirely different people.)

Also mention is cumbersomely made of the ā€œDOS command prompt on Windowsā€ ā€“ but if you have someone running TADS like this, you can probably just say ā€œat the command lineā€ since anyone embarking on that approach will already understand this concept. Talking about ā€œDOS command promptā€ and ā€œWindowsā€, again, just seems to throw a lot at someone who may just be getting started. Thereā€™s also too much reference to TADS 2, even on just this one page. Someone coming at this new, wonā€™t even have that background and may wonder if they should, based on what they read. (Put TADS 2 specific notes as a footnote or something.)

More importantly, on the Web version of the guide, under ā€œii) Creating a project manuallyā€, it shows an example but that example doesnā€™t show

#include <adv3.h>

while a latter mini-example on that same page does. Thatā€™s not the case in the PDF, however. The PDF example does have the missing line. So, now, as a user I donā€™t know which guide ā€“ of this same exact document ā€“ I can trust. Then a ā€œproject fileā€ is explained (sort of) and it seems a little obtuse unless you know about build and/or make files. Right away I can just see this turning off people new to the system. And this is just in the first section of the first manual ā€“ and a ā€œGetting Startedā€ one at that.

Iā€™m not moaning about the author of the work since I appreciate when anyone takes time to document. Again Iā€™m just stating the observation that if thereā€™s a desire to get people involved in TADS, having documentation proofread might help quite a bit. If I didnā€™t have my background context, I probably would have given up already and just gone to Inform 7 which seems a lot easier to get right out of the box.

Hereā€™s another example from the same page:

ā€œWe promised earlier that weā€™d provide an explanation of the gibberish in the .t3m file. You should be able to get quite far sticking to the recipes above, so feel free to skip this section if you donā€™t feel you need the details right now.ā€

So itā€™s ā€œgibberishā€? Thatā€™s encouraging to a new user. But beyond that: ā€œfeel free to skip this section if you donā€™t feel you need the details right now.ā€ Okay ā€“ but how do I know? As a new person, I donā€™t know what I donā€™t know. I donā€™t know the things I need and donā€™t need. And given that I already have trust issues with the document, now Iā€™m even more uncertain.

And hereā€™s another example where PDF and Web differ. The PDF includes this line:

-D LANGUAGE=en_us

The Web version does not.

Again, I understand: you may not need this. It may be handled for you. It may just be ā€œgibberish.ā€ But it took me no time at all to find these discrepancies. Everyoneā€™s frustration factor is different but it seems text adventure development has a wide range of users with very differing levels of experience in terms of using tools like these.

Sorry ā€“ at this point, Iā€™m derailing the thread. But given that TADS 3.1 seems to offer lots of new features and a cool long-awaited feature of Web deployment, it just seems like the right time to get new people involved ā€“ but if this documentation is what they have to go on ā€¦

I opened a bug report for those doc issues a few months ago and it was marked as fixed. It looks like some of the new documentation may not have gone live yet.

Youā€™re right, though. Itā€™s off-putting to newcomers; the report came about when someone else on this forum ran squarely into issues caused by omitting those lines.

As for the style issues, I agree that it seems like the document is trying to be accessible to both non-technical and technical folks, and falling somewhere in the middle. I found it quite helpful when getting started but I skimmed past the Windows stuff and really enjoyed the next section - Programming Prolegomena - which is marked as optional.

Thereā€™s probably a space for new material targeting both types. Something like Learn TADS 3 The Hard Way for the one, and Aaron Reedā€™s Inform 7 book for the other. I7 has a better out-of-box experience, no question, and to a large extent that enables more accessible tutorials. The writer can assume a standard platform for all readers and skip all the window dressing.

(EDIT: Iā€™ve re-opened my ticket; the fix seems to have been lost in the shuffle.)

I hadnā€™t looked at that page in a long, long time, and I agree with you. I suspect Eric wrote that material quite early in the development of T3, and it does need to be revised in light of (a) how most people will be learning T3 today and (b) the more robust competition from I7.

If I were writing it today, Iā€™d make the top-level distinction, ā€œAre you using Windows or not?ā€ Because if you are, you can just install the whole Authorā€™s Kit and then launch Workbench. You never need to touch that other stuff. The other stuff is relevant only for Mac and Linux users.

Itā€™s like Christmas in December! :smiley: Seriously though, this is great news.

Systems that have been around a long time like TADS 3 always need some nip and tuck in their docs.

One thing that I think could help, which you donā€™t tend to see with IF systems compared to other programming languages for whatever reason, is the "getting started with " kind of blog post. I wouldnā€™t be surprised if there were literally millions of these posts floating around for languages like Python, Ruby, JavaScript, etcetera.

The two key characteristics of those posts is that theyā€™re short and aimed at the absolute beginner. As such almost anyone, including a TADS beginner, can write them. Theyā€™ve always been a big help to me getting started with a new thing.

edit to add: Just downloaded 3.1, and the user experience was really good, nice work!

Thatā€™s absolutely right. In terms of the life-span of T3 that part of the documentation is quite antediluvian. So far as I recall, itā€™s not even something I wrote myself; I think I just incorporated some of Mikeā€™s older documentation at that point for the purposes of the first official release.

I agree it probably does need revising. In fact Iā€™ve felt some discontent with Getting Started for a while, which is one reason I wrote Learning TADS 3 as an alternative. Quite a while back I posted on the old TADS 3 list suggesting a thorough re-write of the Getting Started guide might be needed, but at the time the suggestion was met with a distinct lack of enthusiasm. Since then Iā€™ve not had the time or energy to pursue it.

That might be a useful approach. I think the prior question is, how can creating a new game in TADS 3 be made as easy as possible for non-Windows users (especially non-Windows beginners)? As a Windows user with no experience of Mac or Unix (apart from briefly using Xenix at work in the early 90s) Iā€™m not familiar enough with non-Windows flavours of TADS 3 to know. Itā€™s a good idea to make it clear to Windows users that they should just use Workbench and ignore the rest (at least, for introductory purposes) but Iā€™d need input from non-Windows users on how best to present the material for them. Or would it be better to take the manual creation of a new game file out of Getting Started altogether, and stick in in the Technical Manual?

OS X and Linux development is essentially just FrobTADS + a text editor + a terminal.

Iā€™m quite happy with my setup now but I remember looking for a long time for an editor with decent syntax highlighting for TADS. Eventually I settled on gVim / MacVim. Thatā€™s not a choice that will work for everyone and itā€™s somewhat cruel as a recommendation for beginners, but it works really well as a T3 dev environment.

General best practice recommendations:

  • Name your makefile ā€˜Makefile.t3mā€™. One of the guides had me do something else and I had to supply a filename to t3make every time I recompiled. Nikos eventually enlightened me and that was a big quality of life boost. Now I can map to save & invoke the compiler and it works no matter what project Iā€™m editing.

  • Make a project specific header file first. Put the includes for adv3 and en_us in there. Then include only that header at the top of all your other source files. This makes it a lot easier to define macros and templates and libGlobal aliases down the road.

  • Have some sort of version-controlled store. Dropbox works pretty well at first; put your project files in a folder there and youā€™re set. That lets you recover an earlier version of a file from up to 30 days in the past. Eventually I moved to Fossil for source control.

One thing that might help would be a skeleton option that you could pass to t3make to get it to create a new project in a particular directory. Run "t3make -skel " and it creates a Makefile.t3m, .t, .h, and an obj/ subdirectory.

Authors could eventually customize that skeletal structure to taste but the defaults would be sensible and allow for a step-by-step guide without a lot of decision points.

Iā€™m a heavy vim user and am planning to use that for my TADS editing.

I donā€™t suppose youā€™ve done any work on a syntax highlighting/indenting plugin for vim that you could share?

I plan to create one, matching the colour highlighting and indenting rules provided by Workbench, but itā€™d be awesome if youā€™ve got something already.

vim supports syntax highlighting for TADS 3 out of the box. The coloring for anonymous functions is a bit off, but itā€™s never bothered me enough to try to fix it.

It handles indenting pretty well; the only hitch is if you use the normal object syntaxā€¦

foo: object
    bar = 1
;

ā€¦ then it wonā€™t auto-indent the first and last lines. You can use the alternate syntax instead:

foo: object {
    bar = 1
}

I find those extra braces kind of ugly so I just use the normal syntax and tab / backspace as needed.

noremap <F5> :up<CR>:!t3make<CR>

Thatā€™s the extent of my .vimrc customization for TADS 3. It lets me press F5 to save and build a project.

Oh yeah I should have just tried it!

Seems a little basic maybe, Iā€™m wondering if itā€™s just a copy of the C syntax highlighting. e.g. something: Topic is both in same colour, whereas Iā€™d expect class name to be different to object name.

But itā€™s definitely a start - Iā€™ll work on some improvements.

Iā€™ll let you know if I add anything else

Classes in T3 are just objects that start (by convention) with an uppercase letter, so I donā€™t think it makes sense to distinguish them.

For example, these are all legal object declarations.

something: Topic;
somethingElse: something;
class Nothing: something;