poka.sh

 Docs

Honesty in output

explanation

A preview is read by someone deciding what a file is. A guess that looks like a fact is worse than saying you do not know. This page explains the rules a parser follows and why.

Say what you did not decode

  • Label assumptions. A format that declares no encoding is reported as Windows-1250 (assumed) or legacy double-byte (titles not decoded), not as decoded text with mojibake in it.
  • Do not imply structure you did not decode. A parser that recovers block names by scanning for printable runs labels the section N found by text scan. The record layout is undocumented, and the output says so.
  • Report undocumented regions as a size, not as invented fields.
  • Surface contradictions and do not pick a side. When a file's extension and its declared media type disagree, show both.
  • Distinguish absent from empty. A nil value is not an empty string. A variable declared but never written is not zero.

Say when you cut the output

A preview is capped. Set truncated when you stop early, and expand a record only if the whole record fits, because a half-expanded record reads as data loss. Fail with a message that names what the file is:

not a SANKOM Audytor file — this is a PDF document, saved with a .ekd extension

not with parse error. Never show a fake preview to cover a failure.

Never decrypt

When content is encrypted or DRM-protected (password-protected archives and office files, encrypted PDFs, encrypted library assets), do not guess keys, reverse the cipher or brute-force passwords. The content is licensed or private. Read only what is stored in the clear (headers, sizes, names) and say plainly that the rest is encrypted and not decoded. This applies to research and issues too, not only to parser code.

Honesty in numbers

When a document, issue or PR quotes a figure, say whether it was measured (by which command, at which commit) or estimated. Do not copy a figure from one document into another by hand. Point at the generator instead (scripts/format-stats.py, scripts/kpi-stats.py).

Why

The reader cannot see the file's bytes. The preview is their only evidence, so every claim in it must be one the parser can back.

See also