I wanna make a TADS 3 wiki / consolidate resources!

Authoring TADS
, , ,
1

As yall are probably well-aware, the TADS 3 documentation is kind of scattered, and makes it hard to get into the language. Me, @\inventor200, and @\alexispurslane tried for a bit to make a TADS 3 website that was nice and shiney, but it was hard to do this with just 3 people with limited energy and time, and ultimately didn’t come to fruition.

As this forum has has helpfully informed me when making this post, at least a few attempts have been made through the years to make a collaborative TADS wiki that people can edit and add to.

These have been varyingly successful as resources: I think @jnelson’s site is incredibly useful (the peripluses especially!) but I’m not sure if it’s a wiki proper, or is just Jim’s maintained site. The decade-old post seemed to hit a hiccup when trying to use MediaWiki (which is pretty complex to set up) and the domain no longer works. Of course, there’s the original TADS 3 bookshelf and @Eric_Eve’s resources for Adv3lite, but these aren’t wikis, but the labor of a few dedicated people writing a whole bunch. Also, none of them have search bars…

I think that a wiki would probably be the better approach in the end than a newb (me) trying to comb through the docs all by themselves to discover things others already discovered or innovated, or the people who already wrote a bunch trying to update their documentation even more alone. I want to make a try at it myself (with the help of yall!) and hopefully not fail immediately.

So, what would yall TADS 3-lovers or would-be-lovers like from a centralised wiki at this point? What would be most useful for everyone as a resource? What wiki software do people prefer, if they prefer any? If you’re not sure of the differences (I sure am not!), what are the criteria you would need the site to meet for you to be able to participate in writing docs or using the website (for ex, WYSIWYG formatting? markdown formatting? some level of low or high complexity? etc)

I’ve bought the domain tads3 . wiki btw, for $3. It’s more expensive in the future, so if this gets off the ground I’d like to apply for an IFTF grant to continue.

(ETA: Jim, if we all prefer, I could even just have the URL redirect to your page but only if people think that GitHub is the best place to host this haha. I think it has a high bar for participation, myself.)

Put resources here! I’ll link them on the website.

12 Likes
2

Cool, I hope this moves forward!

3 Likes
3

Would you be up for contributing? If so, what would you need to be able to?

3 Likes
4

A simple alternative to a full wiki would be a static site hosted on GitHub Pages. It would allow you to write articles in Markdown, and have links between pages like any wiki, you just couldn’t edit it on the site, instead you’d need to edit it in git or on GitHub. But it could be a way to get started quickly, and if you decided to switch to a full wiki you could do that later. GitHub Pages does support custom domains so you could use tads.wiki. It could also be part of the unofficial TADS collective: TADS Interactive Fiction · GitHub

5 Likes
5

Ooh I didn’t know that collective was a thing! I would be happy to make a static site generator in Jekyll, which I’m familiar with, but I dunno how many people who aren’t me would update it with the whole “need to make an article by submitting a pull request” thing. Part of the appeal of wikis, TMU, is the low bar for editing.

5 Likes
6

You could use IFWiki (www.ifwiki.org) as long as you’re happy for the text to belong to everyone. Unless you’re worried about running into this problem:

2 Likes
7

oh, I don’t mind that no, I think that TADS is niche enough that’s unlikely to happen (or that often). Would yall mind just having a section of the site for TADS documentation and resources?? There’s. A lot.

eta: are there wiki portals in IFWiki like there are in Wikipedia? I’d feel better starting there if there were a specific little corner for TADS and all its pages/documentation (maybe that could be linked to the domain I bought, but that’s not as huge a deal)

3 Likes
8

There are (is?) a variety of TADS pages already: see Search results for "TADS" - IFWiki and, for example, Switch statement (TADS) - IFWiki.

It would be a problem if you want to copy and paste existing material (rather than link to it or use brief quotations). But if you want to use it as a place for something new then it would fit all right.

