Help documentation

Author: graham-trott

iwsy/resources/ecs/help.txt

@@ -52,6 +52,7 @@ GetPage:
     	put empty into Page
         go to GetPage
     end
+    put Page into storage as `.help`
     set the content of Container to showdown decode Content with DecoratorCallback
     set the elements of Link to LinkCount
     put 0 into N
@@ -93,7 +94,12 @@ Decorate:
 !	Process an image, including positioning and class information
 ProcessImage:
 	put the position of `:` in Data into N
-    if N is -1 return
+    if N is -1
+    begin
+        put `<img id="ec-image-` cat ImageCount cat `" src="` cat Data cat `" />` into Payload
+        add 1 to ImageCount
+        return
+    end
     put left N of Data into Source
     add 1 to N
     put from N of Data into Data

iwsy/resources/ecs/steps.txt

@@ -395,7 +395,7 @@ ReloadStepEditor:
 	create TR in Table
     create TD in TR
     set the style of TD to `width:6em`
-    set the content of TD to `Title:`
+    set the content of TD to `Name:`
     create TD in TR
     index TitleInput to SelectedStep
     create TitleInput in TD

iwsy/resources/help/action-init.md

@@ -0,0 +1,17 @@
+~page:contents:Contents~
+
+# The `init` action
+
+Every presentation starts with an `init` action, which defines the environment in which the presentation will run. The editor looks like this:
+
+~img:resources/users/2020/160/1/images/help/editor-init.png~
+
+Here there are a set of _properties_ relating to the `init` action. All these are editable. The Title is there for your convenience; it has no affect on the presentation. The properties are as follows:
+
+ - `aspect` `ratio` is a pair of numbers that govern the size of the display area. The width is that of the container provided to IWSY by the web page. Sometimes the height will also be defined, in which case you should clear the `aspect` `ratio` field. In most cases, though, the height is not given. You can decide what it should be in relation to the width. The default is a 16:9 widescreen format but other common choices are 4:3 (old-style TV) and 1:1 (square). On one particular laptop, 16:9 is OK but the values 160:89 work better to fill the screen exactly. Some experimentation may be needed, and once you've discovered a ratio that works for your computer you can use it in all presentations.
+ 
+ - `background` is for the entire screen. By default it has no value, making it transparent. The values you use here are standard CSS background styles, which include using images.
+ 
+ - `border` is also for the screen. A default value is provided. When you started IWSY the left-hand side of the screen will have shown this outline before the help panel replaced it.
+ 
+ - `css` is any set of global style values you wish to set up for your presentation. These will be added to the HEAD of your document. Typical uses are to set a color for headers or to adjust margins on specific elements.

iwsy/resources/help/addBlock.md

@@ -0,0 +1,3 @@
+~page:contents:Contents~
+
+# Adding a new block

iwsy/resources/help/addContent.md

@@ -0,0 +1,3 @@
+~page:contents:Contents~
+
+# Adding content

iwsy/resources/help/addStep.md

@@ -0,0 +1,3 @@
+~page:contents:Contents~
+
+# Adding a new step

iwsy/resources/help/contents.md

@@ -0,0 +1,21 @@
+~page:iwsy:Home~
+
+# Contents
+
+~page:quickstart:Quick-start tutorial~ **Beginners start here!**
+
+~page:users:User registration and login~
+
+~page:project:The Project panel~
+
+~page:start:Starting a project~
+
+~page:addStep:Adding a step~
+
+~page:addBlock:Adding a block~
+
+~page:addContent:Adding content~
+
+## Actions
+
+~page:action-init:The `init` action~

iwsy/resources/help/iwsy.md

@@ -1,6 +1,14 @@
+~page:contents:Contents~
+
 # I Wanna Show You 
 
