From a1df81ff782363b980f7af1d047366eb849d1aa3 Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Sat, 14 Nov 2026 22:29:16 +0100 Subject: [PATCH] Separate Midra manual quick start and advanced guides --- docs/manuals/midra-layout/SUMMARY.md | 38 ++++++++----- docs/midra-layout/README.md | 4 +- docs/midra-layout/changelog.md | 2 + docs/midra-layout/guide/README.md | 8 +-- docs/midra-layout/guide/quickstart.md | 80 +++++++++++++++++++++++++++ 5 files changed, 111 insertions(+), 21 deletions(-) create mode 100644 docs/midra-layout/guide/quickstart.md diff --git a/docs/manuals/midra-layout/SUMMARY.md b/docs/manuals/midra-layout/SUMMARY.md index 045ff83..0229fc7 100644 --- a/docs/manuals/midra-layout/SUMMARY.md +++ b/docs/manuals/midra-layout/SUMMARY.md @@ -1,22 +1,30 @@ # Summary -- [Introduction](../../midra-layout/README.md) -- [User guide contents](../../midra-layout/guide/README.md) -- [Layers and editing](../../midra-layout/guide/editing.md) -- [Canvas and reference images](../../midra-layout/guide/canvas.md) -- [Formats, crop and precision](../../midra-layout/guide/formats-and-crop.md) -- [Import, export and project files](../../midra-layout/guide/files.md) -- [Menus and preferences](../../midra-layout/guide/preferences.md) -- [Midra connection and transfers](../../midra-layout/guide/device.md) +[Introduction](../../midra-layout/README.md) + +# Quick start + +- [Your first layout](../../midra-layout/guide/quickstart.md) - [Starter files for every format](../../templates/midra-layout/README.md) + +# Advanced + +- [Advanced guide](../../midra-layout/guide/README.md) + - [Layers and editing](../../midra-layout/guide/editing.md) + - [Canvas and reference images](../../midra-layout/guide/canvas.md) + - [Formats, crop and precision](../../midra-layout/guide/formats-and-crop.md) + - [Import, export and project files](../../midra-layout/guide/files.md) + - [Menus and preferences](../../midra-layout/guide/preferences.md) + - [Midra connection and transfers](../../midra-layout/guide/device.md) - [Resolution and cropping model](../../midra-layout/resolutions.md) -- [Project file contract](../../interfaces/midra-layout.md) -- [Geometry exchange contract](../../interfaces/midra-layout-exchange.md) -- [Settings contract](../../interfaces/midra-layout-settings.md) -- [Recovery contract](../../interfaces/midra-layout-recovery.md) -- [Device import contract](../../interfaces/midra-device-import.md) -- [Device send contract](../../interfaces/midra-device-send.md) -- [Input preview contract](../../interfaces/midra-input-preview.md) +- [File and device contracts](../../interfaces/README.md) + - [Project file contract](../../interfaces/midra-layout.md) + - [Geometry exchange contract](../../interfaces/midra-layout-exchange.md) + - [Settings contract](../../interfaces/midra-layout-settings.md) + - [Recovery contract](../../interfaces/midra-layout-recovery.md) + - [Device import contract](../../interfaces/midra-device-import.md) + - [Device send contract](../../interfaces/midra-device-send.md) + - [Input preview contract](../../interfaces/midra-input-preview.md) - [Hardware verification](../../midra-layout/device-check.md) - [Viewport performance](../../midra-layout/guide/performance.md) - [Updating screenshots](../../midra-layout/images/README.md) diff --git a/docs/midra-layout/README.md b/docs/midra-layout/README.md index f45c468..2abb159 100644 --- a/docs/midra-layout/README.md +++ b/docs/midra-layout/README.md @@ -10,7 +10,7 @@ frame their content before working with the screen processor. You can design offline, exchange geometry with drawing and presentation tools, and connect to an Analog Way Eikos 4K when you are ready to review and transfer a layout. -[User guide](guide/README.md) · [Starter files for all formats](../templates/midra-layout/README.md) · [Changelog](changelog.md) +[Quick start](guide/quickstart.md) · [Advanced guide](guide/README.md) · [Starter files for all formats](../templates/midra-layout/README.md) · [Changelog](changelog.md) ## Start a layout @@ -76,7 +76,7 @@ See [formats and crop](guide/formats-and-crop.md) and Follow the [connection and transfer guide](guide/device.md) and its linked hardware-verification notes before using device writes. -For advanced workflows, start at the [user guide contents](guide/README.md). +For advanced workflows, start at the [advanced guide](guide/README.md). File schemas and compatibility rules are in the [interface reference](../interfaces/README.md). [Screenshot capture and update instructions](images/README.md) diff --git a/docs/midra-layout/changelog.md b/docs/midra-layout/changelog.md index e414167..c1ecd21 100644 --- a/docs/midra-layout/changelog.md +++ b/docs/midra-layout/changelog.md @@ -4,6 +4,8 @@ ## Unreleased +- Split the Midra mdBook into Quick start and Advanced sections, with a first-layout walkthrough and nested workflow/contract chapters. Keep the existing detailed chapters and screenshot capture notes linked. + - Add direct links to the published mdBook manual from the project README, tool guide and documentation indexes. - Mark PPTX, draw.io and SVG format acceptance as solved following the user's confirmation that all three work (2026-11-14). diff --git a/docs/midra-layout/guide/README.md b/docs/midra-layout/guide/README.md index cdf4622..eaf7e61 100644 --- a/docs/midra-layout/guide/README.md +++ b/docs/midra-layout/guide/README.md @@ -1,9 +1,9 @@ -# Midra Layout user guide +# Midra Layout advanced guide -[Introduction and quick start](../README.md) · [Starter files](../../templates/midra-layout/README.md) · [Changelog](../changelog.md) +[Introduction](../README.md) · [Quick start: your first layout](quickstart.md) · [Starter files](../../templates/midra-layout/README.md) · [Changelog](../changelog.md) -Detailed controls, workflows and limitations are grouped below. Start with layers -and the canvas, then use the chapters relevant to your workflow. +Use this guide after the [first-layout walkthrough](quickstart.md), or jump +directly to the detailed controls, workflows and limitations you need. | Chapter | What it covers | | --- | --- | diff --git a/docs/midra-layout/guide/quickstart.md b/docs/midra-layout/guide/quickstart.md new file mode 100644 index 0000000..ccbfcfe --- /dev/null +++ b/docs/midra-layout/guide/quickstart.md @@ -0,0 +1,80 @@ +# Quick start: your first layout + +[Introduction](../README.md) · [Advanced guide](README.md) · [Starter files](../../templates/midra-layout/README.md) + +Make a simple Slides + Presenter layout, save an editable project, and export its +geometry. This walkthrough uses the default Full HD canvas and works offline; +no screen processor is needed. + +## 1. Open a fresh layout + +Launch Midra Layout. To run from source, use this command from the repository root: + +```sh +cargo run --locked -p midra-layout +``` + +See [development setup](../../development/README.md) if you need the build tools. +If a previous layout was restored, save any work you want to keep, then choose +**Project → New project…** and confirm. + +The default canvas is **1920 × 1080**, with **Slides** and **Presenter** layers. +Leave that resolution unchanged for this walkthrough. + + +![Default Full HD layout with Slides and Presenter, with Presenter selected](../images/01-workspace.png) + +## 2. Place and size the layers + +1. Click **Presenter** in the Layers list or on the canvas. +2. Drag the layer to position it. Drag a corner handle to resize it; keep + **Keep aspect ratio when resizing** checked to preserve its proportions. +3. For exact placement, use the inspector's position fields. Check the selected + measurement corner first: “From right” measures from the right edge, not the left. +4. Select **Slides** and position it beside the presenter. Use **Undo** if a move + or resize is not what you wanted. + +The layer-resolution field opens **Layer properties**, where you can enter exact +width and height. Leave the default sizes if you only want to try positioning. + +## 3. Try framing the content + +With **Presenter** selected, open **Layer properties → Crop**. The source pattern +shows how content fits inside the visible layer box. Drag the content to adjust +its position or use the crop handles to change its zoom. + +The visible layer box stays fixed while cropping. Use **Reset crop** to return to +the default framing, then switch back to the **Layer** tab to finish crop editing. +You can skip this step if you only need rectangle positions. + +## 4. Save the editable project + +Apply any pending property edits, then choose **Project → Save project…** and +save as `first-layout.midra.json`. This is the file to reopen when you want to continue +editing: it retains the project, including source/crop settings and reference images. + +Use **Project → Open project…** to load it later. + +## 5. Export the layer geometry + +Choose **Project → Export → Export layers…**, select **SVG** and **All layers…**, +and save the export. For plain layer boxes, leave the background and placeholder +pictures disabled. The SVG can be opened in a vector editor. + +Keep the `.midra.json` project as well: a geometry export does not retain all editor +settings. The [starter-file catalog](../../templates/midra-layout/README.md) has +matching layouts in every supported format if you prefer to start in another app. + +## Continue with the advanced guide + +You now have an editable project and a geometry export. Choose your next task: + +- [Organize and align layers](editing.md), including folders and multiple selections. +- [Add reference images and adjust the canvas view](canvas.md). +- [Control source formats and cropping](formats-and-crop.md). +- [Import existing geometry or choose export scopes](files.md). +- [Connect an Eikos 4K and review layer transfers](device.md). Device sends are + explicit actions; ordinary local editing does not send changes. + +The [advanced guide](README.md) also links to settings, compatibility contracts +and hardware-verification details.