Kokkoja as of 2026-10-10: the teacher's requests, the Session window, notices, the QR code, the license

docs/guest.md

@@ -14,22 +14,28 @@ chat message, a text message.  It is a link of this shape:
 
 The part after `join=` is the invitation itself, which the host's Kokkoja
 may also give you on its own, without the link around it.  Both forms
-work wherever an invitation is asked for.  The invitation carries the key
+work wherever an invitation is asked for.  A host in the same room may
+instead show you the link as a QR code on their screen: point your
+phone's or tablet's camera at it and open the link it offers.  The invitation carries the key
 that protects the session, so pass it on only to people who belong in the
 session, and treat it as you would a meeting link.  An invitation is good
 for one session: the host's next session has a new one.
 
 ## Joining
 
-Open the link in a web browser.  Firefox, Brave and Chrome are known to
-work; other browsers built on the same engines very probably do.  You see
-Kokkoja's start screen with the invitation already filled in.  Enter the
-name the others should see and press **Join**.  That is all: nothing is
-installed, and there is no account to make.
+Open the link in a web browser.  Firefox, Brave and Chrome on a
+computer, and Safari on an iPad or an iPhone, are known to work; other
+browsers built on the same engines very probably do.  You see
+Kokkoja's start screen, headed "Join a session", with the invitation
+already filled in.  Enter the name the others should see and press
+**Join**.  That is all: nothing is installed, and there is no account to
+make.  (Opened without an invitation, the same screen also offers to
+start a session of your own; an invitation is a request to join one
+session, so with one it offers joining alone.)
 
 Your name is remembered by the browser for next time.  So is a second