-I Wanna Show You (IWSY, pronounced "You-zee" as an approximation to the initials) is an online presentation package. It has the ability to deliver slideshows that either run under manual control or unattended, but instead of being a PC application that's tied to the desktop, IWSY is entirely browser-based. IWSY presentations can run here in this web app, they can be embedded in other web pages or they can run as independent web pages.
+I Wanna Show You (IWSY, pronounced "You-zee" as an approximation to the initials) is an online presentation package. It's built to deliver slideshows that either run under manual control or unattended, but instead of being a PC application that's tied to the desktop, IWSY is entirely browser-based. IWSY presentations can run here in this web app, they can be embedded in other web pages or they can run as independent web pages.
+
+## Quick-start
+
+These help pages contain everything there is to know about IWSY, but there's a lot to read. Most people just want to get started quickly, so we have a built-in ~page:quickstart:quick-start tutorial~ where you can create a simple presentation - a few slides with text and pictures - in just a few minutes. Once you've completed this first step you'll have a pretty good idea of what IWSY is all about, and the rest of the help pages won't be nearly as intimidating.
+
+## Feature summary
 
 The basic features of IWSY are:
 
@@ -12,9 +20,6 @@ The basic features of IWSY are:
  - User management - each user has their own account and storage area
  - Image management - users can create folders, upload/delete images and so on
  - Built-in help - what you're reading
+ - A ~page:quickstart:quick-start tutorial~
 
-The block and content editors may be an unfamiliar concept. Rather than hand-editing each slide you use blocks to define the areas of the screen that will hold text or images. Each block has a name so you can choose which ones to use for any given part of the show. Similarly, the text content is all edited separately and each item has a name.
-
-All text input in IWSY is in MarkDown format, which is much simpler than HTML, being mostly plain text. All standard features of MarkDown are supported, plus some custom additions documented in these Help pages.
-
-~page:start:Starting a project~
+~page:contents:Contents~

iwsy/resources/help/project.md

@@ -0,0 +1,30 @@
+~page:contents:Contents~
+
+# The Project panel
+
+The right-hand side of the screen holds the Project panel. When you start up - or after you click the ~img:resources/users/2020/160/1/images/help/new.png:{width:1em}~(New) button - it looks like this:
+~img:resources/users/2020/160/1/images/help/project.png:100%~
+
+There are 3 main sections.
+
+## 1 - Steps
+
+This lists the steps of your presentation. These are in some way analogous to the 'slides' of a PowerPoint presentation. A step is any action that affects the presenttion, whether it causes any visual change or not. Every presentation starts with an `init` step where you define the size and proportions of your screen. This step is already provided, with its name on a clickable button. When you click the button it opens the ~page:action-init:`init` step editor~. All the action types are documented in their own pages - see the ~page:contents:Contents~.
+
+To the left of the button is a tiny ~img:/resources/icon/binoculars.png:{width:1em}~ binoculars symbol. When you click one of these the panel on the left - called the _player_ - shows you what the presentation looks like at this step.
+
+To the right of the button is a ~img:/resources/icon/plus.png:{width:1em}~ plus symbol, that when clicked adds a new step to the end of the presentation. See ~page:addStep:Adding a step~.
+
+## 2 - Blocks
+
+This lists the blocks used in your presentation. A block is a rectangular area of the screen that can contain text, an image or some of each.
+
+It's common to use the same layout for multiple slides in a presentation, and one of the problems with PowerPoint is how difficult it is to change a layout once set. Sometimes the only way is to edit the numerical coordinates of the text and other blocks on each slide; a time-consuming and error-prone task.
+
+IWSY takes a different approach. You define all the different type of block that will be used, giving each one a name, then use them on as many slides as you like. To make changes you then just need to edit the block definition; all the slides that use it will take on the new size and position. See ~page:addBlock:Adding a block~.
+
+## 3 - Content
+
+This lists all the content text items used in your presentation. Each one is named. In the step editor you assign content to blocks by clicking names from a drop-down list. This makes it much easier to see what is where than by having the full text visible at each point.
+
+All content text is written using **_MarkDown_**; a format that is mostly plain text, plus simple markup tags to define headers and other text features. IWSY provides a set of custom MarkDown extensions that define image and other attributes. These help pages are written using the same system. See ~page:addContent:Adding content~.

iwsy/resources/help/quickstart.md

