rwml 0.1.0

Native Rust toolkit for Microsoft Word — read, write, edit, and render legacy .doc (Word 97-2003, [MS-DOC]) and modern .docx (OOXML): one document model, package-preserving edits, field evaluation, Markdown/HTML export, PDF preview
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70

# Contributing to rwml

Thanks for your interest in improving `rwml` — a native Rust toolkit for
Microsoft Word documents (**read**, **write**, **edit**, **render**) covering
both legacy `.doc` (Word 97–2003 binary, [MS-DOC]) and modern `.docx`
(OOXML WordprocessingML, [ECMA-376]).

## Ground rules

- **No `unsafe`.** The crate is `#![forbid(unsafe_code)]`. Parsing untrusted
  files must never crash a host process — every byte access is bounds-checked,
  and malformed or hostile input must surface as an `Error` value or read-only
  diagnostics, never a panic.
- **Preserve before interpreting.** `.docx` edits mutate live WordprocessingML
  element trees and reserialize **only** touched parts; a no-op open→save is
  part-payload byte-stable. Don't regress package preservation.
- **Deterministic output.** Field evaluation and rendering must be deterministic
  and source-order stable.
- **Document every public item.** The crate denies `missing_docs`.
- **Keep dependencies minimal.** The legacy-`.doc` core depends only on `cfb`,
  `encoding_rs`, and `thiserror`; the default `docx` feature adds `zip`,
  `quick-xml`, and `flate2`, and the opt-in `render` feature adds `parley` and
  `krilla` (raising the MSRV to 1.92). New dependencies need a strong
  justification.
- **Follow the spec.** `.doc` behaviour should trace to [MS-DOC] / [MS-CFB] and
  `.docx` behaviour to [ECMA-376]; cite the relevant section in comments when
  implementing format details.

## Before opening a PR

Run the local gate (all must pass clean). The default gate covers the `docx`
feature:

```sh
cargo fmt --all -- --check
cargo clippy --all-targets -- -D warnings
cargo test --all-targets
cargo doc --no-deps
```

If you touch the renderer, also run the `render`-gated build (MSRV 1.92):

```sh
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-targets --features render
```

## Tests

- `.doc` unit tests build minimal valid OLE2/`.doc` files in memory so the
  parser is exercised end-to-end without binary fixtures; `.docx` tests drive
  the public API (`Document::open`, `fields()`, `write_docx`, …) and the
  synthetic public corpus under `corpus/public/`.
- Use TDD (a red test first) for behaviour changes. When fixing a real-world
  file, add a focused regression test that captures the structural quirk (piece
  table shape, encoding, control marks, element layout) rather than committing a
  private or binary document. Use only synthetic or clearly public corpus files.

## Scope

`rwml` reads, writes, edits, and renders both `.doc` and `.docx` into one shared
`DocModel`. Most remaining work is deeper compatibility — field semantics,
layout/rendering fidelity, additional fixtures, and validation depth — rather
than new top-level APIs; see the roadmap in the [README](README.md#roadmap).
Preview-grade rendering is not a LibreOffice/Word replacement, and layout-exact
pagination is intentionally out of scope.

[MS-DOC]: https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-doc/
[MS-CFB]: https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-cfb/
[ECMA-376]: https://ecma-international.org/publications-and-standards/standards/ecma-376/