2 Likes
9

Hmm, I wish I’d known these existed. That’s the problem, everything’s scattered! I think an updated site with an obvious URL would be nice rather than people’s personal githubs and buried in the IFWiki. Plus what if I wanted to re-organize existing documentation instead of write it wholecloth?

I guess if no one else has the spoons to contribute to a new site, then boosting the vis of the IFWiki resources would be better than nothing. I don’t want to be the ““let’s make one standard to consolidate 13 standards” and now there’s 14 standards” guy

1 Like
10

Of course, I 1000% concur and agree (and I’m available… perhaps…)

my opinion that is best something like tads. ifwiki. org (that is, a subdomain of ifwiki)

side point, the periplus has inspired the task topical guide of adv3lite library manual, so perhaps the periplus concept is the best one for organising and systematising (sp?) the TADS documentation.

Best regards from Italy,
dott. Piergiorgio.

1 Like
11

ykno, if there were a search bar in the peripluses @jnelson maybe a lot of this new effort would be moot haha. you did a good job there!

the offer still stands re: the url, I only got it cuz of a huge sale :slight_smile:

or would this be possible @Jonathan ? :thinking: (or…both?? who knows)

12

Nope! :slight_smile: But if you would like to add to IFWiki I’m sure everybody would welcome it.

(On second thoughts, if you’d like to pursue it then it would probably be a decision for a big cheese in the IFTF rather than just me replying to a forum message.)

13

Maybe speak to the people running the existing things (I don’t think I’ve used TADS so don’t know) to see what you can come up with together.

Edit: I might have used TADS on the Amiga in the early 90s though I’m not entirely sure!

14

I think at minimum it needs an easy way to include code that recognises TADS 3. It’d also be important to clearly distinguish adv3 from adv3lite, and I guess generic TADS 3.

I contributed to Jim’s cookbook (and still want to) and I don’t think if it were a wiki that you’d get a lot more content. But maybe it might?

I’m working in very slow time to make my own alternative to Eric Eve’s tutorials, but that might just be a me project.

1 Like
15

The syntaxhighlight tag which we now have on IFWiki apparently understands TADS 3 (and Inform too).

The existing TADS pages have had their code formatted into wikitext by hand which looks like it must have been a torturous process.

1 Like
16

looks like IFWiki/MediaWiki’s extension uses uses pygments which does have support for TADS 3 syntax highlighting, and could easily be implemented for a new website, if people actually want one…

1 Like
17

Glad to see renewed interest in the topic of improving TADS 3 documentation and developer help.

I built two separate sites some time back:

GitHub’s wiki operates much like any other wiki, but editing is limited to GitHub accounts with edit perms for the project. I don’t believe the cookbook gets much traffic.

The periplus pages are built using a crude PHP script I slapped together that generates static HTML hosted in frames. It’s not pretty, even by 1998’s standards, but works well enough. I got tremendous value out of the adv3Lite periplus while developing Cain and Cognomen.

Note that I’ve not updated the adv3Lite periplus for the latest versions of adv3Lite. This is partly laziness, and partly because I’m still on adv3Lite 1.5 and dragging my heels to upgrade.

Both sites are hosted in the same repo.

If there’s some final decision that that’s the best call, I’m fine with it, but do hope the needle can be moved forward.

GitHub does make a high bar for participation. When I started, I looked at several low-cost, ad-free wiki solutions out there, and was unimpressed. I also considered hosting the wiki on my personal web site, but felt that was even less “welcoming,” esp. if the wiki were to take off and have several active maintainers. (Dare to dream!)

Also, because the cookbook is in a GitHub repo, it was trivial to host example source files people could download directly and compile.

I also worried about producing something that disappears one day because I—or someone else—fails to pay a bill. For better or worse, a GitHub repo is free, and GitHub appears to be around for a long time. (Of course, GH might some day require free repos to start paying a fee. No certainties in this world.)

