diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..0992525 --- /dev/null +++ b/.gitattributes @@ -0,0 +1 @@ +scripts/dev.sh text eol=lf diff --git a/.gitignore b/.gitignore index dc88a1b..55f042d 100644 --- a/.gitignore +++ b/.gitignore @@ -6,4 +6,5 @@ logs/ temp/* !temp/keep.txt .idea +.dev/ # *.py \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md index d7219cd..27f9b37 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -26,7 +26,7 @@ Rules: - **Link it from `index.md`.** Every subdirectory (`barcode-reader/general/`, `barcode-reader/web/configuration/`, `mrz-scanner/general/`, etc.) has an `index.md` that lists every article in that section. A new article with no entry there is orphaned — it exists but no one can navigate to it. Add a bullet there when you add the file, and remove the bullet if you remove the file. - **Internal links use `.html`, not `.md`.** Link to sibling/other articles as `some-page.html` (Jekyll serves the built output), and to a parent-directory archive as `../archive/some-page.html`, etc. A link ending in `.md` will not resolve on the live site. - **Don't add "back to index" links inside articles.** They were deliberately removed repo-wide; the sidebar/index already provides navigation. -- **Images** go through a site variable per product/edition — `{{site.dbr_web_assets}}`, `{{site.dbr_mobile_assets}}`, `{{site.dbr_server_assets}}` (defined in `_config.yml`), pointing at that edition's `assets/` directory. Before referencing an image, confirm the file actually exists at that path — a stale or placeholder filename (e.g. a literal `undefined.png`) will silently 404. +- **Images** go through a site variable — `{{site.assets}}` for shared assets or `{{site.dbr_web_assets}}`, `{{site.dbr_mobile_assets}}`, `{{site.dbr_server_assets}}` for edition assets (defined in `_config.yml`). Before referencing an image, confirm the file actually exists at that path — a stale or placeholder filename (e.g. a literal `undefined.png`) will silently 404. - **Write the answer as a direct statement, not a raw Q&A fragment.** Don't leave phrasing like "Yes — ..." or "This can be expanded ..." floating with no visible question or antecedent above it — the H1 is the question; the body should read as its answer, not as a leftover snippet. - **Don't duplicate a section under a second heading.** If a "what's new"/changelog-style heading and a "how to" heading right below it cover the same ground, merge them. @@ -35,7 +35,13 @@ Rules: - `barcode-reader/general/` — cross-edition Barcode Reader FAQs - `barcode-reader/mobile/`, `barcode-reader/server/`, `barcode-reader/web/` — edition-specific Barcode Reader FAQs, each split into topic subdirectories (`configuration/`, `capabilities/`, `debug/`, `scan-setting/`, etc.) - `mrz-scanner/general/` — MRZ Scanner FAQs -- `license/` — licensing FAQs shared across products +- `barcode-reader/license/`, `mrz-scanner/license/` — published licensing FAQs for each product; shared answer bodies live in `_includes/shared/license/` + +## Shared FAQ answers + +Published FAQs are regular Markdown pages under each product path. For an answer reused across products, keep the frontmatter and question H1 in each page and put only the answer body in `_includes/shared/`; include it with `{% include shared/.md %}`. Edit the include for shared answer changes, and keep each product section’s `index.md` linked to its own page. Do not use filesystem symlinks. The two product license sections share `_includes/shared/license/` for their answers; there is no bare `license/` section. + +The shared offline-registration answer references six screenshots through `{{site.assets}}license/`. Their only source files are in `assets/license/`; do not add copies in either product license directory. ## Archived content (`*/archive/*`) @@ -47,6 +53,12 @@ Directories named `archive` under `barcode-reader/{mobile,server,web}/` hold his If you find yourself wanting to *add* content to an archive directory, it almost certainly belongs in the live directory instead. +## Testing the local site + +The Jekyll layout comes from `Docs-Template-Repo`, not this repository. Install Git and Ruby/Bundler plus `rsync` (Bash) or `robocopy` (PowerShell). From the repo root, run `./scripts/dev.sh` or `./scripts/dev.ps1` to prepare `.dev/DocHome` and serve at `http://localhost:5555/faq/`. The scripts exclude archived FAQ directories and local worktrees from that merged workspace. + +For preparation without a server, use `./scripts/dev.sh --no-serve` or `./scripts/dev.ps1 -NoServe`; rerun the script without that flag to start the server. Use `--no-template-update` / `-NoTemplateUpdate` to reuse the cloned template. Rerun after editing FAQ source because the merged workspace is a copy, then check the changed page in the local site. `.dev/` is generated and Git-ignored; do not edit it as source. + ## Before finishing Run the link checker from the repo root and fix anything it flags in files you touched: diff --git a/README.md b/README.md index 1fc04f5..1fea87d 100644 --- a/README.md +++ b/README.md @@ -10,10 +10,27 @@ See [`AGENTS.md`](AGENTS.md) for the FAQ article structure, frontmatter, linking The site is built with Jekyll using a shared theme/layout maintained in [dynamsoft-docs/Docs-Template-Repo](https://github.com/dynamsoft-docs/Docs-Template-Repo), which this repo doesn't include locally. Pushes to `main` and `preview` trigger the CI workflows in `.github/workflows/main.yml`, which build and sync to production and the preview/testing environment respectively. +For a local preview, install Git, Ruby/Bundler, and rsync (Bash) or robocopy (PowerShell), then run from the repository root: + +```bash +./scripts/dev.sh +``` + +Or on Windows: + +```powershell +./scripts/dev.ps1 +``` + +The scripts clone the shared template's preview branch into `.dev/`, merge it with this FAQ source, install gems, and serve Jekyll at `http://localhost:5555/faq/`. The generated `.dev/` workspace is ignored by Git and omits archived FAQ content and local worktrees. Use `--no-serve` / `-NoServe` to prepare without serving, then rerun without that flag to serve; `--no-template-update` / `-NoTemplateUpdate` reuses the cloned template. Changes to FAQ files require rerunning the script to refresh the merged workspace. + +Shared answers live in `_includes/shared/`. Product FAQ pages retain their own frontmatter and question H1, then include the answer body. The license FAQs are regular pages under `barcode-reader/license/` and `mrz-scanner/license/`; they share `_includes/shared/license/` and preserve their product URLs. Edit shared answer text in the include, not in each page. +The license screenshots are stored once in `assets/license/` and referenced through `site.assets` from the shared answer. Do not copy them into the product license directories. + ## Checking links `check_links.py` crawls the repo's Markdown files and reports broken links. Run it before submitting a change that touches links: ```bash python check_links.py -``` +``` \ No newline at end of file diff --git a/_config.yml b/_config.yml index da7d582..8f4aa09 100644 --- a/_config.yml +++ b/_config.yml @@ -55,15 +55,6 @@ defaults: path: "Hide_Tree_Page.html" values: sitemap: false - - scope: - # license/ is shared content, duplicated at build time under - # /faq/barcode-reader/license/ and /faq/mrz-scanner/license/. Those - # product-scoped URLs are the ones linked from the site and correctly - # highlighted in the sidebar; this bare path has no product context - # for the sidebar to highlight, so keep it out of the sitemap. - path: "license" - values: - sitemap: false - scope: path: "barcode-reader/mobile/capabilities" values: diff --git a/_includes/shared/camera-preview-renders-incorrectly-ios.md b/_includes/shared/camera-preview-renders-incorrectly-ios.md new file mode 100644 index 0000000..cd78030 --- /dev/null +++ b/_includes/shared/camera-preview-renders-incorrectly-ios.md @@ -0,0 +1,100 @@ +## Applicable Products + +This article applies to: + +- Dynamsoft Barcode Reader (DBR) JavaScript SDK (`dynamsoft-barcode-reader-bundle`) 11.6.3000 and earlier +- Dynamsoft Capture Vision (DCV) JavaScript SDK (`dynamsoft-capture-vision-bundle`) 3.6.3000 and earlier + +## Summary + +On iOS 27, switching cameras or changing resolution can make the live camera preview render incorrectly. The exact behavior depends on the SDK version: + +| Version | Behavior | +|---|---| +| DBR 11.4 – 11.6.3000 (DCV 3.4 – 3.6.3000) | The preview renders distorted — squeezed or stretched instead of filling its container. Intermittent: the same switch can render correctly on one attempt and distorted on the next. | +| DBR 11.2 and earlier (DCV 3.2 and earlier) | The preview isn't distorted, but it no longer fits its container — shown at the wrong zoom or size and not extending to the borders. | + +It's reproducible on Safari, Chrome, Edge, and Firefox — all iOS browsers share WebKit's camera implementation, so we suspect the issue originates there rather than in any Dynamsoft SDK. It does not occur on iOS 26. + +> [!NOTE] +> Reported to Apple, but not confirmed as an Apple bug and still open as of iOS 27 RC. Details here may change if Apple ships a fix. + +
+
+ Camera video rendering correctly on iOS +
Expected
+
+
+ Camera video rendering distorted after switching cameras on iOS 27 +
Distorted after switching cameras
+
+
+ +## Resolution + +### Recommended: upgrade + +Upgrade to `dynamsoft-barcode-reader-bundle` **11.6.3200+** or `dynamsoft-capture-vision-bundle` **3.6.3200+**, which include a built-in workaround. + +### If you can't upgrade yet + +Both workarounds below are temporary and version-specific — neither replaces upgrading. + +**DBR 11.4 – 11.6.3000 (DCV 3.4 – 3.6.3000)** + +The distortion requires `object-fit: fill` on the video element plus an ancestor using `display: flex` with `flex: 0 0 auto`, so overriding `object-fit` with `cover` on the `