DOCX: read and write the "gutter at top" setting (w:gutterAtTop)

The reader ignored w:gutterAtTop in settings.xml (it was only carried
through on save), so an app using the model could not tell that Word adds
the gutter to the top margin instead of the left one. Add
Settings::gutter_at_top (document-wide, off by default), read it with the
shared on/off helper, write it after w:mirrorMargins and before
w:attachedTemplate, and make the settings merge treat it as a modelled
child so turning it off removes it.

Tests: round trip and default off, every on/off spelling, merge into a
settings part from another writer (keep, remove, insert in schema order).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
vangel76
2026-11-16 00:12:22 +01:00
co-authored by Claude Sonnet 5.5
parent 0eaafeb505
commit fc808abd49
5 changed files with 123 additions and 0 deletions
+1
View File
@@ -56,6 +56,7 @@ impl Reader<'_> {
}
"m:mathPr" => s.math = Some(math::read_math_pr(k)),
"w:mirrorMargins" => s.mirror_margins = on_off(k),
"w:gutterAtTop" => s.gutter_at_top = on_off(k),
"w:autoHyphenation" => s.auto_hyphenation = on_off(k),
"w:doNotHyphenateCaps" => s.hyphenate_caps = !on_off(k),
"w:hyphenationZone" => {
+4
View File
@@ -50,6 +50,10 @@ pub(super) fn settings_xml(doc: &Document, footnotes: bool, endnotes: bool, temp
if s.mirror_margins {
w.empty("w:mirrorMargins", &[]);
}
// CT_Settings order: after `w:mirrorMargins`, before `w:attachedTemplate`.
if s.gutter_at_top {
w.empty("w:gutterAtTop", &[]);
}
if let Some(id) = template_rel {
w.empty("w:attachedTemplate", &[("r:id", id)]);
}
+17
View File
@@ -18,6 +18,7 @@ const OWNED: &[&str] = &[
"w:removeDateAndTime",
"w:displayBackgroundShape",
"w:mirrorMargins",
"w:gutterAtTop",
"w:attachedTemplate",
"w:linkStyles",
"w:trackRevisions",
@@ -386,4 +387,20 @@ mod tests {
assert!(out.contains("<w:compat><w:compatSetting") && out.contains("</w:compat>"), "{out}");
assert!(out.contains("<w:rsidRoot w:val=\"00112233\"/>"), "{out}");
}
#[test]
fn gutter_at_top_comes_from_the_generated_part() {
let orig = r#"<w:settings xmlns:w="w" xmlns:m="m" xmlns:r="r"><w:mirrorMargins/><w:gutterAtTop/><w:proofState w:spelling="clean"/></w:settings>"#;
assert!(has_unowned(orig.as_bytes()));
// Turned off in the model: the original element goes, the foreign one stays.
let out = String::from_utf8(merge(orig.as_bytes(), GEN.as_bytes()).unwrap()).unwrap();
assert!(!out.contains("gutterAtTop") && out.contains("<w:proofState"), "{out}");
// On in the model: written once, in place.
let gen_on = GEN.replace("<w:defaultTabStop", "<w:gutterAtTop/><w:defaultTabStop");
let out = String::from_utf8(merge(orig.as_bytes(), gen_on.as_bytes()).unwrap()).unwrap();
assert_eq!(out.matches("<w:gutterAtTop/>").count(), 1, "{out}");
assert!(out.find("<w:mirrorMargins/>") < out.find("<w:gutterAtTop/>") && out.find("<w:gutterAtTop/>") < out.find("<w:proofState"), "{out}");
// A file whose only extra setting is this one has nothing foreign to keep.
assert!(!has_unowned(br#"<w:settings xmlns:w="w"><w:zoom w:percent="100"/><w:gutterAtTop/></w:settings>"#));
}
}
+96
View File
@@ -2926,3 +2926,99 @@ fn drop_cap_options_round_trip() {
(Some(4), Some(true), None, None)
);
}
/// `word/settings.xml` of a saved package.
fn settings_part(bytes: &[u8]) -> String {
let mut zip = zip::ZipArchive::new(std::io::Cursor::new(bytes)).unwrap();
let mut xml = String::new();
std::io::Read::read_to_string(&mut zip.by_name("word/settings.xml").unwrap(), &mut xml).unwrap();
xml
}
/// Page Setup's "Gutter position: Top" (`w:gutterAtTop`) is a document setting: off by default
/// (no element), written when on after `w:mirrorMargins` and before `w:attachedTemplate`, and
/// read back; the section's own gutter width is untouched.
#[test]
fn gutter_at_top_round_trips_and_is_off_by_default() {
let plain = craft_docx::write(&Document::new()).unwrap();
assert!(!settings_part(&plain).contains("gutterAtTop"));
assert!(!craft_docx::read(&plain).unwrap().settings.gutter_at_top);
let mut d = Document::new();
d.settings.gutter_at_top = true;
d.settings.mirror_margins = true;
d.settings.attached_template = Some("file:///C:/Templates/Report.dotx".into());
d.last_section.gutter = 50.0;
let bytes = craft_docx::write(&d).unwrap();
let xml = settings_part(&bytes);
assert_eq!(xml.matches("<w:gutterAtTop/>").count(), 1, "{xml}");
let at = |tag: &str| xml.find(tag).unwrap_or_else(|| panic!("{tag} missing: {xml}"));
assert!(at("<w:mirrorMargins") < at("<w:gutterAtTop") && at("<w:gutterAtTop") < at("<w:attachedTemplate"), "{xml}");
let back = craft_docx::read(&bytes).unwrap();
assert!(back.settings.gutter_at_top);
assert_eq!(back.last_section.gutter, 50.0);
// Switched off again, the element goes.
let mut off = back;
off.settings.gutter_at_top = false;
assert!(!settings_part(&craft_docx::write(&off).unwrap()).contains("gutterAtTop"));
}
/// Every spelling of the on/off value a file may carry for `w:gutterAtTop`: a bare element is on,
/// a missing element is off (not an explicit "false" that something else would have to undo).
#[test]
fn gutter_at_top_reads_every_value_spelling() {
let plain = craft_docx::write(&Document::new()).unwrap();
let xml = settings_part(&plain);
let zoom = r#"<w:zoom w:percent="100"/>"#;
assert!(xml.contains(zoom), "{xml}");
for (element, expected) in [
("", false),
("<w:gutterAtTop/>", true),
(r#"<w:gutterAtTop w:val="1"/>"#, true),
(r#"<w:gutterAtTop w:val="true"/>"#, true),
(r#"<w:gutterAtTop w:val="on"/>"#, true),
(r#"<w:gutterAtTop w:val="0"/>"#, false),
(r#"<w:gutterAtTop w:val="false"/>"#, false),
(r#"<w:gutterAtTop w:val="off"/>"#, false),
] {
let file = replace_part(&plain, "word/settings.xml", xml.replace(zoom, &format!("{zoom}{element}")).as_bytes());
assert_eq!(craft_docx::read(&file).unwrap().settings.gutter_at_top, expected, "{element:?}");
}
}
/// A settings part from another writer (proofing state, rsids, document variables…) is merged on
/// save, not regenerated: `w:gutterAtTop` stays once where it was, goes when the setting is turned
/// off, and is added at its schema position (after `w:mirrorMargins`, before `w:proofState`) when
/// the file had none.
#[test]
fn gutter_at_top_is_merged_into_a_foreign_settings_part() {
let plain = craft_docx::write(&Document::new()).unwrap();
let xml = settings_part(&plain);
let zoom = r#"<w:zoom w:percent="100"/>"#;
let foreign = |element: &str| {
let extra = format!(
r#"{zoom}<w:mirrorMargins/>{element}<w:proofState w:spelling="clean"/><w:rsids><w:rsidRoot w:val="00A1B2C3"/></w:rsids>"#
);
replace_part(&plain, "word/settings.xml", xml.replace(zoom, &extra).as_bytes())
};
let with = craft_docx::read(&foreign("<w:gutterAtTop/>")).unwrap();
assert!(with.settings.gutter_at_top && with.settings.mirror_margins);
let saved = settings_part(&craft_docx::write(&with).unwrap());
assert_eq!(saved.matches("<w:gutterAtTop/>").count(), 1, "{saved}");
assert!(saved.contains("<w:proofState") && saved.contains("<w:rsidRoot"), "{saved}");
let mut off = with;
off.settings.gutter_at_top = false;
let saved = settings_part(&craft_docx::write(&off).unwrap());
assert!(!saved.contains("gutterAtTop") && saved.contains("<w:proofState"), "{saved}");
let mut on = craft_docx::read(&foreign("")).unwrap();
assert!(!on.settings.gutter_at_top);
on.settings.gutter_at_top = true;
let saved = settings_part(&craft_docx::write(&on).unwrap());
assert_eq!(saved.matches("<w:gutterAtTop/>").count(), 1, "{saved}");
let at = |tag: &str| saved.find(tag).unwrap_or_else(|| panic!("{tag} missing: {saved}"));
assert!(at("<w:mirrorMargins") < at("<w:gutterAtTop") && at("<w:gutterAtTop") < at("<w:proofState"), "{saved}");
}
+5
View File
@@ -80,6 +80,10 @@ pub struct Settings {
pub default_tab: f32,
pub even_odd_headers: bool,
pub mirror_margins: bool,
/// The gutter (`w:gutter` of a section's page margins) is added to the top margin instead of
/// the left one (`w:gutterAtTop`; Page Setup › Gutter position › Top). A document-wide
/// setting: Word keeps it in `settings.xml`, not per section.
pub gutter_at_top: bool,
pub auto_hyphenation: bool,
/// Hyphenation zone (`w:hyphenationZone`), points: a line is hyphenated only when breaking
/// it at a word boundary would leave more than this empty at its end.
@@ -296,6 +300,7 @@ impl Default for Settings {
default_tab: 36.0,
even_odd_headers: false,
mirror_margins: false,
gutter_at_top: false,
auto_hyphenation: false,
hyphenation_zone: DEFAULT_HYPHENATION_ZONE,
hyphenate_caps: true,