thanks eric!!
THANK YOU ERIC !!!
now the examples are definitively perfect !!
I warmly recommend adding this to the docs bundled with a3Lite.
Happy regards from Italy,
dott. Piergiorgio.
@Piergiorgio_d_errico
I was wondering whether to do that, so your vote in favour should probably help me make up my mind to do so.
First of all, thank you everyone working on the documentation and hosting, and making things more accessible to new TADS users.
I skimmed through the thread and I think there’s one idea that I didn’t see (or I missed it): adding all of the adv3lite-related periplus links to the adv3lite documentation source, so the whole thing can be downloaded and accessed locally.
The repo I use for my TADS work has the entire adv3lite source (that I periodically update) and I have local links to the bookshelf. I started doing this because I noticed that the tads.org site started losing some content.
As for helping people start with TADS 3 / adv3lite, here are the links from periplus that I find the most helpful (and are hard to get to in the bookshelf):
- vocab string parsing
- Action life cycle (I find Action Results misleading)
- Action reference
- Thing
- Room
- Procedural code
I used the periplus links, but they should be links to the latest version of adv3lite.
My suggestion is to add these links as shortcuts in the Table of Contents of all the adv3lite books, something like this:
Additionally, I think the TADS 3 system manual should be merged into the adv3lite documentation and updated. I find it an absolutely fantastic resource but the Table of Contents makes it very hard to find certain things. There’s no definitive documentation of keywords, the procedural programming topic is almost an afterthought and many of the topics (while useful) are hard to reach (because they’re hidden inside a somewhat-related topic in the TOC).
Like Eric mentioned earlier in the thread, when I started with TADS (first with adv3, then adv3lite), the problem for me wasn’t the lack of documentation, but how to find what I need. Even now I struggle with finding things.
The Task Topical Index in the Library Manual is intended to provide some of that functionality, Maybe it could be improved, but it is there.
EDIT:
I’m not 100% sure about this. It wouldn’t even be possible (or desirable) to do this for the adv3Lite Library Reference Manual, and it would probably be more of a distraction than a help in the tutorial documents, which really only leaves the Library Manual. A question then is how much agreement we could secure on which quick links might be most helpful, given that having too many of them would surely be self-defeating. For example, both Room and Thing feature near the top of the Library Manual TOC; wouldn’t quick links to them on the same page be somewhat redundant?
I can see that including the TADS 3 System Manual in the other adv3Lite documentation might be beneficial. I’m less sure I’d want to take on the task of updating it - especially unaided. I’m probably not the best person to do so in any case, since I’ve become so accustomed to working with the System Manual over the last 20+ years that I don’t experience the same difficulty in finding my way around it and so wouldn’t see how to make it more accessible.
FURTHER EDIT
I’ve now added the System Manual to the adv3Lite docs and added Quick Link panels to the System Manual and the Library Manual table of contents pages.
That’s great. I now link to them in a couple of places, but I was wondering whether you might to link to them from TADS 3 Resources (and also to the TADS 3/adv docs)? That would help people find them.
I’m currently planning to release version 2.2 of adv3Lite in early March, so that’s when you’d need to update your site’s copy of the adv3Lite docs again.
I’ll try!
Wow, thank you, much appreciated. 
By the time I got around to responding to your post, you already added the manual. Both impressive and very kind.
I’d only suggest removing the yellow background color - in my screenshot the yellow background wasn’t intended as a style choice, just as a means of highlight. I created a PR into your repo to remove it, but thank you for adding the section. I think the links there are actually useful as the most basic topics for someone new to TADS.
I’d be willing to offer some changes (the content is already very good in the System Manual, but I could add some minor enhancements and maybe some ways to organize parts of it). I’d be happy to post the PR-s here as well, so that others could review it to make it better. I don’t think I’m any kind of an expert on the TADS internals, but I’ve been doing programming for a while.
Yes, I see your point. Maybe a few quick links in the Library Manual would be helpful - others should speak up to see what they found hard to get to as they started with TADS.
I think adding links to the top bar (without the yellow background ) to all books would be helpful. There’s rarely a time when I don’t have the Tutorial, the Reference, the Library Manual and the System Manual all open as I work on TADS, and I very frequently have to navigate back to the bookshelf page. Having those top links would definitely cut down on the back-and-forth. This is just my perspective, though.
Lol, I had no idea these existed and I’ve been on that TOC page many times. I think this is the problem with TOC-s in general (nothing specific to the TADS docs) - it’s a long list of links and one has to actively read through it to find each topic. There are so many of them that I find it real easy to miss things.
I’d definitely add both of those to every page header (in all the books). If it’s a lot of work, I’d be happy to help with that.
Now pulled. I’ll make the same change to the Library Manual TOC.
That would be great, thanks.
I already added some.
I tend to have multiple books open (Library Manual, System Manual, Library Reference Manual - plus any docs I’m updating) when I’m working on TADS too. They’re open in different tabs in my browser so I seldom need to go back to the Bookshelf. I’d want to think about this some more.
with all the prompt updates you make I keep wondering how to host the docs you have on github as-is, just directly from your repo. if people want to noodle on this, please help
Those may not be the best versions of the docs to host, insofar as the updates on GitHub tend to be work in progress between releases rather than released versions (the two only coincide directly after a release). I assume most users would rather wait for a release rather than keep downloading the latest update from my GitHub repo, so the most useful version of the docs to have online will, for most people, be the version relating to the latest release rather than the GitHub repo version.
If you link to adv3lite/docs/index.htm at master · EricEve/adv3lite · GitHub, what you get is the raw HTML, not the rendered HTML. But the only people likely to be reading the docs on the repo will be people who’ve downloaded the latest repo version and so will have a copy of the docs for themselves.
I suppose one possible exception might be people who want to see the latest changelog on GutHub - adv3lite/docs/manual/changelog.htm at master · EricEve/adv3lite · GitHub - so they can see what’s coming and decide if they want to grab the latest version from the repo or wait for the next release. Although they’ll again see the raw HTML rather than the rendered HTML, they’d probably be able to make out the contents of the change log easily enough.
Fair point, I’m just really struggling with the whole thing. Is the only way really just to download the docs per every release and rehost them?
I think so, not least because it’s the released versions that are the ones to link to. I tend not to do more than three releases in a year, though, so it shouldn’t be too often, and I’d have thought it was just a matter of copying the new docs to the same location as the old one - your link should still work because it will still point to a file in the same place with the same name.
Good afternoon,
I have made a fork of your TADS 3 resource repository to experiment with.
I have have migrated the antique Far Out Science web site to a new server. What a relief. I had some very old embedded code that made it difficult.
I will definitely keep Eric’s documentation on FOS up to date.
It is SO nice of him to develop and maintain Adv3Lite. That is the lifeblood of TADS. !!!
The idea of a wiki page TADS 3 via github looks good.
Thank you, Jeff
Thanks both of you!! And def agree. Eric updating Adv3Lite so frequently is a blessing
I forked the github page to use for experimentation.
Here is a link to setting up the a wiki for the page. It is pretty straight forward.
PS. This is just a rough draft for demo purposes. If interested, a very enhanced version could be developed on the original repository. (A wiki could also be developed easily on a commercial server.)
I once did a diagram of the T3 library with Eric Eve. Like diagramming a sentence, a visual reference rather than just a written one. Unfortunately t is gone.
I am going to start, not with Inform 6, but with T3. A rewrite of an existing game. If I come up with sample code, will share. I did not pay my web site and lost my Inform 6 primer, just the first page remains. I was planning tto relearn it with my own primer. Heh.
With T3, Mark Roberts threw the kitchen sink in, all preconstructed stuff, which actually makes iit harder to learn. Like back when there was a word processor called Multimate, it would do everythihng, but you could use function keys, menus and shortcuts, there were three ways to do anything. Great word processor but hard to learn. And you could actually open a code window that show you the basic formatting, letting you add and delete. Things like {pagination}. It was cool, but many “secretaries” could not learn it. I took a class on it. I was a temp secretary between programming jobs.
Don’t know if this helps, not sure what links are still active…
Oddly my word press pages have stayed up all these years, here is one on T3…
Marnie Parker aka that Doe Person (old timer, creator of the IF Art Show and other things)
Might you want to consider using adv3Lite? Just a thought.
I’ve been (re)absorbing a lot of TADS docs over the last few weeks and feel like some high-level diagrams/cheatsheets would be helpful. Are there PDFs like the adv3 quickrefs but for adv3lite?
Also I wonder if an adv3lite-only version of the Library Reference Manual, or even two, one just for adv3lite and one for core TADS, would make finding things easier.
You could create a latest_stable branch that syncs with master whenever you tag a release, and then the doc workflow could pull from that.