-field, **Notebook for the pages of this session**, which you can leave as
-it is for now; what it does is explained under "Your notebook" below.
+choice, **Notebook for the pages of this session**, which you can leave
+as it is for now; what it does is explained under "Your notebook" below.
 
 If you have the Kokkoja program installed on your computer (see
 [A host's Kokkoja](host.md) for what that is and why you might want it),
@@ -42,15 +48,17 @@ place in it waits for the host to return.
 
 ## The screen
 
-Across the top is the toolbar.  On the left are the tools and their
-settings; on the right, the zoom and, for the host, the buttons that
-start pages.  Below it, the page fills most of the window, with a panel on
-the right.  Every button explains itself: rest the pointer on it for a
-second and its explanation appears beneath it.
+Across the top is the toolbar, one row holding everything: the tools
+and their settings, the view, the host's page buttons, your notebook,
+and **Session**, which opens a window with the participants and the
+invitation.  Below it the page has the whole width of the window.  Every button
+explains itself: rest the pointer on it for two seconds and its
+explanation appears beneath it.
 
 ### The page
 
-The page is an A4 sheet, shown so that it fits the window.  Write
+The page is an A4 sheet lying on its side, shown so that it fits the
+window.  Write
 anywhere on it.  When your writing comes near an edge, the sheet grows in
 that direction, in small steps, so there is always room, and the view
 keeps its scale and extends beyond the window; scroll to reach the rest.
@@ -65,11 +73,12 @@ is scrolled to concern nobody else.
 
 **Pen** is chosen when you arrive.  Draw with a pen on a tablet, a mouse,
 or a finger on a touch screen.  With a pen, pressing harder makes the
-line wider.  The colours are to the right of the tools: black, blue, red
-and green, and **+** opens a palette of more.  A colour chosen from the
-palette joins the row of colours and stays there in this browser.  The
-three lines to the right of the colours are the line widths: 0.4, 0.7
-and 1.2 mm at ordinary pressure.
+line wider.  The colours are to the right of the tools: black, red,
+green, blue and white, and **+** opens a palette of more, in which the
+colours already in the row leave their places empty.  A colour chosen
+from the palette joins the row and stays there in this browser.  White
+is for painting over.  The four lines to the right of the colours are
+the line widths: 0.4, 0.7, 1.2 and 2.4 mm at ordinary pressure.
 
 If a pen is in use, a hand resting on a touch screen is ignored.
 
@@ -78,17 +87,25 @@ If a pen is in use, a hand resting on a touch screen is ignored.
 **Text** types on the page.  Tap where the text should begin and type; a
 text field appears there and the text is laid out on the page as you
 type.  Enter begins a new line.  Press Escape, or tap somewhere else, to
-finish; a block with nothing in it disappears.
+finish; a block with nothing in it disappears.  You need not finish to
+move a block: rest the pen on it while typing, and it follows the pen,
+field and all; lift, and go on typing.
 
 A block made by a tap does not wrap: its lines are as long as you type
-them, and the page grows to hold them.  To make the text wrap at a chosen
-width, drag along where its top edge should run instead of tapping: the
-block begins at the left end of the drag and wraps at the right end.
+them, and the page grows to hold them; a red corner mark of 5 mm at its
+top left shows where it begins.  To make a *text rectangle*
+instead, drag it open where you want it: a red box, white inside, in
+which the text wraps at the box's width, and which grows downward by
+lines when you type more than it holds.  The box is part of the page,
+seen by everyone, and where it lies over an image it covers the image
+and nothing else; a teacher uses one to say "write your answer here".
 
-Tap your own text to change it.  While a block of yours is being edited
-it is drawn grey, and three handles appear: the one at its top-left
-corner and the line along its top edge move it, the one at the right end
-of that line changes its width.  You cannot change anyone else's text.
+Tap your own text to change it, anywhere in a box, and the cursor is at
+the end of the text.  To move a block of yours, rest the pen
+on it, without moving, for a little over half a second: a green outline
+appears, and it follows the pen.  To resize a text rectangle, rest the
+pen near one of its corners and drag the corner; the text wraps anew at
+the new width.  You cannot change anyone else's text.
 
 With the Text tool, the row of colours stays and the line widths give way
 to the font, one of **Sans**, **Serif** and **Mono**, and the size in
@@ -102,48 +119,79 @@ whole stroke goes; across a text block and the block goes.  It removes
 nothing of anyone else's, and nobody else's eraser can touch yours.  An
 erased stroke is gone from the page for everyone.
 
-### Zoom
+### The view
 
-**Fit** shows the whole page in the window, and keeps doing so as the
-page grows by writing, except while you are in the middle of a stroke of
-your own.  **+** and **−** zoom in and out by a tenth.  Holding Ctrl and
-turning the scroll wheel zooms about the pointer.  When the page is
-larger than the window, scroll it as you would any page.  When the host
-adds an image, the view keeps its scale rather than shrinking to fit; a
-new image at the bottom of a long page is reached by scrolling.
+A page is shown whole when you first see it.  Afterwards the view keeps
+its scale: when the page grows, or the host adds an image, the page
+extends beyond the window and you scroll to the rest.  Three buttons and
+two gestures change the view, and none of them changes the page:
+
+* **Fit** shows the whole page in the window.
+* **A4** shows the page at the scale a new page has, one A4 sheet
+  filling the window, so that a page shrunk to a small exercise is seen
+  at its size on the sheet rather than enlarged to fill the window.
+* When the host presses **Fit** or **A4**, every participant's view
+  follows, each in their own window.  Your own Fit and A4 change only
+  your screen.
+* **Widen**, which only the host and co-hosts have, makes the page
+  itself wider, for everyone, until it fills the
+  window at the present zoom.  The sheet grows equally on both sides,
+  so nothing on the page moves and nothing is rescaled; there is simply
+  more room at either side.
+* **Shrink**, also for the host and co-hosts, makes the page, for everyone, just large enough for what is on it,
+  with the usual margin around.  Nothing on it moves either.
+* **Extend** is a box, ticked to begin with.  Ticked, the sheet grows
+  when your writing comes near an edge, so there is always room.
+  Unticked, your writing stops short of the edge; a stroke that leaves
+  the page resumes when the pen comes back.  Images always get the room
+  they need.
+* Hold **Ctrl** (Command on a Mac) and turn the scroll wheel to zoom in
+  and out about the pointer.
+* Hold **Ctrl** (Command on a Mac) and draw a stroke with the pen: up
+  zooms in, down zooms out, by twice for every 100 pixels of movement,
+  about the point where the pen touched down.  Nothing is drawn while
+  the key is held.
 
 If you reload the browser tab, it comes back to the page as you last saw
 it: same zoom, same place.
 
-### The panel
+### Session
 
-**Participants** lists everyone in the session, with *you* and *host*
-marked, and *away* beside anyone who has left or lost their connection;
-an absent participant's writing stays on the page.  The box in front of
-each name shows or hides that participant's writing on your screen alone.
-Hiding your teacher's corrections to try an exercise again, or hiding
-your own answers to see the exercise as it was, changes nothing for
-anyone else.
+**Session** in the toolbar opens a window with the people and the
+invitation.  **Participants** lists everyone in the session, with *you*
+and *host* marked, and *away* beside anyone who has left or lost their
+connection; an absent participant's writing stays on the page.  The box
+in front of each name shows or hides that participant's writing on your
+screen alone.  Hiding your teacher's corrections to try an exercise
+again, or hiding your own answers to see the exercise as it was,
+changes nothing for anyone else.
 
 **Invitation** shows the invitation of this session, with a button to
-copy it, in case someone else should be invited.
+copy it and, below, as a QR code for a camera, in case someone else
+should be invited.  **Log** is a record of what happened in this
+session, pages and connection and every press and release of the pen,
+with a button to copy it: if something goes wrong, copy it and send it
+to whoever looks after Kokkoja.  Above it the window says which page
+you are on, counted from the start of the session, how you stand with
+the relay, and when the page was last saved; below it, where your
+notebooks are kept.
 
-**Current notebook**, **Keep page** and **Export** concern your notebook,
-below.  Under them, a line reports what was last saved, and whether
-anything went wrong.
+### Notices
 
-The last line of the panel reports what your pen or mouse is delivering:
-the kind of device, the pressure, and how many positions per second it
-sends.  It is there for curiosity and for finding faults.
+While all is well Kokkoja says nothing.  When there is something to
+know, a line appears between the toolbar and the page: in red while
+a problem lasts, in grey for a few seconds after something was done.
+*Not connected. Reconnecting…* means the relay cannot be reached;
+Kokkoja reconnects by itself, and what you wrote meanwhile is sent when
+it returns.  *The page could not be saved* means the notebook is out of
+reach; the page is still in memory and the saving is tried again.
+*Waiting for the host's page* means the host has not started a page
+yet, or your connection is down.  The grey notices say that a page was
+kept or exported, and where.
 
-### Status
-
-At the right end of the toolbar, **Page 3** is the number of the page you
-are on, counted from the start of the session, and beside it *Connected*,
-*Connecting…* or *Disconnected* says how you stand with the relay.  If
-the connection drops, Kokkoja reconnects by itself; what you wrote while
-disconnected is sent when it returns.  Until the host has started a
-page, the toolbar says *Waiting for the host's page*.
+For finding faults, the browser's console (F12) keeps a short log of the
+session's events: pages, images, the connection, and what your pen or
+mouse delivers.
 
 ## Your notebook
 
@@ -162,24 +210,28 @@ last changed and the number counting the pages kept that day.
 
 Two buttons bring pages out of the browser:
 
-* **Keep page** keeps a dated copy of the page as it is now, and
+* **Keep** keeps a dated copy of the page as it is now, and
   downloads it, so you find it among your browser's downloads.  Pressing
-  it again before anything has changed makes no second copy.
+  it again before anything has changed makes no second copy and no
+  second download.  Any mark counts as a change, even a dot from a
+  stray touch of the pen.
 * **Export** downloads a picture of the page as you see it, as a PNG
   file; writing you have hidden is left out.  Its name is the date and
   the page number.
 
 A page file is an SVG file.  Any web browser displays it, and vector
 drawing programs such as Inkscape open it.  Kokkoja itself can load one
-again, writing and all, when someone with the right to start pages
-chooses it (see "When the host gives you more" below, and the host's
+again, writing and all, when the host or a co-host chooses it (see "When the host gives you more" below, and the host's
 part).
 
-The notebook field on the start screen names the notebook within the
+The notebook list on the start screen names the notebook within the
 browser's storage.  Giving each course or each colleague a notebook of
-their own keeps their pages apart; the name proposed is simply
-*Notebook*.  **Current notebook** in the panel shows the notebook in use
-and lets you change it during the session.
+their own keeps their pages apart; until you make one, everything goes
+into the notebook *General*.  The last entry of the list, **New
+notebook…**, asks for a name and makes a notebook of that name; it
+exists from the moment a page is written into it.  **Current notebook**
+in the toolbar is the same list, and lets you change notebook, or make
+one, during the session.
 
 ### On your computer
 
@@ -193,7 +245,7 @@ to open the invitation in the installed program.
 
 With the program, a notebook is a directory in `Kokkoja` in your
 Documents directory.  The page you are on is `Current.svg` there, and
-kept pages lie beside it under their dated names.  **Keep page** makes
+kept pages lie beside it under their dated names.  **Keep** makes
 the dated copy; **Export** opens Kokkoja's own file chooser, in which you
 pick a directory and a name for the PNG file.
 
@@ -210,35 +262,44 @@ still on the page, from the others' copies and from your notebook, and
 it is still yours to erase or change.  A tab that was in a session and is
 reloaded goes straight back in.
 
-## When the host gives you more
+## When the host makes you a co-host
 
 Normally only the host puts images on the page, starts new pages, or
-loads pages from a notebook.  The host can give you the same right, for
-instance in a discussion among colleagues where everyone brings
-material.  When that happens, three more buttons appear at the right of
-your toolbar:
+loads pages from a notebook.  The host can make you a *co-host*, which
+gives you the same powers, for instance in a discussion among
+colleagues where everyone brings material.  The Session window then
+says *co-host* beside your name, and three more buttons appear at the
+right of your toolbar:
 
 * **New** starts a new blank page for everyone.  The page being left is
   kept in each person's notebook.
 * **Image** puts an image file on the page for everyone, below any
   images already there.  Your browser's file chooser asks for the file
   (with the Kokkoja program, Kokkoja's own chooser does, beginning where
-  the notebooks are, with a choice whether an image wider than the page
-  is shrunk to fit it).  A PNG or JPEG file keeps its exact pixels unless
+  the notebooks are).  A PNG or JPEG file keeps its exact pixels unless
   it is very large; other formats and very large images are converted
   and reduced before they are shared.  An image is placed at its natural
-  size, centred, 8 mm from the top or from the image above; one wider
-  than the sheet is scaled down to fit between the margins.  To put an
-  image on a page of its own, press **New** first.
+  size, centred, 5 mm below the image above or at the top of the page;
+  one wider than the page widens it.  To put an image on a page of its
+  own, press **New** first.
 * **Notebook** starts a new page for everyone from a page kept in one of
   your notebooks, with everything that was written on it.  A chooser
   shows your notebooks and small pictures of their kept pages.  The kept
   page itself is not changed: the session works on a copy.
+* **Hide**, among the tools, hides part of the page for everyone: drag
+  open a rectangle and whatever lies under it, writing included, is
+  covered in white, marked by blue corners so that nobody writes there
+  unknowingly.  Rest the pen on it to move it, near a corner to resize
+  it; a tap of the eraser removes it and uncovers what was there.  A Hide
+  stays even for someone who hides your writing on their own screen.
 
-An image cannot be moved or removed once anyone has written on it or
-added anything after it, since the marks on it would make no sense
-without it.  The one exception is a mistake caught at once: the person
-who added an image can take it back with a tap of the eraser on it, as
-long as nothing else has happened on the page since.
+As a co-host you can also move and scale images, as the host can: rest the pen on an image for a little over half a second
+and it follows the pen; rest it near a corner and the corner follows,
+the shape kept.  Writing stays where it is, so images are arranged
+first and written on afterwards.  A new image always arrives below the
+others, centred, at its own size, to be arranged by hand.  A tap of the
+eraser on an image removes it; writing on it stays.  An image you added
+yourself you may always remove, even after you have stopped being a
+co-host.
 
-The right stays with you until the host withdraws it or the session ends.
+You stay a co-host until the host decides otherwise or the session ends.