Problem
ParsingFailedBlock.raw is the only retained representation of input the parser could not model. The writer currently prepends a generated warning comment to that source by default. On the next parse, the warning becomes an ordinary implicit comment; writing again adds another warning. Repeated read/write cycles therefore accumulate generated content even when the user changes nothing.
There is also no fail-closed writer mode for applications that must refuse export while any parse failure remains.
Proposed policy
Add an explicit BibtexFormat.failed_block_policy with three values:
"preserve" (proposed default): write retained raw failed blocks unchanged;"annotate": prepend the configured diagnostic, while recognizing and replacing an identical existing annotation so repeated cycles are idempotent; and"raise": refuse to write if the library contains any failed block, reporting all failures together.
An unknown policy must raise immediately. Failed blocks without raw source remain unwritable under every policy. There should be no silent discard mode.
This setting applies only to failed blocks. Normal parsed blocks must continue to serialize from their current model state because their cached raw source may be stale after middleware or user edits.
Compatibility
Changing the default from annotation to preservation is intentional but user-visible. The former behavior remains available as "annotate", and strict applications gain "raise". The documentation should call out the change and the fact that canonical writing is not a byte-identical concrete-syntax editor for normal blocks.
The configurable annotation text is already tracked by #530 / PR #566. A standalone implementation of this proposal may carry that fix as a clearly separated prerequisite until it merges.
Problem
ParsingFailedBlock.rawis the only retained representation of input the parser could not model. The writer currently prepends a generated warning comment to that source by default. On the next parse, the warning becomes an ordinary implicit comment; writing again adds another warning. Repeated read/write cycles therefore accumulate generated content even when the user changes nothing.There is also no fail-closed writer mode for applications that must refuse export while any parse failure remains.
Proposed policy
Add an explicit
BibtexFormat.failed_block_policywith three values:"preserve"(proposed default): write retained raw failed blocks unchanged;"annotate": prepend the configured diagnostic, while recognizing and replacing an identical existing annotation so repeated cycles are idempotent; and"raise": refuse to write if the library contains any failed block, reporting all failures together.An unknown policy must raise immediately. Failed blocks without raw source remain unwritable under every policy. There should be no silent discard mode.
This setting applies only to failed blocks. Normal parsed blocks must continue to serialize from their current model state because their cached raw source may be stale after middleware or user edits.
Compatibility
Changing the default from annotation to preservation is intentional but user-visible. The former behavior remains available as
"annotate", and strict applications gain"raise". The documentation should call out the change and the fact that canonical writing is not a byte-identical concrete-syntax editor for normal blocks.The configurable annotation text is already tracked by #530 / PR #566. A standalone implementation of this proposal may carry that fix as a clearly separated prerequisite until it merges.