So I went with a technology that was zero-cost, ad-free, easy (for me, at least) to use, and produced a relatively useful result. I figured that, if the wiki were to gain in popularity, I could reconsider hosting it in a more suitable place.

Yes! That’s why I made the periplus—not to rewrite the docs, but reorganize them by subject matter.

If the class libraries ever update—as has happened with adv3Lite—I don’t need to rewrite a lot of pages due to the changes. I merely rebuild the periplus with my script, and ta-da.

It’s all static HTML. A search solution might not be hard to add at all.

…

Ok, those are my responses. Here’s a few points I’d like to add:

I’m not protective of the two sites I built—if someone wants to take them over, host them elsewhere, or build something better, I welcome it.

I’m also not wed to the code I wrote to build the peripluses—it was throwaway, ends-justifies-the-means programming. If someone wants to build a better script, again, I support that.

Of the two (cookbook & periplus), I think the periplus has higher value.

The weary mantra that TADS doesn’t have enough documentation is kind of misleading. Between MJR and Eric Eve, TADS has a great deal of documentation, technical and tutorial, but it’s spread over several resources. It’s hard to locate the specific answer to a specific question a programmer may have. (To this day, I can’t explain off the top of my head the difference between the System Manual and the Technical Manual without looking at their TOC, yet both have information most coders will need at some point.)

That, plus the class library docs cover all classes in the library, when realistically only about 35-40% of those classes are of interest to a game developer.

Perhaps the solution is a better periplus: An extensible wiki organized by subject matter that links or hosts the technical docs alongside commentary on how to best use it.

Or, a true wiki, publicly editable, that organically grows by topics.

…

With that, one cautionary point:

When I started the cookbook, I was coding to adv3. Later, I moved to adv3Lite. I attempted on the cookbook wiki to support both.

That’s a tough thing to do, though. Even common problems can require drastically different steps in each library.

Since so much of the game dev process is geared toward the library, and not the language, this split in the community will make practical documentation efforts that much harder.

I don’t have a good solution for this. It’s something to keep in mind.

…

Unfortunately, I am right now a burnt match and cannot offer tangible assistance. I fully support whatever path is chosen. When I get my act together, I hope I can contribute in some measure.

10 Likes
18

Of course, I thank JN for his insights;

For me, the best top level structure remains the bookshelf, the ideal being merging the two bookshelves, the peripluses and the cookbook in one shelf, usable both online and offline (I use day-to-day my offline copy of the bookshelves and the periplus, all three in this browser’s bookmark tab)

The main issue in this plan is that the TADS bookshelf’s rights are held by a MIA author, and this is a technical, not legal issue (said copyright allows linking from other pages, as done by Adv3Lite bookshelf, and linking between offline copies the two is not only trivial, but also well explained in A3Lite bookshelf)

I think that Eric and Jim has no issues in allowing the merging together in an expanded bookshelf adv3Lite bookshelf, the periplus and the cookbook. This should be a good “phase 1”.

Of course, the Tads/adv3 bookshelf can be integrated in this expanded bookshelf (unmodified, see below on this point) as already done by Eric for the TADS system manual.

Of course, at this point, we need to differentiate what document is what: the best solution is a differentiating icon (IMVHO best placed after the title) between the three main categories, TADS, Adv3 and Adv3Lite.

Now, on the wiki… Everyone know the goods and bads of a publicily-editable wiki, and I guess that the best means of integrating a wiki in a more or less static bookshelf is a “select snapshot”, the “select” part meaning that the snapshot is edited, correcting errors, mistakes (often involving wikilinks…) and vandalisms, of course :wink: and the references and like to the rest of the bookshelf integrated in it.

Now, the core issue: the MIA status of Roberts. the best solution is a detective work, aimed at finding him, explaining the situation, and gently but firmly inviting him to relicense under a more permissible, derivative-work allowed, license.
As fallback, there’s available the “AdvSys solution”, that is, releasing the improvements to the TADS & Adv3 parts of the bookshelf in form of diff files, admittely a gray-zone expedient.

