Suggestion: Help, man pages, and/or info pages #637
Comments
|
These are some good points, and some proper documentation is definitely needed. Let me at least address some of your concerns here:
None! Well, since it's a Qt program it does accept standard Qt command-line args such as
Some. Emacs-like cursor control is generally available (C-a to go to the beginning of the line, C-e to go to the end, C-d to delete a character, and so on). C-c and C-v are copy and paste, as you'd expect. C-, (control-comma) opens the config file in a text editor.
Not at the moment. This is actually supported on macOS, but not on Windows/Unix. Eventually I'd like to add such support to the Windows/Unix interface (they share the same one), and unify it with macOS. It's not a trivial task, though, since the launcher and the interpreters are completely separate. The launcher starts a new process to run the interpreters, and the interpreters have no concept of launching a game. Eventually it'll probably happen, if only because I'd love to retire the Mac-specific interface code and replace it with Qt. No time frame, though.
"change games" is covered above, but the other options are, unfortunately, interpreter-specific. Gargoyle makes use of third-party game interpreters, and itself only provides the user interface. Which is to say, how all this happens differs between various interpreters and even games in the same interpreter. With Z-machine games, for example, you can probably use the "SCRIPT" command to start a transcript, but nothing forces games to support it. Setting a random seed is also a function of the interpreter, and may not even be supported, depending on the interpreter. Now, all of this can be documented. But it's not quite as simple as it seems at first blush.
This is not possible. Gargoyle is inherently a graphical program. You can build all its interpreters against a terminal Glk implementation (see https://www.eblong.com/zarf/glk/; GlkTerm with widechar support is the one to choose). But that'll take some effort. Some day I'd like to produce a Gargoyle-like project for the terminal, but it doesn't exist yet. I will try to start jotting down stuff in the Wiki, to be consolidated, eventually, into a coherent document. That is indeed sorely missing from Gargoyle. If you're playing Z-machine games, there is a manpage for Bocfel, the interpreter used for Z-machine games: https://cspiegel.github.io/bocfel/bocfel.html |
|
If I understand correctly, [conceptually] Gargoyle itself is more of a front-end to other interpreters, by other people? (But packaged with/along-side Gargoyle?) I have seen recent posts (here) regarding the flushing of the standard output stream. which is why I thought that Gargoyle itself could operate as both a TUI and a GUI application. Perhaps, as a long-term goal, it could be made possible? My original purpose and thinking was in making an archive (mainly for the original Infocom games) of game solutions, which could be launched something like 'gargoyle zork1.z3 --script my-solution.txt' or similar, and have it output the results to do anything I want with. I would be happy to help when/where I can, both documentation and maybe some coding (although my coding skills are ancient, late 1990's style C/C -- but it seems to me many z-machine interps are from this era as well...). Let me know and maybe we can chat about it elsewhere without flooding the 'issues' section here. |
Yes, that's completely correct. To be more specific, Gargoyle includes its own Glk implementation, called garglk. Briefly, Glk is an API designed for interactive fiction. You can think of it as a portable I/O layer. Interpreters can target Glk instead of a specific OS, resulting in wide support across various platforms: there are Glk implementations for Unix, Windows, DOS, Android, etc, as well as specialized libraries like RemGlk. Gargoyle then packages a bunch of interpreters written by various authors, all of which use Glk, so get access to the Gargoyle UI.
That was in relation to transcripts, which are implemented in terms of C's standard I/O library.
This would be best served by building interpreters against RemGlk or cheapglk. There are some efforts to get Gargoyle's interpreters into a separate repository that's available to anybody who wants them, precisely so projects like you're describing can use them. See https://github.com/cspiegel/terps and https://github.com/cspiegel/interpreters. The latter is probably a better approach but not fully fleshed out yet. As it stands, if you're looking to start work on a game solutions archive, I'd start by picking a single interpreter and using cheapglk (or RemGlk, if you need the extras it supports). There's nothing in Gargoyle, apart from the interpreters themselves, which would be helpful, given that most of what Gargoyle provides itself is the Glk implementation. If you're on a Unix-like system, the following will download and build Bocfel (the Z-machine interpreter Gargoyle uses) against cheapglk: wget https://cspiegel.github.io/bocfel/downloads/bocfel-2.0.tar.gz
tar xfv bocfel-2.0.tar.gz
cd bocfel-2.0
wget https://www.eblong.com/zarf/glk/cheapglk-106.tar.gz
tar xfv cheapglk-106.tar.gz
(cd cheapglk && make -j`nproc`)
make GLK=cheapglk -j`nproc`You now have a This will seed the PRNG with a value of 1, read a command script from
This is as good a place as any to discuss documentation improvements. As an end-user who is asking for documentation, I'd say you're in a decent position to know what Gargoyle is missing. What was the biggest "hole", so to speak, in understanding Gargoyle, from your perspective? I have a hard time being able to determine levels of importance in missing documentation. But if you can see an obvious deficiency and are willing to work on it, I'll answer any questions you have and help get things into shape. You can add documents to the Wiki, and of course we can add things, such as man pages, to the repository. I do think one area of Gargoyle that could use help is in its configuration. Gargoyle is pretty configurable, but it's all done via a configuration file that's not necessarily very discoverable. I'm not sure how many people are even aware there is such a thing. And the config file itself is documented (via comments), but it may be useful to have a more comprehensive document explaining it. Thanks for wanting to make Gargoyle better! |
|
For the documentation... Start with what we have already brought up: What Gargoyle is, and just as importantly, what it is not. I installed it originally because it seemed to be the only multipurpose "interpreter" I could find for Linux -- Everything else I looked at seems to be aimed at other platforms (Mac, Win, Palm, etc.). But now that I understand that it is not an interpreter itself, but more of a front-end to others, I can better see how I can use it - and when I need to use something else, such as verifying and playback solutions. I have installed fixmo, frtoz, and zoom from my distro's repo, but they are all becoming outdated as well for Debian. I will be manually building locally when I can, but for now, the pre-built ones seem to work for the solutions archive purpose (but lack graphics for playng some games). And I am still learning about interps other than for z-machine. bocfel does seem like a good one for z-machines as well; I just have not had enough time at one sitting to build it locally and it is not in my distro's repo. For man pages, most of what has been said here should go in them. Command line options (which you said there are none, other than a game file to load), and let the user know that Gargoyle itself does not really provide an active UI once it passes the game off to the interp. For the config file... Let's start with a simple question: Where is it and what is it named? |
|
I'm going to address just one thing here initially:
There are multiple answers to this. First, it depends on the operating system. And once you've identified the operating system, it can also depend on other factors (mainly historical). The "best" way to determine the location is to start up a game and hit Control-comma (or Command-comma on Mac), to open up the config file in a text editor, then note where that is. That's kind of gnarly, to be sure... It'd probably be nice to have a command-line flag which provides this information, which would dovetail nicely with a man page, since now we'd actually have at least one flag to document. Gargoyle also allows games to override its settings (e.g. to set their own colors). Really, what Gargoyle does is find a list of all possible config files, loading settings from all, resolving conflicts by giving each config file a priority. Config files are also split into two categories, which are referred to as "user" and "non-user" config files. User config files are those which the user can reasonably be considered the user's "main" config file, and one that he'd want to edit. So it excludes game-specific config files as well as system-wide config files. With that not-at-all-confusing introduction, here's how user config files are searched, from lowest to highest priority: Windows:
Haiku:
All others (this is really Unix, including Mac):
In truth, on Mac, |
|
Yeah this is a big issue, i had no idea gargoyle is themable before today. When I used play 6 years ago, i inverted the colours in my entire os to get dark mode. Lack of documentation is very painful. |
|
This might be something I can help with, as well... even with coding. My thinking is to simplify all this config madness, from the users perspective. Place one master config file in a known and predictable location. In turn, it can be used to generate per-interp config files "on the fly" as needed (and monitor them for changes to write back to the master config). I would use XML, myself, since I have many tools and scripting languages which handle XML easily, and can pretty much import/export to anything else... Window's user used to .ini format? No problem. Comma Separated Values (CSV)? No problem. Unx style *.conf files? No problem. Original IBM-PCjr ROM BASIC byte code? Well... that one might be a problem... As for location... Typical software these days use some form of $HOME (likely with a additional directory appended, such as $HOME/.config on Linux). I am even pondering how much it would take to embed something like Lua, Python, or TCL in Gargoyle, any of which can extend Gargoyle, and possibly any interps, in many ways with little additional code. For example, embedding TCL brings with it the TK GUI graphics library -- Suddenly, Gargoyle and it's interps become full-fledged GUI apps, and can even play games with graphics and sound. TCL can also... Operate on Android devices (but not iOS :-/). Or offload the interps as TCL modules that can be loaded/unloaded dynamically (*.dll on Windows, *.so on Linux and Mac). How easy (or hard) any of this would be, I am not certain, as I am still learning how Gargoyle works, and have not looked at the code yet. |
From a user perspective, as long as they use Gargoyle to launch the editor, the config file location is immaterial. And there is a preferred location for config files, on a per-platform basis (the highest priority). If no config files exist, and the user asks to edit the config, then a pristine version (stored in the binary) is copied to the preferred location, and an editor opened. For backward compatibility, multiple config locations have to be honored. On Unix, As for per-interpreter configs, I don't know how tenable it is to have individual configuration files per interpreter, if that's the suggestion: most people, I suspect, will want all interpreters to look the same, and if there are any deviations, that's supported already in the main configuration file: you can override on a per-game or per-interpreter basis.
Now, I have been pondering the idea of a brand new config file format (while still having backward compatibility with the old ones), from a convenience (to me) perspective. The config file format now is ad hoc, though well-suited to editing by users. Ultimately, the right approach to configuration is probably a GUI, so the user doesn't have to ever touch a the config file, but with the option for manual config for those who want it.
Gargoyle is an implementation of the Glk API, and although it provides a few extensions for interpreters (largely for better Z-machine compatibility), there's no goal to go beyond implementing Glk.
Being anything beyond a Glk implementation is at odds with what Gargoyle is. Even if interpreters were extended to provide GUI support, there wouldn't be any authoring systems which support them, and few game authors who would use any newly-written authoring systems, since they'd be tied to Gargoyle. Games, which now also run on Lectrote, or via the web, for example, wouldn't run there anymore. Gargoyle, like Glk in general, is very firmly in the "1980s text adventure optional graphics optional sound" mold. Game authors don't target Gargoyle specifically, either: they write with a particular authoring system that produces a type of game file which can run on any number of systems (including Android, DOS, HP calculators, eInk readers, etc etc etc). Gargoyle is just one of many possible ways to run these games. Configuration absolutely does need some attention. It's just always been a lower priority for me. At some point, if I ever get the Mac interface fully switched over to Qt, then a built-in configuration UI would become feasible. |
|
That was not quite what I meant. :-) I mean, as I see it, Gargoyle is more or less akin to a GUI version of a terminal emulator (such as Konsole, on my Debian Linux machine). But there are some drawbacks, including not being a full-fledged GUI but rather a console-type TUI presenting in a GUI window. This presents a problem for authors, developers, interpreter implementations, et cetera: Presenting graphics and sound is not an (easily) viable option. (I am still learning about GLK, and how or even if GLK changes the scenario....) But to my thinking, what if Gargoyle can act as the "go-between" in these cases? Having a graphical output/window which can be drawn on, and handling dispatching audio to the sound system, etc. Of course, any of this is moot if such is completely beyond what you intended Gargoyle to be -- or too difficult to implement. I am just thinking as an end-user here; Testing solutions is just one of my purposes, but I also want to be able to play many games in the manner originally intended ("old shcool"). I can load many (if not all?) my old Infocom z-machine games in DosBox, but that presents other issues:
In most cases, the data files can be "extracted" from these games and played in more "modern" interpreters with access to more modern system facilities, if such interpreters exist. None of the ones available for Debian Linux can use graphics or sound, which was why I got excited to see Gargoyle in my upstream repository and gave it a try. I was previously using DosBox and things like the DOSZip interpreter or WinFrotz on my Windows virtual machine. But that requires constant switching between systems/emulators/virtual machines/interpreters/etc. I simply want a single, unified, consistent way to play different games, possibly translating certain functions as needed between the "presentation" (Gargoyle?) and the underlying interpreter, such as "<META> S" invoking a "save state" function/feature. I may not be wording all of these very clearly, of course. And as I learn about GLK, I wonder how much of this overlaps wih GLK itself. But it does seem to me that more often than not, the various components do not interoperate seemlessly from the end-user perspective. Maybe Gargoyle can lead the way towards making this happen and provide developer encouragement to provide more consistent interfacing/APIs in the interpeter back-ends... I.E., let the interpreter developers worry more about the interpreter internals, and not so much about how to present it to the user. While Gargoyle and it's ilk can worry more about how to present it to the user without worrying about how the interpreter(s) work internally. Of course, I may still be unclear myself on what Gargoyle is and is not, or what it's intended niche/purpose is. Which goes back to my original post regarding documenting such things. (Side note: Much of my old programming and development stems from working on Internet M.U.D.s, which where/are "client-server" based. While some servers did present their own clients, most of them did not. Users chose and used their own favorite client, such as zMud. tintin , etc, which handled all the "presentation" details, without regard to which MUD server they used/played on. Much of my thinking here is based on those concepts.) |
This is what Gargoyle is, within the framework of Glk. It includes both graphics and sound (see the game City of Secrets, for example, for graphics, or Ekphrasis for both graphics and sound). The Glk documentation describes Glk in great detail. Glulx is the VM/format designed by Andrew Plotkin (who also created Glk) meant to take full advantage of Glk, and most modern interpreter-based interactive fiction uses the Glulx format. To a rough approximation, it's a modern take on the Z-machine, removing a lot of its limitations and expanding support for graphics and sound. Glk doesn't provide a blank canvas to work with. You have to conform to its ideas about what graphical IF looks like. Version 6 Z-machine games (Arthur, Journey, Shogun, Zork Zero, from Infocom) are just incompatible with with Glk. The way graphics work is too different. But if you're willing to work within what Glk provides, you'll get multimedia support from Gargoyle.
Which games are you expecting to have graphics/sound, but don't? If it's any of the Infocom ones noted above, you're unfortunately out of luck with Gargoyle, and that will probably always be the case. The way Infocom did graphics is just too different from Glk to be feasible to shoehorn into it. I'm not against the idea of adding a new graphics mode to support the V6 Infocom games, but it would be a huge undertaking. At the moment, Windows Frotz via Wine is probably the best way to play these games on Linux (or other Unixes which Wine runs on).
Gargoyle is intended to be that unified game player that you're looking for. It has interpreters for lots of different formats, all via Glk, so they look and act roughly the same. There are individual interpreters available in some cases (QTads and Hugor specifically) which can provide a better experience because they are tailored for their specific formats. Since Gargoyle uses Glk, interpreters must be adapted to work with Glk. For the most part this is fine, but more multimedia-based systems such as TADS and Hugo don't mesh perfectly. Glulx is the exception because it's designed for Glk. Things like a unified save function aren't really feasible. Glk does have functions to prompt the user for a save file, so all interpreters will at least look the same when saving/restoring, but there's just no way to hook into interpreters to do a sort of out-of-band save. For VM-based games, for example, games are just effectively programs running on a computer, and are able to control when and how saving is done. It's not some external operation. And since the games are really just computer programs, they don't even need to provide a save function. You can hack around it in interpreters, maybe, but not in a completely useful way. Bocfel (the Z-machine interpreter in Gargoyle) does support out-of-game saving, via the interpreter-provided Basically, you get games that all look and act somewhat different in their semantics, but have a unified feel when it comes to the interface with the operating system: same fonts, colors, save dialogs, etc.
At this point in time, if you're writing VM-based/parser-based interactive fiction and you want it to work with Gargoyle, you probably ought to be using Glulx. That's the best way to get consistent output since Glulx maps perfectly to Glk. The downside to a unified player is that you have to provide some common denominator, and systems which are still under some sort of development (Alan, Adrift) aren't targeting Glk, they're targeting their own runners. A lot of what they provide will work with Glk/Gargoyle, but not all of it. Whether that's a price you're willing to pay for a single game player is up to you.
This is, in fact, precisely how it works. The "original" code in Gargoyle is just a Glk implementation. It knows nothing about interpreters. Gargoyle then bundles third-party interpreters that use Glk. You could take any of the interpreters bundled with Gargoyle and build them against any other Glk implementation. If there are things that would be useful for new interpreters, and which fit the design goals of Glk, you can recommend them as features to Andrew Plotkin. Glk is still very much alive and in development. I think Gargoyle is what you want, it just may not be quite as much as you want, so to speak. If there are ways to improve things without straying from Glk, I've got nothing against improvements: and we do have some extensions to Glk to add quality of life improvements, but mainly for the Z-machine (text styling and the annoying "preloaded" input it supports). |
|
Unfortunately, the Infocom games you mentioned were the ones I was trying, so as you stated, I may be out of luck and need to do as you said (However, I cannot seem to get Winfrotz to work under Wine, only under a full Windows VM via VirtualBox). I have not tired many other IF games besides z-machine ones, yet, as my own focus right now is on Infocom game collections, but I will be expanding on others in the future. You may also be correct that some of my idea/suggestions might be better sent to GLK development. I am still figuring a lo of things out -- Back to documentation, perhaps this is something that can be included. To explain... Are you familiar with the 7-layer OSI networking model? I am thinking in similar lines, structurally. Gargoyle sits at the top, same as FireFox, Chrome, or Edge, sit at the top of the TCP/IP stack. None of those worry, or care, about which NIC you physically have, which ISP you use, or which web server you connect to (or even which OS you use, in many cases). GLK, as I see it right now, is akin to the TCP/IP stack and the HTTP(S)/HTML protocols. And the various game engines/interpreters are akin to web servers. Games are simply like web pages; collections of data and resources (graphics and sounds). Each part only has to "worry" about how it is "connected" to the proper component(s), and conform to the protocol(s) in use. In this case, there is the added "complication" of there being a client-server model along side the rest. From the end users perspective, they do not care about most of this. they just see it all as "the web". They want to view a web page, they go to the URL which provides it. They do not care if it is an Apache2 or NGINX web server providing the page. And so on. Another example of my thinking is databases. Most DBMS systems (rBase, dBase, MS-JET, MySQL, MariaDB, etc.) provide db-system specific libraries to access and manipulate the database itself. But they also provide another method: SQL, a generalized and common language for database access, independent of both the database back-end and the application front-end that is in use by the user. Those two examples provide a basic model of "how things work", and are common and generic enough that most users can understand them. Gargoyle's documentation can include such things. Give an overview of the entire system and then show where Gargoyle sits within the system. You will not need to provide much documentation about things like GLK or the interpreters other than to note which are in use/available (and let them provide their own more detailed documentation, as needed). This would better help the user understand the system as a whole, and when to dig deeper in to Gargoyle documentation -- or to find and dig deeper in to other documentation (such as GLK) for what they want/how to do something. Some other notes: Regarding saves, I was specific in saying "save state" and not "save game" -- save the state of the interpreter (much like Frotz' "/save" command versus the game's own "save" ((without the "/" in front)) feature--if present) by serializing what is needed to save/restore it. This is most likely something I need to talk to GLK about, however -- Add specifications for in-band and out-of-band communication between the user and the game engines/interpreters. Something like, for example, GLK can get input from the user, "move north" (or just "n", etc.), and that can be passed to the game "in-band". While "out-of-band" can include things like a "user wishes to save and exit" event, which can signal the game (engine/interp) to generate and return a serialization, which, in turn, can be saved "locally". I will continue to learn about GLK, and likely submit such suggestions there where appropriate. Regarding media (graphics and sound), that may also be a GLK thing. Set up/define a basic "virtual machine" style core to execute interpreters within. Various platforms (Apple II series, Commodore C64/128/Amiga, IBM PC-compatibles, etc.) often use specific ways to render the display (often memory mapped display frames) or produce sound (a bit more complex than display). The virtual machine can translate these between the "Guest" and "Host". Some interpreters already do this sort of thing internally, while others may require a lot of code refactoring. And some -- or much? -- of this is already covered by GLK/Glulx. (I still have not had much time to dig more in to that side.) I had something else I waned to add here, but it is now after midnight here and my brain is sleepy and I work tomorrow. Good night. |
I originally started writing Bocfel in part to have proper V6 support on Linux, so maybe some day I'll get back to that goal... but it'd require writing an entire new interface, since I can't use Glk for it, and that would be a whole lot of work. I'd like for it to happen but it hasn't been a priority, unfortunately.
Gargoyle has always presupposed some knowledge about interpreters, although it has never hidden the fact that different interpreters are used. But the landscape is different today than it was back when Gargoyle started, and I agree that a brief explanation of what Gargoyle really is is probably a useful thing. As is often the case, though, documentation lags behind code.
If you're specifically talking about autosaving when the user quits, there's good news and bad news. Some good news is that Andrew Plotkin has tackled this problem and documented it: Interpreter-Managed Saves in Glulx. The bad news here is that it will require a huge amount of work in Gargoyle to ensure the current state of play is serialized properly. More bad news is that interpreters will need to be modified to support this, although it looks like the modifications wouldn't be too invasive, and glulxe already supports it. If somebody wants to add serialization (and deserialization!) of Gargoyle's data structures, I wouldn't say no to it, but I'm not sure I want to be doing it myself any time soon. One silver lining is this, though: Bocfel, the Z-machine interpreter, supports autosaving independent of Glk. It's disabled by default, but if you add
Glk supports graphics and sound, without specifying the details of supported formats, leaving it up to implementations. Most implementations use Blorb, including Gargoyle. This uses JPEG and PNG for graphics, and AIFF, Ogg Vorbis, and tracker modules (MOD, IT, XM, S3M) for sound. It's up to the interpreter to provide things in a format that is supported by Gargoyle. Glk also supports graphics windows, onto which arbitrary graphics can be drawn. The Magnetic Scrolls interpreter does this, for example, to support the original graphics, while Bocfel requires Blorb files (i.e. it won't interpret Infocom's original graphics files). |
There seems to be lack of documentation and help for actually running IF games. What command line arguments does it take? Any keyboard shortcuts? Under X11, can I load a different game (there seems to be no menu bar or right click context menu)? I cannot figure out how to do anything such as save a transcript of my game, change games, execute special commands/actions (such as setting the initial random number seed, etc).
I cannot even figure out how to run Gargoyle in text only (TUI) mode, instead of X11 GUI.
The text was updated successfully, but these errors were encountered: