Time to get excited!
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! 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;