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.

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