PCjs documentation updates

Gruntfile.js

@@ -379,12 +379,12 @@ module.exports = function(grunt) {
                     }
                 }
             },
-            "demos": {
+            "examples": {
                 files: [
                     {
                         cwd: "versions/pcjs/<%= pkg.version %>/",
                         src: ["pc.js", "pc-dbg.js", "components.css", "components.xsl"],
-                        dest: "docs/pcjs/demos/",
+                        dest: "docs/pcjs/examples/",
                         expand: true
                     }
                 ],
@@ -457,8 +457,8 @@ module.exports = function(grunt) {
                 cmd: "./modules/htmlout/bin/delete_indexes.sh",
                 args: []
             },
-            "zipify-demos": {
+            "zipify-examples": {
-                options: {cwd: "docs/pcjs/demos"},
+                options: {cwd: "docs/pcjs/examples"},
                 cmd: "./zip.sh",
                 args: ["v" + pkg.version + ".zip"]
             }
@@ -512,6 +512,6 @@ module.exports = function(grunt) {
     grunt.registerTask("promote", ["replace:promote-to-version"]);
     grunt.registerTask("clean", ["run:delete-indexes"]);
     grunt.registerTask("copyfiles", grunt.option("rebuild")? ["copy"] : ["newer:copy"]);
-    grunt.registerTask("default-osx", ["compile", "copyfiles", "run:zipify-demos"]);
+    grunt.registerTask("default-osx", ["compile", "copyfiles", "run:zipify-examples"]);
     grunt.registerTask("default", ["compile", "copyfiles"]);
 };

README.md

@@ -63,8 +63,8 @@ Developer Notes
 
 The [PCjs repository](https://github.com/jeffpar/pcjs) on GitHub contains everything needed to run PCjs
 computer simulations.  The [PCjs](/docs/pcjs/) and [C1Pjs](/docs/c1pjs/) emulators run in any modern web browser,
-with or without a web server, and examples are provided for both [local](/docs/pcjs/demos/) and [remote](http://www.pcjs.org/)
+with or without a web server, and examples are provided for both [local](/docs/pcjs/examples/) and
-operation.
+[remote](http://www.pcjs.org/) operation.
 
 The project includes:
 
@@ -80,7 +80,7 @@ JavaScript files to your browser will work.  However, instructions for doing tha
 In fact, you can run PCjs simulations without a web server at all, using the "file:" protocol instead of "http:".
 However, most of the machine configurations require additional resource files (ROMs, disk images, etc), which are
 included in the project, but unless all the resource files are moved into a single directory (as they are in these
-[Demos](/docs/pcjs/demos/)), your browser will probably be unable to load all of them, due to security restrictions.
+[Demos](/docs/pcjs/examples/)), your browser will probably be unable to load all of them, due to security restrictions.
 Using the bundled web server is the preferred solution.
 
 The project includes a large selection of disk images, and a powerful [DiskDump](modules/diskdump/) utility that

_includes/machine-engines.html

@@ -22,7 +22,7 @@ here and in markout.js.  Examples include 'autopower' ('autoPower') and 'automou
 
 {% endcomment %}
 {% for machine in page.machines %}
-  {% capture machine_embed %}window.embed{{ machine.type | remove:'-dbg' | upcase }}{% endcapture %}
+  {% capture machine_embed %}embed{{ machine.type | remove:'-dbg' | upcase }}{% endcapture %}
   {% if machine.autopower == nil %}
     {% assign machine_autopower = "true" %}
   {% else %}

docs/pcjs/README.md

@@ -12,7 +12,7 @@ PCjs Documentation
 ---
 
 [PCjs](/docs/about/pcjs/) is a full-featured IBM PC, PC XT and PC AT emulator written entirely in JavaScript.
-After you've read the Documentation, play with the [Demos](demos/).
+After you've read the Documentation, play with the [Examples](examples/).
 
 {% include machine.html id="ibm5150" %}
 
@@ -23,29 +23,29 @@ of XSL and CSS support files (included in the ZIP file below).
 
 ### Creating Machine XML Files
 
-A PCjs machine XML file defines all a machine's components. Components include:
+A PCjs machine XML file defines all a machine's components, including:
 
-* [Chipset](/docs/pcjs/chipset/)
+* [Chipset](chipset/)
-* [Computer](/docs/pcjs/computer/)
+* [Computer](computer/)
-* [Control Panel](/docs/pcjs/panel/)
+* [Control Panel](panel/)
-* [CPU](/docs/pcjs/cpu/)
+* [CPU](cpu/)
-* [Debugger](/docs/pcjs/debugger/)
+* [Debugger](debugger/)
-* [Floppy Disk Controller](/docs/pcjs/fdc/)
+* [Floppy Disk Controller](fdc/)
-* [Hard Disk Controller](/docs/pcjs/hdc/)
+* [Hard Disk Controller](hdc/)
-* [Keyboard](/docs/pcjs/keyboard/)
+* [Keyboard](keyboard/)
-* [Mouse](/docs/pcjs/mouse/)
+* [Mouse](mouse/)
-* [RAM](/docs/pcjs/ram/)
+* [RAM](ram/)
-* [ROM](/docs/pcjs/rom/)
+* [ROM](rom/)
-* [Parallel Port](/docs/pcjs/parallel/)
+* [Parallel Port](parallel/)
-* [Serial Port](/docs/pcjs/serial/)
+* [Serial Port](serial/)
-* [Video Adapter](/docs/pcjs/video/)
+* [Video Adapter](video/)
 
 Here's a simple machine XML file that includes an 8088 CPU and 16Kb of RAM:
 
 	<machine id="ibm">
-		<computer id="pc" name="IBM PC"/>
+	    <computer id="pc" name="IBM PC"/>
-		<cpu id="cpu8088" model="8088"/>
+	    <cpu id="cpu8088" model="8088"/>
-		<ram id="ramLow" addr="0x00000" size="0x04000"/>
+	    <ram id="ramLow" addr="0x00000" size="0x04000"/>
 	</machine>
 
 However, that machine isn't usable, since it lacks a keyboard, screen, or any code (ROMs) to execute.
@@ -53,93 +53,108 @@ However, that machine isn't usable, since it lacks a keyboard, screen, or any co
 A simple machine definition that actually works might look like:
 
 	<machine id="ibm" class="pc" width="720px">
-		<computer id="pc" name="IBM PC"/>
+	    <computer id="pc" name="IBM PC"/>
-		<cpu id="cpu8088" model="8088"/>
+	    <cpu id="cpu8088" model="8088"/>
-		<ram id="ramLow" addr="0x00000" size="0x04000"/>
+	    <ram id="ramLow" addr="0x00000" size="0x04000"/>
-		<rom id="romBASIC" addr="0xf6000" size="0x8000" file="ibm-basic-1.00.json"/>
+	    <rom id="romBASIC" addr="0xf6000" size="0x8000" file="ibm-basic-1.00.json"/>
-		<rom id="romBIOS" addr="0xfe000" size="0x2000" file="1981-04-24.json"/>
+	    <rom id="romBIOS" addr="0xfe000" size="0x2000" file="1981-04-24.json"/>
-		<keyboard id="keyboard"/>
+	    <keyboard id="keyboard"/>
-		<video id="videoMDA" model="mda" screenwidth="720" screenheight="350" charset="ibm-mda-cga.json">
+	    <video id="videoMDA" model="mda" screenwidth="720" screenheight="350" charset="ibm-mda-cga.json">
-			<name>Monochrome Display</name>
+	        <name>Monochrome Display</name>
-		</video>
+	    </video>
-		<chipset id="chipset" model="5150" sw1="01000001" sw2="11110000"/>
+	    <chipset id="chipset" model="5150" sw1="01000001" sw2="11110000"/>
 	</machine>
 
-Here is a [demo](/docs/pcjs/demos/sample1.html) of this machine's [XML](/docs/pcjs/demos/sample1.xml) file.
+Here is an [example](examples/example1.html) of this machine's [XML](examples/example1.xml) file.
 
 Machine definitions can also include visual elements.  For example, we can include a "Run" button with the CPU component.
 Note that as soon as the machine is ready and the CPU starts running, the "Run" button will change to "Halt".
 
 	<machine id="ibm" class="pc" width="720px">
-		<computer id="pc" name="IBM PC"/>
+	    <computer id="pc" name="IBM PC"/>
-		<cpu id="cpu8088" model="8088">
+	    <cpu id="cpu8088" model="8088">
-			<control type="button" class="input" binding="run">Run</control>
+	        <control type="button" class="input" binding="run">Run</control>
-		</cpu>
+	    </cpu>
-		...
+	    ...
 	</machine>
 
 Next, we can add a Floppy Disk Controller (FDC) component.  And since we want to be able to "load" and "unload" floppy
 disks at will, we'll include some UI controls.
 
 	<machine id="ibm" class="pc" width="720px">
-		<fdc id="fdcNEC" automount="{A: {name: 'PC-DOS 1.0', path: 'pcdos-1.00.json'}}">
+	    <fdc id="fdcNEC" automount="{A: {name: 'PC-DOS 1.0', path: 'pcdos-1.00.json'}}">
-			<control type="container">
+	        <control type="container">
-			<control type="list" class="input" binding="listDrives"/>
+	            <control type="list" class="input" binding="listDrives"/>
-				<control type="list" class="input" binding="listDisks">
+	            <control type="list" class="input" binding="listDisks">
-					<disk path="">None</disk>
+	                <disk path="">None</disk>
-					<disk path="pcdos-1.00.json">PC-DOS 1.0</disk>
+	                <disk path="pcdos-1.00.json">PC-DOS 1.0</disk>
-				</control>
+	            </control>
-				<control type="button" class="input" binding="loadDrive">Load</control>
+	            <control type="button" class="input" binding="loadDrive">Load</control>
-			</control>
+	        </control>
-		</fdc>
+	    </fdc>
-		...
+	    ...
 	</machine>
 
-Here is a [demo](/docs/pcjs/demos/sample2.html) of the updated machine's [XML](/docs/pcjs/demos/sample2.xml) file.
+Here is an [example](examples/example2.html) of the updated machine's [XML](examples/example2.xml)
+file.
 
 ### Loading Machine XML Files
 
-Inside a web page, add a &lt;div&gt; to contain the machine, load the **pc.js** script
+Inside a web page, add a &lt;div&gt; to contain the machine, load the *pc.js* script
-(**pc-dbg.js** if you need the PCjs [Debugger](/docs/pcjs/debugger/)), and then call *window.embedPC()*:
+(*pc-dbg.js* if you need the PCjs [Debugger](debugger/)), and then call *embedPC()*:
 
-	<div id="sample2"/>
+	<div id="example2"/>
 	<script type="text/javascript" src="pc.js"/>
 	<script type="text/javascript">
-		window.embedPC("sample2", "sample2.xml", "components.xsl");
+	    embedPC("example2", "example2.xml", "components.xsl");
 	</script>
 
-In fact, this is exactly what we did in the previous [demo](/docs/pcjs/demos/sample2.html).
+In fact, this is exactly what we did in the previous [example](examples/example2.html).
 
-*window.embedPC()* requires 3 parameters:
+*embedPC()* accepts 4 parameters:
 
-- The *id* of the machine &lt;div&gt; (e.g., "sample2");
+- The *id* of the machine &lt;div&gt; (e.g., "example2");
-- The *url* of the machine XML file (e.g., "sample2.xml");
+- The *url* of the machine XML file (e.g., "example2.xml");
 - The *url* of the components XSL file (e.g., "components.xsl")
+- Any *parms* that should be passed to the machine components during initialization
 
-**components.xsl** (and the corresponding **components.css**) are included with the PCjs scripts in the samples download below.
+The first 3 parameters are required; the *parms* parameter is optional.  If *parms* is specified, it should
+contain a single-quoted JSON object definition, with properties intended to override those specified in the
+machine XML file; eg:
+
+	'{messages:"warn",autoMount:{"A":{"path":"/disks/pc/dos/ibm/1.00/PCDOS100.json"}}}'
+
+*components.xsl* (and the corresponding *components.css*) are included with the PCjs scripts in the
+[Examples](#running-pcjs-on-your-own-server) download.  Every version of *components.xsl* has a corresponding
+*components.css*, which your web page should also load, usually with a &lt;link&gt; tag inside the &lt;head&gt;
+element; eg:
+
+	<link rel="stylesheet" type="text/css" href="components.css">
 
 ### Using the PCjs Debugger
 
 To create a configuration that includes the PCjs Debugger, you need to:
 
-- Add [Debugger](/docs/pcjs/debugger/) and [Control Panel](/docs/pcjs/panel/) components to the machine XML file;
+- Add [Debugger](debugger/) and [Control Panel](panel/) components to the machine XML file;
 - Add debugger controls to the Control Panel, such as Run, Step, Reset, etc;
-- Change your web page to load **pc-dbg.js** instead of **pc.js**.
+- Change your web page to load *pc-dbg.js* instead of *pc.js*.
 
-Take a look at the [sample3a](/docs/pcjs/demos/sample3a.html) demo (with [XML file](/docs/pcjs/demos/sample3a.xml)) for an example.
+Take a look at the [example3a](examples/example3a.html) example
+(with [XML file](examples/example3a.xml)).
 
-The debugger gives you access to more capabilities than mere debugging. For example, you can use the **load** command
+The debugger gives you access to more capabilities than mere debugging. For example, you can use the **load**
-to load diskette sectors into memory ("l &lt;addr&gt; &lt;drive&gt; ...") or dump an entire diskette as JSON ("l json &lt;drive&gt;").
+command to load diskette sectors into memory ("l [addr] [drive #] ...") or the **dump** command to dump an entire
-You can also **halt** a machine ("h") and **dump** its entire state as JSON ("d state"). You can save that state in a .json file,
+diskette as JSON ("d disk [drive #]").  You can also **halt** a machine ("h") and **dump** its entire state as JSON
-and then use that state to initialize a new machine (as long as it uses the same machine *id*).
+("d state"). You can save that state in a .json file, and then use that state to initialize a new machine (as long as
+it uses the same machine *id*).
 
-In fact, the [sample3b](/docs/pcjs/demos/sample3b.html) demo (with [XML file](/docs/pcjs/demos/sample3b.xml))
+In fact, the [example3b](examples/example3b.html) example (with [XML file](examples/example3b.xml))
-does just that, using JSON dumps created from [sample3a](/docs/pcjs/demos/sample3a.html) after starting VisiCalc.
+does just that, using JSON dumps created from [example3a](examples/example3a.html) after starting VisiCalc.
-See the *state* attribute on the [Computer](/docs/pcjs/computer/) component for more information on state files.
+See the *state* attribute on the [Computer](computer/) component for more information on state files.
 
 ### Running PCjs On Your Own Server
 			
-All of the demos described above are available for [download](/docs/pcjs/demos/).
+All of the examples described above are available for [download](examples/).
 
 ### Creating PCjs-Compatible Disk Images
 

docs/pcjs/demos/README.md

@@ -1,34 +0,0 @@
----
-layout: page
-title: PCjs Documentation Demos
-permalink: /docs/pcjs/demos/
-machines:
-  - type: pc
-    id: sample3
-    config: /docs/pcjs/demos/sample3b.xml
----
-
-PCjs Documentation Demos
----
-
-This folder provides all the self-contained [PCjs](/docs/about/pcjs/) demos described in the [Documentation](/docs/pcjs/).
-
-To use them, download [samples.zip](samples.zip), unzip it into a folder on your desktop computer or web server,
-and experiment with them in your web browser.  Since all these samples are self-contained, they should work with either
-the "file:" or "http:" protocol.
-
-+ Check out the sample HTML and XML files:
-	- [sample1.html](sample1.html) and [sample1.xml](sample1.xml)
-	- [sample2.html](sample2.html) and [sample2.xml](sample2.xml)
-	- [sample3a.html](sample3a.html) and [sample3a.xml](sample3a.xml)
-	- [sample3b.html](sample3b.html) and [sample3b.xml](sample3b.xml)
-+ Feel free to copy/paste additional components from other machine XML files on [pcjs.org](http://www.pcjs.org/).
-+ Remember to display the appropriate attribution on anything you share publicly; e.g.:
-		[PCjs](http://pcjs.org) © 2012-2016 by [Jeff Parsons](mailto:Jeff@pcjs.org) ([@jeffpar](http://twitter.com/jeffpar))
-+ Stay in sync with the [PCjs repository](https://github.com/jeffpar/pcjs), to keep your copy of PCjs up-to-date.
-
-Have fun!
-
-{% include machine.html id="sample3" %}
-
-[Return to [PCjs Documentation](..)]

docs/pcjs/demos/zip.sh

@@ -1,4 +0,0 @@
-#!/bin/sh
-if [ ! -d zips ]; then mkdir zips; fi
-zip -q zips/$1 * -x samples*.zip zip.sh
-cp zips/$1 samples.zip

docs/pcjs/examples/README.md

@@ -0,0 +1,36 @@
+---
+layout: page
+title: PCjs Documentation Examples
+permalink: /docs/pcjs/examples/
+machines:
+  - type: pc
+    id: example3
+    config: /docs/pcjs/examples/example3b.xml
+redirect_from:
+  - /docs/pcjs/demos/
+---
+
+PCjs Documentation Examples
+---
+
+This folder provides all the self-contained [PCjs](/docs/about/pcjs/) examples described in the [Documentation](/docs/pcjs/).
+
+To use them, download [examples.zip](examples.zip), unzip it into a folder on your desktop computer or web server,
+and experiment with them in your web browser.  Since all these examples are self-contained, they should work with either
+the "file:" or "http:" protocol.
+
++ Check out the example HTML and XML files:
+	- [example1.html](example1.html) and [example1.xml](example1.xml)
+	- [example2.html](example2.html) and [example2.xml](example2.xml)
+	- [example3a.html](example3a.html) and [example3a.xml](example3a.xml)
+	- [example3b.html](example3b.html) and [example3b.xml](example3b.xml)
++ Feel free to copy/paste additional components from other machine XML files on [pcjs.org](http://www.pcjs.org/).
++ Remember to display the appropriate attribution on anything you share publicly; e.g.:
+		[PCjs](http://pcjs.org) © 2012-2016 by [Jeff Parsons](mailto:Jeff@pcjs.org) ([@jeffpar](http://twitter.com/jeffpar))
++ Stay in sync with the [PCjs repository](https://github.com/jeffpar/pcjs), to keep your copy of PCjs up-to-date.
+
+Have fun!
+
+{% include machine.html id="example3" %}
+
+[Return to [PCjs Documentation](..)]

docs/pcjs/examples/example1.html

@@ -2,15 +2,15 @@
 <html>
 	<head>
 		<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
-		<title>pcjs.org | /docs/pcjs/demos/sample1.html</title>
+		<title>pcjs.org | /docs/pcjs/demos/example1.html</title>
 		<meta charset="utf-8">
 		<link rel="stylesheet" type="text/css" href="components.css">
 		<script type="text/javascript" src="pc.js"></script>
 	</head>
 	<body style="font-family: Helvetica, Arial, sans-serif;">
-		<div id="sample1"></div>
+		<div id="example1"></div>
 		<script type="text/javascript">
-			window.embedPC("sample1", "sample1.xml", "components.xsl");
+			embedPC("example1", "example1.xml", "components.xsl");
 		</script>
 	</body>
 </html>

docs/pcjs/examples/example1.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<machine id="sample1" class="pc" width="720px">
+<machine id="example1" class="pc" width="720px">
 	<computer id="pc" name="IBM PC"/>
 	<cpu id="cpu8088" model="8088" autostart="true"/>
 	<ram id="ramLow" addr="0x00000" size="0x10000"/>

docs/pcjs/examples/example2.html

@@ -2,15 +2,15 @@
 <html>
 	<head>
 		<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
-		<title>pcjs.org | /docs/pcjs/demos/sample2.html</title>
+		<title>pcjs.org | /docs/pcjs/demos/example2.html</title>
 		<meta charset="utf-8">
 		<link rel="stylesheet" type="text/css" href="components.css">
 		<script type="text/javascript" src="pc.js"></script>
 	</head>
 	<body style="font-family: Helvetica, Arial, sans-serif;">
-		<div id="sample2"></div>
+		<div id="example2"></div>
 		<script type="text/javascript">
-			window.embedPC("sample2", "sample2.xml", "components.xsl");
+			embedPC("example2", "example2.xml", "components.xsl");
 		</script>
 	</body>
 </html>

docs/pcjs/examples/example2.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<machine id="sample2" class="pc" width="720px">
+<machine id="example2" class="pc" width="720px">
 	<computer id="pc" name="IBM PC"/>
 	<ram id="ramLow" addr="0x00000" size="0x10000"/>
 	<rom id="romBASIC" addr="0xf6000" size="0x8000" file="ibm-basic-1.00.json"/>

docs/pcjs/examples/example3a.html

@@ -2,15 +2,15 @@
 <html>
 	<head>
 		<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
-		<title>pcjs.org | /docs/pcjs/demos/sample3a.html</title>
+		<title>pcjs.org | /docs/pcjs/demos/example3a.html</title>
 		<meta charset="utf-8">
 		<link rel="stylesheet" type="text/css" href="components.css">
 		<script type="text/javascript" src="pc-dbg.js"></script>
 	</head>
 	<body style="font-family: Helvetica, Arial, sans-serif;">
-		<div id="sample3"></div>
+		<div id="example3"></div>
 		<script type="text/javascript">
-			window.embedPC("sample3", "sample3a.xml", "components.xsl");
+			embedPC("example3", "example3a.xml", "components.xsl");
 		</script>
 	</body>
 </html>

docs/pcjs/examples/example3a.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<machine id="sample3" class="pc" border="0" width="900px">
+<machine id="example3" class="pc" border="0" width="900px">
 	<computer id="pc" name="IBM PC"/>
 	<cpu id="cpu8088" model="8088" autostart="true"/>
 	<debugger id="debugger"/>

docs/pcjs/examples/example3b.html

@@ -2,15 +2,15 @@
 <html>
 	<head>
 		<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
-		<title>pcjs.org | /docs/pcjs/demos/sample3b.html</title>
+		<title>pcjs.org | /docs/pcjs/demos/example3b.html</title>
 		<meta charset="utf-8">
 		<link rel="stylesheet" type="text/css" href="components.css">
 		<script type="text/javascript" src="pc.js"></script>
 	</head>
 	<body style="font-family: Helvetica, Arial, sans-serif;">
-		<div id="sample3"></div>
+		<div id="example3"></div>
 		<script type="text/javascript">
-			window.embedPC("sample3", "sample3b.xml", "components.xsl");
+			embedPC("example3", "example3b.xml", "components.xsl");
 		</script>
 	</body>
 </html>

docs/pcjs/examples/example3b.xml

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<machine id="sample3" class="pc" width="720px">
+<machine id="example3" class="pc" width="720px">
-	<computer id="pc" name="IBM PC" state="sample3.json"/>
+	<computer id="pc" name="IBM PC" state="example3.json"/>
 	<cpu id="cpu8088" model="8088" autostart="true"/>
 	<ram id="ramLow" addr="0x00000" size="0x10000"/>
 	<rom id="romBASIC" addr="0xf6000" size="0x8000" file="ibm-basic-1.00.json"/>

docs/pcjs/examples/zip.sh

@@ -0,0 +1,4 @@
+#!/bin/sh
+if [ ! -d zips ]; then mkdir zips; fi
+zip -q zips/$1 * -x examples*.zip zip.sh
+cp zips/$1 examples.zip