Talk:Commands

Peer Review

The document needs peer review again. I rewrote a few sections of it to account for some of Jaxen's feedback related to subshells; I basically found a way to explain it without going into the dregs of the details. It might become apparent tomorrow how I can more properly integrate that concept. I'm open to suggestions. -- Alkani 2017-08-14 13:53:44

Jaxen's Feedback (From Page Mail on 2017-08-14

Lepus' Feedback

My immediate feedback is that it's comprehensive but may be abstruse for a newcomer. It can serve well as a in-depth view into the commands, but a more tutorial focus might be easier for people to take in--one that even includes an explanation of the common UI (use muck.spindizzy.org screenshots for this). For example, a newcomer needs to know how to speak and pose and look at things; until they know how to do these things a deeper understanding of the notions of keywords and parameters is not especially useful to them. Another facet of this experience that should be touched upon is not just input but output: Breakdown some text in the window into room description, exits/contents, and conversation/actions. This seems obvious but it is 2017.

This could exist as the first part of the Commands page before a deeper dive into the axioms involved. Now, perhaps that is beyond the scope of the Commands page as you envision it. If so, that's fine. But then I'd like to see a more example/run-through oriented getting started page which links to the Commands page for further details.

That being said: The contents of the commands page is excellent in its clarity and comprehensiveness. Well-done.

---Lepus


I'd like to take a pass at tightening up the language and flow of this page (e.g. I plan to move the distinction of built-in versus installed commands into later in the document when the concepts make sense in context), but I don't want to do so in such a way that will obfuscate the purpose. Can you describe the goals/anti-goals you're trying to achieve with this page? -- Lepus 2017-08-14 17:09:54


Did some revisement. Notes below. Feel free to revert anything you don't like in the changes. I'm still not sold on the purpose of the document: It documents, to be sure, some information about commands on the MUCK. But while presenting itself in a very technical language, it also obscures a bit with metaphor instead. The result is the document's first few sections feel at times like it isn't terribly useful for a newcomer (because it's about how commands work rather than how to use them or how to get help) or for a veteran (because it doesn't actually tell you how commands are actually set up in the sense of actions, links, programs, MUF, etc.). The most useful information is probably the information on the globals list and getting help.

Feedback:

1) Iut the 'There are two types of commands available on the SpinDizzy MUCK: built-in commands and global commands.' text since it shows up later.

2) "For example, in the Windows operating system, Notepad (notepad.exe), Task Manager (taskmgr.exe), and Command Prompt (cmd.exe) are basic programs included as part of the default install. In Linux and BSD distributions, and many flavors of UNIX (such as HPUX or AIX), your system distribution is likely to be installed with Stream Editor (sed), and a command line processor such as Korn Shell (ksh) or Bourne Again Shell (bash)."

This is actually not a great metaphor; really things like notepad.exe are not 'built-in'. And their muck equivalents (e.g. lsedit) aren't builtin either. The builtin commands are implemented in C code inside the FB server itself. The operating system equivalent would be parts of the kernel itself. Whereas notepad.exe is a userland program built on top of system calls; the MUCK equivalent is MUF programs invoking primitives.

notepad.exe is the same as notepad++.exe in their relation to the OS technically. The difference is that one of them is part of a standards Windows installation, similar to a minimum DB install on FB.

3) 'After the program has finished working with the parameters given, it returns its output to the player. The output will either indicate a successful execution of a command or will indicate an error.'

This is similarly misleading. Most output is achieved with notify muf calls and output happening at the end is incidental. A muf command could output one thing at the start of its execution, run for its full length, and then output nothing at the end. This is also muddled with the notion of TUIs, which output during execution and don't have a result.

The exception is MPI programs which generally DO have an output. Although it's not uncommon for a complicated MPI program to be wrapped in {null:} and notify with {tell:} instead.

4) Getting help is a really good section.

5) Could use some resources under external links to help people write programs.

-- Lepus 2017-08-15 18:26:53

PageTalk/Commands (last edited 2017-08-16 14:56:58 by Alkani)