@@ -0,0 +1,61 @@
+~page:contents:Contents~
+
+# Quickstart
+
+This tutorial will quickly take you through all the steps needed to build your first IWSY presentation. Everything you need is here and everything will be explained.
+
+We don't need to log into IWSY, so that's some time saved already. The first thing to do is define a _block_. This is an area of the screen having a defined position and size, to contain text and/or images.
+
+## Your first block
+
+Click the **Blocks** button over in the right-hand panel, then click the ~img:/resources/icon/plus.png:{width:1em}~ at the right-hand end of the title row. Now click the button titled "New Block". You should get this:
+
+~img:resources/users/2020/160/1/images/quickstart/newblock.png:100%~
+
+Most of these default values are fine as they are; they describe a block that occupies the whole window area. Let's just change the 'name' property to `background` and the 'background' property to `url('resources/users/2020/160/1/images/SemoigoDawn.jpg')`. The effect will be to display a full-size image.
+
+The effect I want to create is for the image to fade up from the white of the screen background. So let's go to to the **Steps** editor and make that happen. But before we do so, let's save our work. Type the name `quickstart` in the **Script name** box under the main button bar, then click the ~img:/resources/icon/save.png:{width:1em}~ icon in the button bar. It's highly recommended that you click this button regularly so you don't lose your work in the event of something going wrong.
+
+## Adding some steps
+
+The `init` step is fine as it is so there's no need to touch it. Click the ~img:/resources/icon/plus.png:{width:1em}~ to add a new step, then click the **New step** button. You should see this:
+
+~img:resources/users/2020/160/1/images/quickstart/newstep.png:100%~
+
+Click in the Action box and a drop-down list appears:
+
+~img:resources/users/2020/160/1/images/quickstart/actions.png:100%~
+
+Choose `set content`. Now set the `name` property to `set up background`. It should now look like this:
+
+~img:resources/users/2020/160/1/images/quickstart/setup-background.png:100%~
+
+Click the ~img:/resources/icon/plus.png:{width:1em}~ in the `Blocks` row, then click the empty selector under the `Blocks` title. A drop-down list appears with the name of the block we created earlier:
+
+~img:resources/users/2020/160/1/images/quickstart/select-background-block.png:100%~
+
+so select that. The block has no text; if it did we'd choose it in the `Content` drop-down list. Click the **Save** button for this step, then click the ~img:/resources/icon/save.png:{width:1em}~ icon in the button bar.
+
+## Fading up
+
+Now we have a block with a background, let's fade it up. Click ~img:/resources/icon/plus.png:{width:1em}~ again or click the **Add step after** button. In the new step, open the editor, give it the name `fade up background` and select the **fade up** action. It should look like this:
+
+~img:resources/users/2020/160/1/images/quickstart/fade-up-background.png:100%~
+
+This action lets you fade up as many blocks as you like simultaneously, so it provides you with the means to add a list. Here we only have a single block so let's add that. Click the ~img:/resources/icon/plus.png:{width:1em}~ in the **Blocks** row, then click the empty selector in the new row and choose **background** again. Finally set the duration of the fade to a suitable value; say 2 (seconds). You can use decimal fractions here if you need to. It should now look like this:
+
+~img:resources/users/2020/160/1/images/quickstart/fade-up-background2.png:100%~
+
+If you haven't saved your project recently, do it now.
+
+## Watch it run!
+
+Now it's time to test your work. This will cause the help panel to disappear, but don't worry; you can bring it back by clicking the ~img:/resources/icon/help.png:{width:1em}~ button in the toolbar.
+
+Click the ~img:/resources/icon/run.png:{width:1em}~ icon in the button bar and enjoy watching your steps run!
+
+A couple of things to note. One is that as the presentation runs the steps in the editor take on green backgrounds. With only a single fade this happens too quickly to see, but in a longer presentation you can see where you are at all times.
+
+Another thing is that you can click the ~img:/resources/icon/binoculars.png:{width:1em}~ icon for any step to see what the presentation looks like at that step. The program invisibly runs the entire presentation up to the step you clicked, then runs that step, giving the button a blue background.
+
+in ~page:quickstart-part2:Part 2~ we'll add some text to the presentation.