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

• Under Struture & Command Life style, I think it would be worth noting that a few commands, notably editors such as editplayer, mail, lsedit have a more involved usage case than send the command (with parameters), it runs then returns results. Once you enter those commands, you're in another shell until you exit it.

  • I'm working on rewriting the article to include these concepts, since there isn't a good way to address this idea with the current structure. Since the article is, overall, considered okay without being overly technical, I feel comfortable mentioning this concept in here. I'm not sure how relevant it is to the average user aside from, depending on the application, they have to interact with the MUCK in a restricted way, but it's worth putting in if I'm talking about program linking. -- Alkani 2017-08-14 12:31:12

    • I have rewritten the article. That was exhausting, but I think well worth it. -- Alkani 2017-08-14 13:53:44

• Minor thing under Return. You give an example the outputs caused by paging, but one might wonder, what was the imput typed to generate that output? ---Jaxen

  • The output in Return is based on the command string that Violet composed at the end of the Composition section. However, that linkage isn't apparent. I have added text to make it clearer that the Return section output is based on the input from the Composition section. -- Alkani 2017-08-14 12:31:12

• Should it be mentioned it's possible for one to have personal commands or area specific commands? 'Restrictions' might be a good place to note this if any. --- Jaxen

  • I was struggling with whether or not to add this as a remark, so now I will. -- Alkani 2017-08-14 12:31:12

• Under 'Global Commands', I think it's worth noting SpinDizzy tries to set a description on all globals which leads to documation of said global. It's also common practice on MUCKs for the parameter '#help' to bring up that command's documentation. ---Jaxen

  • I've added an explanation about using 'look <command>' and '<command> #help' to get help for global commands. Both syntaxes are used extensively, with more weight being placed on 'look <command>' in the current global command set (78 v. 57). The remaining twenty-one commands use neither. Perhaps unifying the global command help system could be a small side project of mine at some point. -- Alkani 2017-08-14 12:31:12

• Lastly, I added whospecies to the short list of common commands, so if any newbie comes across that list, they'll know how to tell if they're in a room with someone to talk to. ---Jaxen

  • Thank you! Hoping to expand this list considerably as part of the Getting Started document. -- Alkani 2017-08-14 12:31:12

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

• Oh, this is definitely not intended as the Getting Started document. That will, hopefully, ultimately be GettingStarted/A Player's First Day, which I sort of want to call "Player's First Day" or something ridiculous as a reference to "The Little Red Hen" video from Rifftrax. -- Alkani 2017-08-14 13:53:44

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

• I think the best way I can describe what the goals of the document are is to point to the first eight sections: in short, the document is to provide information and guidance on those specific aspects of commands and enable a reader, who may or may not be familiar with MUCKs or even with command-line processing environments, some idea of how those commands interact with the system and with other players, what kinds of commands there are, how they operate, how to get help about them, and any other additional details. It's not intended to be super-technical, but at the same time, it's not intended to be entry-level (that's what Getting Started is for). I feel like the purest revision that holds to this is Revision 15, but I also recognize that Revision 16 does include salient points about command scope and console persistence v. non-persistence (couldn't think of a good way to describe forked v. non-forked without getting super technical). By all means, take a pass at it. I know there are some inconsistencies in formatting that I want to address (i.e. references to programs should be emphasized with code) and the difference between a command and a program needs to be better defined (a command is a way of invoking a program; a program actually processes parameters and does meaningful work). I know something else I created a "mapping" for in the map on my homepage was a Glossary, which would be helpful to store terms. I'm not sure if "Program" requires a separate entry compared to "Command", but perhaps it would be worth considering, too. And I might just be blowing this out of proportion. -- Alkani 2017-08-14 18:45:13

• I also just realized that the scope of the Commands document is really intended to talk about publically accessible and generally available commands on the MUCK, not on developing commands for personal use. Perhaps discussing writing commands for personal use should be relegated to more mention in either Building or Programming. -- Alkani 2017-08-14 18:54:46

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.

• Absolutely. Good to remove that bit of duplication since it's spelled out later. -- Alkani 2017-08-16 14:52:52

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.

• We've already had a long discussion about the metaphor, so I won't rehash all that here. In short, because this document is intended for people who aren't necessarily familiar with (or care about) the underpinnings of MUCK function, it's important to give folks who aren't used to the environment something to latch on to so they can understand concepts associated with working in an environment like a MUCK. This is especially important for non-technical users or users who don't have familiarity with a command-line processing-style environment. One thing that could definitely be debated (and I feel might be a more relevant question, and I wrote the section) is whether or not there needs to *be* a delineation between built-ins and global packages. The same, however, could be said about public v. private, and persistent v. non-persistent. I feel that having categories will help people new to a MUCK environment look at things and make links between concepts, especially if they decide to do some building of their own, and go "Oh! I know why people can't use that action. It's because it's private." Or "I don't want people to use this action, so I can hide it by making it Dark." Or, "Oh, I know why my stuff is getting gobbled up when I try to interact with the outside world, it's because this is a persistent command." Teaching concepts is important for people who are new or unfamiliar; it gives building blocks. Practical examples are also good, as has been pointed out, and I intend on putting practical examples in all of the Command Documents as they're built, including complex examples where applicable. More advanced things, like whether or not MUF programs return before or after execution (which I think it's blasphemy to return execution status BEFORE something has even executed, but that is a conversation for another day), is something to be considered by individuals who have moved far, far beyond the point of needing a concept scoped and defined for them. Those are MUCKers and Systems Programmers, and they will likely start here, but move far beyond this document, which will have been a building block in that journey, hopefully. -- Alkani 2017-08-16 14:52:52

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.

• I've actually tried to fold this into the Command Lifecycle section by specifically pointing out that commands sometimes give you intermediate pieces of information as part of the execution step, because that's a great point: programs can return multiple things before returning the penultimate "I'm finished." As I stated above for Item 2, if a programmer decides they want to tell a user "I'm finished doing this thing" before the program actually performs any work, I'm not sure that I can control that. From my own personal experience, there has been no generally-used MUCK program that's accessible to users that doesn't return *something* "at the end" as part of its execution. Just because a programmer *could* do something, doesn't mean that they *do* do something. I can't stop a programmer from not following a good pattern (telling a user when something is completed when it's *actually* completed), but I can certainly document what the pattern is expected to look like based on how things *appear*. What you are pointing out is an important nuance to note in programming, and I think it *should* be noted an expanded upon further in the SpinDizzy MUCK System Programming page (perhaps as Something Not To Do Without Good Reason TM). I would be curious to see how many MUF programs don't follow that reasonable ages-old pattern of "Tell people when it's done," especially since as MUCK users, we don't have things like job control, and we don't actually have a terminal to regain control of at the end of execution anyway, so we can't tell if we have our console back unless we're told, such as by getting an "I'm done" message. -- Alkani 2017-08-16 14:52:52

4) Getting help is a really good section.

• Thank you. I think Jaxen helped plenty with that as well, so they deserve equal credit. -- Alkani 2017-08-16 14:52:52

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

• Composing programs is beyond the scope of this document. I feel that anything to help readers write programs would probably be most effective as references in the SpinDizzy MUCK System Programming page to prevent information creep/scatter. -- Alkani 2017-08-16 14:52:52

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

• Thank you for the feedback! It was really great! -- Alkani 2017-08-16 14:52:52