Merge pull request #1776 from vangel76/fix/gutter-at-top

The "gutter at top" page setting in Word files is now read and saved
This commit is contained in:
Dylan M. Taylor authored and GitHub committed 2026-11-16 16:11:33 -05:00
commit 09cae32c45
5 files changed
+126

No files matched your search

+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)]);
}
+19
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,22 @@ 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:mirrorMargins/><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}");
let at = |tag: &str| out.find(tag).unwrap_or_else(|| panic!("{tag} missing: {out}"));
assert!(at("<w:mirrorMargins/>") < at("<w:gutterAtTop/>") && at("<w:gutterAtTop/>") < at("<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>"#));
}
}
+97
View File
@@ -2928,3 +2928,100 @@ 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),
(r#"<w:gutterAtTop w:val="False"/>"#, false),
(r#"<w:gutterAtTop w:val="FALSE"/>"#, 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,