>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3614221. --> Reported by: [mably](https://www.drupal.org/user/3375160) Related to !123 >>> <p>Yoyaku can draw and sell a hall of 1,422 seats, and every piece of it is documented on its own: the <code>yoyaku_placement_io</code> README specifies the venue package format, and the Placement page explains what the picker does with a drawing once it has one. What no page explains is how a person gets from a floor plan to a bookable hall. That is the one thing a new site builder has to do first, and it is currently learned by reading the example package and guessing.</p> <h3>What the page has to cover</h3> <p>In the order the work is actually done.</p> <p><strong>1. The artwork.</strong> What the SVG must contain, and why each requirement exists rather than just that it exists:</p> <ul> <li>a <code>viewBox</code>, because it defines the coordinate space every place's x and y is expressed in; get this wrong and the seats land off the picture</li> <li>a <code>symbol</code> per place sprite inside <code>defs</code>, whose ids go in the venue's Place sprite id and Accessible place sprite id fields</li> <li>an id on any shape a pooled area will be clicked through, named by that section's Map element field</li> <li>what to leave out: the seats themselves, which the picker draws</li> <li>that it is one standalone file, fetched and injected as a document, and served publicly like any other upload</li> </ul> <p><strong>2. From a plan to coordinates.</strong> The hard part, and the part the module has no tool for. The page should be honest that this is a one-off job per hall, describe the realistic routes (seats drawn as elements in the artwork and extracted with a throwaway script, a spreadsheet of rows with a computed layout, or an export from a seating tool that already has the geometry), and then walk one worked example small enough to follow by hand: one section, two rows, real numbers. The bundled Auditorium de Bordeaux package is the shape to imitate at scale, and the page should point at it rather than invent a second example.</p> <p><strong>3. The entities, and what each one decides.</strong> A place grade is a price band and a legend color. A section is an area whose weight orders the panel and whose mode decides how it is sold: place by place, as a pool, or not at all. A pooled area needs a capacity and must name no map element, because a shape means it is sold from the plan. A configuration is which areas are on sale for a production, which is what lets one hall run at reduced capacity without a second venue.</p> <p><strong>4. Loading it.</strong> The package format and the two drush commands, by reference to the io README rather than repeated here, plus what export is for: build a hall by hand once, export it, and keep it in version control.</p> <p><strong>5. Checking the result.</strong> The failure modes, each with its cause, because every one of them looks like a broken module to someone who has not been told:</p> <ul> <li>seats invisible: the sprite id is not defined as a symbol in the artwork</li> <li>seats bunched together or outside the picture: coordinates are not in the viewBox coordinate space</li> <li>a pooled area with no steppers in the panel: it names a map element, so it is sold from the plan instead</li> <li>no plan at all: the venue has no artwork, or no place has coordinates</li> <li>the plan reports it could not be loaded: the artwork itself could not be fetched</li> </ul> <h3>Where it goes</h3> <p>A new page in the handbook, after Placement, which is reference material and should stay that way. This one is a tutorial and reads top to bottom.</p> <h3>Scope</h3> <p>Documentation only, no code. Writing it will probably surface two things that deserve their own issues rather than being solved inside a doc page: that producing seat coordinates has no tooling at all, and that the venue form accepts sprite ids without checking that the uploaded artwork defines them, which is the single easiest way to end up with a hall of invisible seats.</p> <p>Worth writing now because <span class="drupalorg-gitlab-issue-link drupalorg-gitlab-link-wrapper"><a href="https://git.drupalcode.org/project/yoyaku/-/work_items/3614077" class="drupalorg-gitlab-link">https://git.drupalcode.org/project/yoyaku/-/work_items/3614077</a></span> changed what an author needs to know: the artwork is a resource of its own rather than markup inside the drawing, so it has to be a standalone file, and replacing it is picked up.</p>