Phase 2 of course, is improving and more important, streamlining and integrating the entire corpus in a more organised fashion, and expanding it.

on expansion, the most important thing to do is smoothing the learning curve, and expanding the learning options; an adv3Lite version of Getting Started and the Tour guide is my first-of-the list, followed by an HTML porting of both Learning Tads3

I think that Eric will be happy in delivering an adv3Lite-based version of his contribuitions to the technical manual; the latter ought to be “dual”, referencing to both Adv3 and adv3Lite.

I understand that I have written more a “roadsketch” than a “roadmap”, but this IS a contribuition to the debate to be discussed and eventually refined and perfected.

Last but not least, I hereby formally declare GPL (code) and FDPL (text) all my posts here giving tricks & tips in this forum, so no need to ask me about inserting them in the cookbook :slight_smile:

Best regards from Italy,
dott. Piergiorgio.

2 Likes
19

hey, I’m down for this!

maybe we could all add to the periplus section of your repo, what do you think? at ths very least starting with a search bar :wink:

alternatively if it’s a lot to be responsible for incorporating pull requests, you could add others to your repo contributors. or if I could fork your repo and go from there (maybe in @Dannii’s TADS 3 repo collective).

if we keep it on github pages, then even if a url (like the one I bought) collapses, I think people can still find the github pages site. for extra safegurading, potentially we could put the domain url in the hands of the IFTF if it takes off.

I do agree as both of you pointed out that there’s a buttload of documentation already, that’s why I said “scattered” not “sparse”, so the wiki ideal I had in mind was basically to reorganize existing documentation, and add on, more comprehensively. I def agree with this idea of incorporating everything (separating adv3, adv3lite, and pure TADS 3 clearly).

I think the peripluses structure + search bar are preferred for me-- I think everything in the existing structure could be improved with a search bar tbh. And consider, there could even be two options for organization, the periplus formatting & the bookshelves, except all in one place.

The status of Roberts’ TADS bookshelves means they’ll have to be untouched content-wise, but I think the adv3 periplus does a good job at that approach (which could of course be added onto)

5 Likes
20

An adv3Lite equivalent of Getting Started already exists; it’s the adv3Lite Tutorial. I don’t think duplicating the function of the adv3Lite tutorial by adding an exact adv3Lite port of Getting Started would help much.

Providing an exact adv3Lite port of the TADS 3 Tour Guide is not a job I’m willing to take on. In any case, an exact port might not be entirely appropriate for a number of reasons: (1) the two libraries are different and what should be covered in relation to one isn’t necessarily what should be covered in the other; (2) The TADS 3 Tour Guide was written about 20 years ago and could probably be improved if it were to be rewritten today; some people have commented that its examples are sometimes idiosyncratic and inappropriate. (3) Having yet another piece of TADS 3/adv3Lite documentation may simply compound the problem of proliferation that some people are already concerned above.

If there were demonstrable demand for and adv3Lite Tour Guide and one or more volunteers willing to work in it, then I might be interesting in helping on such a project.

But the TADS 3 Technical Manual isn’t readily editable, for reasons already discussed in this thread. And most of the stuff that’s adv3-specific in the Technical Manual is either irrelevant to adv3Lite (e.g. manipulating the transcript) or else already covered in the adv3Lite Library Manual (so producing an adv3Lite Technical Manual would largely duplicate existing material).

I get the impression that the main problem most people are trying to address here is not shortage of documentation but the difficulty of locating what one is looking for in the existing documentation. So what may be needed is not primarily more documentation but a way of helping people find their way around what already exists.

That’s not to discourage anyone from trying to provide something (e.g. a Recipe Book or Inform 7 style manual) that they may feel would fill a gap.

BTW, are people aware of Home · EricEve/adv3lite Wiki · GitHub?

5 Likes