From b812f1658e8a84e72da6ed02963fef35d090a72a Mon Sep 17 00:00:00 2001 From: Martin Tazl Date: Wed, 29 Jul 2026 09:00:12 +0200 Subject: [PATCH] docs: add English quick reference to help --- PROJECT_KNOWLEDGE.md | 9 +- README.md | 13 +- app.py | 54 +++++++ docs/de/recent_changes.md | 1 + docs/en/quick_reference.md | 315 +++++++++++++++++++++++++++++++++++++ static/recent_changes.json | 1 + templates/help_index.html | 10 ++ templates/user_manual.html | 13 ++ 8 files changed, 413 insertions(+), 3 deletions(-) create mode 100644 docs/en/quick_reference.md diff --git a/PROJECT_KNOWLEDGE.md b/PROJECT_KNOWLEDGE.md index 61ff1bb..75e8d44 100644 --- a/PROJECT_KNOWLEDGE.md +++ b/PROJECT_KNOWLEDGE.md @@ -18,6 +18,7 @@ Backend: - `/` renders the active calculator template. - `/help` renders the authenticated Help landing page. - `/help/user-manual` renders `docs/de/user_manual.md` server-side inside the RollCalc Help layout. +- `/help/quick-reference` renders `docs/en/quick_reference.md` server-side inside the RollCalc Help layout. - `/help/recent-changes` renders `docs/de/recent_changes.md` server-side inside the RollCalc Help layout. - `/help/user-manual/screenshots/` serves German manual screenshots from `docs/de/screenshots/`. - `/static/` is intended to serve static files behind Basic Auth. @@ -58,6 +59,8 @@ The data is loaded centrally in `app.py` and made available to every template as The in-app Help area keeps `docs/de/user_manual.md` as the leading German documentation source. RollCalc reads the Markdown file on each `/help/user-manual` request and renders it server-side with `markdown-it-py`. +`docs/en/quick_reference.md` is the English Quick Reference source and is rendered at `/help/quick-reference`. It is derived from the full German User Manual and must remain a concise workflow reference rather than an independently diverging technical source. + The documentation structure is prepared for language-specific manuals: ```text @@ -65,9 +68,11 @@ docs/ de/ user_manual.md screenshots/ + en/ + quick_reference.md ``` -Additional languages can follow the same structure later. The current public route still opens the German manual and no language switcher is implemented. +Additional languages can follow the same structure later. The current public route still opens the German manual, the Quick Reference is currently English only, and no language switcher is implemented. Rendering rules: @@ -86,7 +91,7 @@ Full user-facing release notes are maintained in: docs/de/recent_changes.md ``` -The calculator header links directly to `/help/user-manual`. The Help landing page lists only existing documents, currently User Manual and Recent Changes. +The calculator header links directly to `/help/user-manual`. The Help landing page lists only existing documents, currently User Manual, Quick Reference, and Recent Changes. The startup What's New dialog uses `build_info.version` and is suppressed when the version is empty or `unknown`. The last acknowledged version is stored only in browser `localStorage` under: diff --git a/README.md b/README.md index 6a2a051..e39b186 100644 --- a/README.md +++ b/README.md @@ -94,6 +94,7 @@ Implemented routes: | `/` | `GET` | Basic Auth | Renders `templates/roll_calculator.html`. | | `/help` | `GET` | Basic Auth | Renders the Help landing page. | | `/help/user-manual` | `GET` | Basic Auth | Reads `docs/de/user_manual.md`, renders it as HTML, and displays it in the RollCalc Help layout. | +| `/help/quick-reference` | `GET` | Basic Auth | Reads `docs/en/quick_reference.md`, renders it as HTML, and displays it in the RollCalc Help layout. | | `/help/recent-changes` | `GET` | Basic Auth | Reads `docs/de/recent_changes.md`, renders it as HTML, and displays it in the RollCalc Help layout. | | `/help/user-manual/screenshots/` | `GET` | Basic Auth | Serves German user-manual screenshots from `docs/de/screenshots/` only. | | `/static/` | `GET` | Basic Auth | Intended protected static-file serving from `static/`. | @@ -173,8 +174,16 @@ Recent changes are available at: /help/recent-changes ``` +The English Quick Reference is available at: + +```text +/help/quick-reference +``` + `docs/de/user_manual.md` is the leading source for the German user manual. The app reads this Markdown file on request and renders it server-side with `markdown-it-py`; no generated static HTML copy is maintained. Raw HTML in the Markdown source is disabled during rendering. +`docs/en/quick_reference.md` is the Markdown source for the English Quick Reference. It is derived from the full German User Manual and must remain a concise reference for common workflows, not an independently diverging technical source. + `docs/de/recent_changes.md` is the leading source for full German release notes. It is rendered through the same authenticated Markdown infrastructure. The documentation directory is prepared for additional languages: @@ -184,9 +193,11 @@ docs/ de/ user_manual.md screenshots/ + en/ + quick_reference.md ``` -The public route `/help/user-manual` currently opens the German manual. No language switcher is implemented yet. +The public route `/help/user-manual` currently opens the German manual. The Quick Reference is currently English only. No language switcher is implemented yet. Screenshots referenced from the manual as `screenshots/filename.png` should be placed in: diff --git a/app.py b/app.py index 9845130..184ccfd 100644 --- a/app.py +++ b/app.py @@ -39,6 +39,7 @@ DOCS_DIR = os.path.join(app.root_path, "docs") DEFAULT_DOC_LANGUAGE = "de" USER_MANUAL_FILENAME = "user_manual.md" RECENT_CHANGES_FILENAME = "recent_changes.md" +QUICK_REFERENCE_FILENAME = "quick_reference.md" WHATS_NEW_SUMMARY_FILE = os.path.join(app.root_path, "static", "recent_changes.json") UNKNOWN_BUILD_INFO = { "version": "unknown", @@ -305,6 +306,11 @@ def render_recent_changes(language=DEFAULT_DOC_LANGUAGE): """Read and render the Markdown recent changes document.""" return render_markdown_document(RECENT_CHANGES_FILENAME, language) + +def render_quick_reference(language="en"): + """Read and render the Markdown quick reference document.""" + return render_markdown_document(QUICK_REFERENCE_FILENAME, language) + @app.route("/", methods=["GET"]) @auth.login_required def index(): @@ -330,6 +336,12 @@ def user_manual(): "user_manual.html", document_title="User Manual", document_subtitle="RollCalc technical user documentation", + document_actions=[ + { + "href": url_for("quick_reference"), + "label": "Open English Quick Reference", + } + ], error_title="User Manual unavailable", manual_html=manual_html, toc=toc, @@ -341,6 +353,12 @@ def user_manual(): "user_manual.html", document_title="User Manual", document_subtitle="RollCalc technical user documentation", + document_actions=[ + { + "href": url_for("quick_reference"), + "label": "Open English Quick Reference", + } + ], error_title="User Manual unavailable", manual_html=None, toc=[], @@ -351,6 +369,40 @@ def user_manual(): ), 500 +@app.route("/help/quick-reference", methods=["GET"]) +@auth.login_required +def quick_reference(): + """Render the English Quick Reference inside the RollCalc Help layout.""" + log_access(auth.current_user(), "/help/quick-reference", "GET") + try: + quick_html, toc = render_quick_reference("en") + return render_template( + "user_manual.html", + document_title="Quick Reference", + document_subtitle="Concise English reference for common RollCalc workflows", + document_actions=[], + error_title="Quick Reference unavailable", + manual_html=quick_html, + toc=toc, + render_error=None + ) + except Exception: + app.logger.exception("Could not render quick reference") + return render_template( + "user_manual.html", + document_title="Quick Reference", + document_subtitle="Concise English reference for common RollCalc workflows", + document_actions=[], + error_title="Quick Reference unavailable", + manual_html=None, + toc=[], + render_error=( + "The quick reference could not be loaded. " + "Please contact the RollCalc maintainer if the problem persists." + ) + ), 500 + + @app.route("/help/recent-changes", methods=["GET"]) @auth.login_required def recent_changes(): @@ -362,6 +414,7 @@ def recent_changes(): "user_manual.html", document_title="Recent Changes", document_subtitle="RollCalc release notes", + document_actions=[], error_title="Recent Changes unavailable", manual_html=changes_html, toc=toc, @@ -373,6 +426,7 @@ def recent_changes(): "user_manual.html", document_title="Recent Changes", document_subtitle="RollCalc release notes", + document_actions=[], error_title="Recent Changes unavailable", manual_html=None, toc=[], diff --git a/docs/de/recent_changes.md b/docs/de/recent_changes.md index 8a7daa4..374e432 100644 --- a/docs/de/recent_changes.md +++ b/docs/de/recent_changes.md @@ -4,6 +4,7 @@ - User Manual integrated into RollCalc. - Help area added for internal documentation. +- English Quick Reference added to the integrated Help area for the main calculation and transport-analysis workflows. - Capacity Analysis presentation improved. - Governing Constraint highlighted more clearly. - Remaining Capacity added to the Capacity Summary. diff --git a/docs/en/quick_reference.md b/docs/en/quick_reference.md new file mode 100644 index 0000000..fe330d3 --- /dev/null +++ b/docs/en/quick_reference.md @@ -0,0 +1,315 @@ +# RollCalc Quick Reference + +## 1. Before You Start + +RollCalc is an engineering support tool for roll geometry, roll weight, and transport capacity assessment. It helps experienced technical users prepare and interpret calculations, but it does not replace production, handling, or shipping approval. + +Before using a result operationally, check that the selected article, article data, manually entered values, and transport assumptions match the actual case. The calculated result is only meaningful if the input data is technically plausible. + +Use this Quick Reference for the most common workflows. For background, detailed interpretation, and troubleshooting, use the full `User Manual`. + +## 2. Which Function Should I Use? + +| Task | Function / Calculation Mode | +| --- | --- | +| Calculate the diameter of a planned roll | `Direct Calculation` → `Roll Diameter` | +| Estimate product length from a measured roll | `Direct Calculation` → `Product Length` | +| Determine maximum permitted product length | `Direct Calculation` → `Target Diameter` | +| Estimate a new roll from a reference roll | `Extrapolation` | +| Assess transport capacity | `Load Optimizer` | +| Understand why a transport result is limited | `Capacity Summary` and `Capacity Analysis` | +| Visually check the geometric arrangement | `Front View – Cross-Section` | + +## 3. Article Selection and Input Data + +Use `Article Number (optional)` when an article is available in the article data. The current application can prefill available article values such as `Product Thickness`, tolerance data, `Area Weight`, and `Core Diameter` when these values are present in the data source. + +Prefilled values are starting values, not approvals. The values currently visible in the input fields are decisive for the calculation. You can manually change the populated values before calculating. + +Planned article-data extension: future article data may also provide a typical `Roll Width` for automatic prefilling. Do not assume `Roll Width` is currently populated by article selection unless it is visibly filled in the UI. + +Check before calculation: + +- `Product Category` and `Production Site` match the intended context. +- `Article Number (optional)` refers to the correct article. +- `Product Thickness` is plausible for the product. +- `Area Weight` is current and product-specific. +- `Core Diameter` matches the actual core. +- `Roll Width` is entered when `Calculated Weight` or `Load Optimizer` will be used. + +## 4. Direct Calculation – Roll Diameter + +Use `Direct Calculation` with `Calculation Mode` `Roll Diameter` when a planned `Product Length` is known and the expected outer roll size must be assessed. + +### Required inputs + +- `Core Diameter (d)` +- `Product Thickness (t)` +- `Product Length (L)` + +### Optional weight inputs + +- `Roll Width` +- `Area Weight` + +### Main results + +- `Roll Diameter (D)` +- tolerance range when tolerance is entered +- `Calculated Weight`, when `Roll Width`, `Area Weight`, and `Product Length` are available +- `Forklift Check`, where applicable + +### Check before use + +- Units: mm for diameters and thickness, m for length and width, g/m² for `Area Weight`, kg for weight. +- `Product Thickness` is plausible and belongs to the article. +- `Core Diameter` matches the actual core type. +- `Product Length` is realistic for the planned roll. +- `Calculated Weight` is plausible before using the result in `Forklift Check` or `Load Optimizer`. + +## 5. Direct Calculation – Product Length + +Use `Direct Calculation` with `Calculation Mode` `Product Length` when a roll has a measured `Roll Diameter` and the product length on the roll must be estimated. + +### Required inputs + +- `Core Diameter (d)` +- `Roll Diameter (D)` +- `Product Thickness (t)` + +### Main result + +- `Product Length (L)` + +### Typical use + +- measured roll +- stock check +- quality check +- comparison with a planned or nominal length + +### Important caution + +The accuracy depends directly on the measured `Roll Diameter` and the assumed `Product Thickness`. If either value is inaccurate or does not match the actual product, the calculated `Product Length` will be inaccurate as well. + +## 6. Direct Calculation – Target Diameter + +Use `Direct Calculation` with `Calculation Mode` `Target Diameter` to determine the maximum allowed `Product Length` for one roll under entered diameter and weight limits. This is a limit workflow for a single roll. It is not a transport optimization and does not answer how many rolls fit into a container or vehicle. + +### Relevant inputs + +- `Core Diameter (d)` +- `Product Thickness (t)` +- `Roll Width` +- `Area Weight` +- `Max. Roll Diameter` +- `Max. Roll Weight` +- `Minimum Product Length` + +### Main results + +- `Maximum Allowed Product Length` +- `Resulting Roll Diameter` +- `Resulting weight` +- `Minimum length` +- `Difference` +- `Limiting factor` +- diameter and weight utilization line + +### Interpretation + +| Result situation | Meaning | +| --- | --- | +| `Limiting factor: Diameter` | `Max. Roll Diameter` is reached before the weight limit. | +| `Limiting factor: Weight` | `Max. Roll Weight` is reached before the diameter limit. | +| `Limiting factor: Diameter + Weight` | Both limits are reached at the same practical length. | +| warning below `Minimum length` | The requested `Minimum Product Length` cannot be achieved under the entered limits. | + +The result describes the maximum allowed single-roll layout under the entered limits. It is not automatically the best roll design. + +## 7. Roll Weight and Forklift Check + +`Roll Weight` depends on `Product Length`, `Roll Width`, and `Area Weight`. Similar `Roll Diameter` values can therefore produce very different roll weights if width, length, or material weight differ. + +`Calculated Weight` is used as the practical roll weight for downstream assessment. It is relevant for handling, `Forklift Check`, `Max. Roll Weight` checks, and the `Load Optimizer`. + +`Forklift Check` is a technical warning or handling indication. It may show messages such as `Forklift Check OK`, `Heavy Roll – Special Equipment Required`, or `Weight Limit Exceeded`. It is not an operational approval, prohibition, or safety release. + +Check first if `Forklift Check` appears unexpected: + +- `Calculated Weight` +- `Core Diameter` +- `Product Category` +- `Roll Width` +- `Area Weight` +- article data used for the calculation + +## 8. Extrapolation + +Use `Extrapolation` when a `Known Reference Roll` exists and a comparable roll with a changed length must be estimated. + +### Use only when + +- a known reference roll exists, +- the same article is used, +- `Core Diameter` is unchanged, +- material structure and `Product Thickness` are comparable, +- mainly `Product Length` changes. + +### Required inputs + +- `Core Diameter (d)` +- `Known Roll Diameter (D₀)` +- `Known Roll Length (L₀)` +- `New Roll Length (L₁)` + +### Main result + +- `Extrapolated Roll Diameter (D₁)` +- optional min/max range when `Tolerance (optional)` is entered + +### Do not use when + +- the article changes, +- `Product Thickness` changes, +- `Core Diameter` changes, +- reference data is uncertain, +- a full technical roll layout is required. + +The quality of the result depends on the quality and comparability of the reference roll. + +## 9. Load Optimizer + +Use `Load Optimizer – Transport Capacity Calculator` after the roll has already been defined. The `Load Optimizer` evaluates an existing roll in a selected transport space. It does not redesign the roll and does not automatically select the best transport mode. + +### Required roll data + +- `Roll Diameter` +- `Roll Width` +- `Roll Weight` + +These values are taken from the completed `Direct Calculation` workflow. Roll data must be plausible before the transport calculation is meaningful. + +### Required transport data + +- `Preset Transport Type:` +- or `Custom` with `Length (m)`, `Width (m)`, `Height (m)`, and `Max. Load (kg)` +- `Loading Clearances` +- `Side Wall Clearance (one side)` +- `Ceiling Clearance (top only)` + +`Loading Clearances` reduce the effective loading space. They can change the number of rolls that fit geometrically and may change the `Governing Constraint`. + +## 10. Reading the Transport Results + +Read transport results in this order: + +1. Read `Capacity Summary`. +2. Check `Total Rolls`. +3. Identify the `Governing Constraint`. +4. Review `Remaining Capacity`. +5. Check `Front View – Cross-Section`. +6. Use `Capacity Analysis` to understand the technical limit. + +### Capacity Summary + +`Capacity Summary` shows the actual transport result. It is divided into: + +- `Governing Constraint` +- `Transport Result` +- `Remaining Capacity` + +`Transport Result` includes `Total Rolls`, `Weight Utilization`, `Volume Utilization`, and the transported product area. Use these values together; a single utilization value does not explain the transport limit by itself. + +Use this area first because it shows the result that can actually be reached under the entered assumptions. + +### Governing Constraint + +| Governing Constraint | Meaning | +| --- | --- | +| `Geometry` | No additional roll fits into the actual arrangement. Payload or volume may remain unused. | +| `Weight` | The permitted payload is reached before geometric capacity is exhausted. | +| `Volume` | The calculated transport volume is reached before another constraint becomes decisive. | + +`Governing Constraint` is not a recommendation. It is the technical constraint that determines the final `Total Rolls`. + +### Remaining Capacity + +`Remaining Capacity` shows reserves after the actual loading result: + +- `Remaining Payload` +- `Unused Payload` +- `Unused Volume` + +Remaining values do not automatically mean that another roll fits. They must be read together with `Governing Constraint` and `Front View – Cross-Section`. + +### Capacity Analysis + +`Capacity Analysis` is a constraint analysis, not a list of alternative loading solutions. Its rows show theoretical capacity limits for: + +- `Weight` +- `Volume` +- `Geometry` + +The smallest applicable limit determines the actual `Total Rolls`. The governing row is marked with `→ Governing Constraint`. + +The table columns are: + +- `Constraint` +- `Max Rolls` +- `Total Weight` +- `Transported Area [m²]` +- `Payload Util. %` — indicates the percentage of the permitted payload that is used. + +### Front View – Cross-Section + +`Front View – Cross-Section` visualizes the actual geometric loading configuration. Use it to check whether the geometric arrangement is plausible, especially when `Geometry` is the `Governing Constraint`. + +### Important interpretation rules + +- `Remaining Payload` does not automatically mean that another roll fits. +- `Unused Volume` does not automatically mean that another roll fits. +- `Capacity Analysis` does not show alternative loading solutions. +- `Weight`, `Volume`, and `Geometry` are theoretical capacity limits. +- The smallest applicable limit determines the actual `Total Rolls`. + +## 11. Final Plausibility Check + +Before using a result for production, handling, or transport planning, check: + +- [ ] Correct article selected +- [ ] `Product Thickness` checked +- [ ] `Area Weight` checked +- [ ] `Core Diameter` checked +- [ ] `Roll Width` checked +- [ ] `Product Length` or `Roll Diameter` checked +- [ ] `Roll Weight` plausible +- [ ] `Calculated Weight` plausible +- [ ] Transport dimensions correct +- [ ] `Max. Load (kg)` correct +- [ ] `Loading Clearances` realistic +- [ ] `Governing Constraint` understandable +- [ ] `Remaining Payload` and `Volume Utilization` plausible +- [ ] `Front View – Cross-Section` plausible +- [ ] Result compared with experience or a reference case + +## 12. Common Problems + +| Observation | Check first | +| --- | --- | +| `Roll Diameter` is unexpectedly high or low | `Product Thickness`, `Product Length`, `Core Diameter`, units | +| `Product Length` is much larger or smaller than expected | measured `Roll Diameter`, `Product Thickness`, `Core Diameter` | +| `Roll Weight` appears incorrect | `Product Length`, `Roll Width`, `Area Weight` | +| Similar `Roll Diameter` values have very different weights | `Roll Width`, `Area Weight`, `Product Length` | +| `Forklift Check` appears unexpected | `Calculated Weight`, `Core Diameter`, `Product Category`, article data | +| `Extrapolation` result appears implausible | `Known Roll Diameter (D₀)`, `Known Roll Length (L₀)`, `New Roll Length (L₁)`, comparability of both rolls | +| Fewer rolls fit than expected | roll data, `Loading Clearances`, transport dimensions, `Governing Constraint` | +| `Remaining Payload` is available but no additional roll fits | `Geometry`, `Front View – Cross-Section` | +| `Capacity Analysis` appears contradictory | governing row, `Capacity Summary`, `Remaining Capacity`, `Front View – Cross-Section` | +| Similar calculations produce different results | article data, roll geometry, transport data, `Loading Clearances` | + +Recalculate completely after changes to article data, roll geometry, or transport parameters. Old results should not be interpreted after changing values such as `Product Thickness`, `Area Weight`, `Core Diameter`, `Roll Width`, `Max. Load (kg)`, or `Loading Clearances`. + +## 13. Key Rule + +> The calculated result is only as reliable as the entered article data, roll data, and transport assumptions. Always perform a technical plausibility check before operational use. diff --git a/static/recent_changes.json b/static/recent_changes.json index bb8016f..b0e47a5 100644 --- a/static/recent_changes.json +++ b/static/recent_changes.json @@ -1,6 +1,7 @@ { "items": [ "User Manual integrated", + "English Quick Reference added to the Help area", "Capacity Analysis improved", "Governing Constraint clarified", "Remaining Capacity added" diff --git a/templates/help_index.html b/templates/help_index.html index 205f500..82c2c8e 100644 --- a/templates/help_index.html +++ b/templates/help_index.html @@ -40,6 +40,9 @@ @@ -57,6 +60,13 @@

Open User Manual +
+

Quick Reference

+

+ Concise English reference for the most common RollCalc workflows and result interpretations. +

+ Open Quick Reference +

Recent Changes

diff --git a/templates/user_manual.html b/templates/user_manual.html index 697be68..de4e006 100644 --- a/templates/user_manual.html +++ b/templates/user_manual.html @@ -17,6 +17,9 @@ .help-nav a { color: #fff; border: 1px solid rgba(255,255,255,0.58); border-radius: 5px; padding: 7px 13px; text-decoration: none; font-size: 13px; font-weight: 700; background: rgba(255,255,255,0.08); } .help-nav a:hover { background: rgba(255,255,255,0.18); } .manual-shell { max-width: 1180px; margin: 28px auto; padding: 0 16px 60px; } + .document-actions { display: flex; gap: 10px; flex-wrap: wrap; margin: 0 0 18px; } + .document-actions a { display: inline-block; color: #1F5438; border: 1px solid #cddbd4; border-radius: 6px; background: #fff; padding: 8px 12px; text-decoration: none; font-size: 13px; font-weight: 700; box-shadow: 0 1px 6px rgba(0,0,0,0.04); } + .document-actions a:hover { background: #eef4f1; } .manual-layout { display: grid; grid-template-columns: 260px minmax(0, 1fr); gap: 24px; align-items: start; } .manual-toc { position: sticky; top: 18px; background: #fff; border: 1px solid #dfe7e2; border-radius: 8px; padding: 16px; box-shadow: 0 2px 12px rgba(0,0,0,0.05); max-height: calc(100vh - 36px); overflow: auto; } .manual-toc h2 { color: #1F5438; font-size: 14px; margin-bottom: 12px; text-transform: uppercase; letter-spacing: 0; } @@ -68,11 +71,21 @@

+ {% if document_actions %} + + {% endif %} {% if render_error %}