imprimatur 0.2.0 → 0.3.0

data/ext/imprimatur_native/core/src/doc/picture.rs

@@ -0,0 +1,192 @@
+//! Pictures: PNG or JPEG files, read once for what PDF and DOCX need.
+
+use std::sync::Arc;
+
+use crate::style::Align;
+use crate::{Error, Result};
+
+/// Pixels per point at 96 pixels an inch: a picture's size when none is set.
+const POINTS_PER_PIXEL: f64 = 0.75;
+/// The largest side, in points, a picture may be set to: PDF's page limit.
+const MAX_POINTS: f64 = 14_400.0;
+/// The largest side, in pixels, a picture may have.
+const MAX_PIXELS: u32 = 1 << 16;
+
+/// A PNG or JPEG drawn in the document's flow.
+///
+/// It is drawn at the width or height set (in points, the other following
+/// its proportions), or else at 96 pixels an inch, never larger than the
+/// page leaves room for.
+///
+/// ```no_run
+/// use imprimatur::doc::{Document, Picture};
+/// use imprimatur::style::Align;
+///
+/// let mut doc = Document::new();
+/// doc.picture(Picture::new(std::fs::read("logo.png")?)?.width(144.0)?.align(Align::Center));
+/// # Ok::<(), imprimatur::Error>(())
+/// ```
+#[derive(Debug, Clone, PartialEq)]
+pub struct Picture {
+    pub(crate) data: Arc<[u8]>,
+    pub(crate) kind: Kind,
+    pub(crate) pixels: (u32, u32),
+    width: Option<f64>,
+    height: Option<f64>,
+    pub(crate) align: Option<Align>,
+}
+
+/// The format, and what writing it takes.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum Kind {
+    Png(Png),
+    /// Gray (1), RGB (3) or CMYK (4) components; Adobe's CMYK is inverted.
+    Jpeg {
+        components: u8,
+        inverted: bool,
+    },
+}
+
+/// A PNG's pixel layout and its compressed pixels (its `IDAT` chunks).
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Png {
+    pub depth: u8,
+    /// 0 gray, 2 RGB, 3 palette, 4 gray and alpha, 6 RGB and alpha.
+    pub color: u8,
+    pub palette: Vec<u8>,
+    /// The `tRNS` chunk: a palette's alphas, or the transparent color.
+    pub transparency: Vec<u8>,
+    pub compressed: Vec<u8>,
+}
+
+impl Picture {
+    /// # Errors
+    /// [`Error::InvalidImage`] for data that is no PNG or JPEG, a damaged
+    /// one, an interlaced PNG, a JPEG other than 8 bits a sample, or one
+    /// larger than 65 536 pixels a side.
+    pub fn new(data: impl Into<Vec<u8>>) -> Result<Self> {
+        let data: Arc<[u8]> = data.into().into();
+        let (kind, pixels) = if data.starts_with(b"\x89PNG\r\n\x1a\n") {
+            png(&data)?
+        } else if data.starts_with(&[0xFF, 0xD8, 0xFF]) {
+            jpeg(&data)?
+        } else {
+            return Err(Error::InvalidImage("not a PNG or JPEG image"));
+        };
+        let valid = (1..=MAX_PIXELS).contains(&pixels.0) && (1..=MAX_PIXELS).contains(&pixels.1);
+        valid.ok_or(Error::InvalidImage("a picture of 1 to 65 536 pixels a side"))?;
+        Ok(Self { data, kind, pixels, width: None, height: None, align: None })
+    }
+
+    /// Its width in points; the height follows unless set too.
+    ///
+    /// # Errors
+    /// [`Error::InvalidImage`] outside 1 to 14 400 points.
+    pub fn width(mut self, points: f64) -> Result<Self> {
+        self.width = Some(points_in_range(points)?);
+        Ok(self)
+    }
+
+    /// Its height in points; the width follows unless set too.
+    ///
+    /// # Errors
+    /// [`Error::InvalidImage`] outside 1 to 14 400 points.
+    pub fn height(mut self, points: f64) -> Result<Self> {
+        self.height = Some(points_in_range(points)?);
+        Ok(self)
+    }
+
+    #[must_use]
+    pub const fn align(mut self, align: Align) -> Self {
+        self.align = Some(align);
+        self
+    }
+
+    /// The size it is drawn at, in points, fitted into `room` (the width
+    /// and height between the margins).
+    pub(crate) fn size(&self, room: (f64, f64)) -> (f64, f64) {
+        let (pixels_wide, pixels_high) = (f64::from(self.pixels.0), f64::from(self.pixels.1));
+        let (width, height) = match (self.width, self.height) {
+            (Some(width), Some(height)) => (width, height),
+            (Some(width), None) => (width, width * pixels_high / pixels_wide),
+            (None, Some(height)) => (height * pixels_wide / pixels_high, height),
+            (None, None) => (pixels_wide * POINTS_PER_PIXEL, pixels_high * POINTS_PER_PIXEL),
+        };
+        let scale = (room.0 / width).min(room.1 / height).min(1.0);
+        (width * scale, height * scale)
+    }
+}
+
+fn points_in_range(points: f64) -> Result<f64> {
+    (1.0..=MAX_POINTS)
+        .contains(&points)
+        .then_some(points)
+        .ok_or(Error::InvalidImage("a picture of 1 to 14 400 points a side"))
+}
+
+/// A PNG's chunks; interlaced ones are refused.
+fn png(data: &[u8]) -> Result<(Kind, (u32, u32))> {
+    let damaged = || Error::InvalidImage("a damaged PNG");
+    let mut png = Png {
+        depth: 0,
+        color: 0,
+        palette: Vec::new(),
+        transparency: Vec::new(),
+        compressed: Vec::new(),
+    };
+    let (mut pixels, mut at) = (None, 8);
+    while let Some(head) = data.get(at..at + 8) {
+        let length = u32::from_be_bytes([head[0], head[1], head[2], head[3]]) as usize;
+        let body = data.get(at + 8..at + 8 + length).ok_or_else(damaged)?;
+        match &head[4..8] {
+            b"IHDR" if body.len() == 13 => {
+                let side = |at: usize| {
+                    u32::from_be_bytes([body[at], body[at + 1], body[at + 2], body[at + 3]])
+                };
+                pixels = Some((side(0), side(4)));
+                (png.depth, png.color) = (body[8], body[9]);
+                (body[12] == 0).ok_or(Error::InvalidImage("an interlaced PNG"))?;
+            }
+            b"PLTE" => png.palette = body.to_vec(),
+            b"tRNS" => png.transparency = body.to_vec(),
+            b"IDAT" => png.compressed.extend_from_slice(body),
+            b"IEND" => break,
+            _ => {}
+        }
+        at += 12 + length;
+    }
+    let layout = matches!(
+        (png.color, png.depth),
+        (0, 1 | 2 | 4 | 8 | 16) | (3, 1 | 2 | 4 | 8) | (2 | 4 | 6, 8 | 16)
+    );
+    let palette = png.color != 3 || !png.palette.is_empty();
+    let pixels = pixels.filter(|_| layout && palette && !png.compressed.is_empty());
+    Ok((Kind::Png(png), pixels.ok_or_else(damaged)?))
+}
+
+/// A JPEG's frame header (`SOF`), and Adobe's mark, which inverts CMYK.
+fn jpeg(data: &[u8]) -> Result<(Kind, (u32, u32))> {
+    let damaged = || Error::InvalidImage("a damaged JPEG");
+    let (mut at, mut inverted) = (2, false);
+    loop {
+        let &[0xFF, marker, high, low] = data.get(at..at + 4).ok_or_else(damaged)? else {
+            return Err(damaged());
+        };
+        let length = usize::from(u16::from_be_bytes([high, low]));
+        if marker == 0xEE && data.get(at + 4..at + 9) == Some(b"Adobe") {
+            inverted = true;
+        }
+        // SOF0 to SOF15, but DHT, JPG and DAC share the range.
+        if (0xC0..=0xCF).contains(&marker) && !matches!(marker, 0xC4 | 0xC8 | 0xCC) {
+            let frame = data.get(at + 4..at + 10).ok_or_else(damaged)?;
+            (frame[0] == 8).ok_or(Error::InvalidImage("a JPEG of 8 bits a sample"))?;
+            let height = u32::from(u16::from_be_bytes([frame[1], frame[2]]));
+            let width = u32::from(u16::from_be_bytes([frame[3], frame[4]]));
+            let components = frame[5];
+            matches!(components, 1 | 3 | 4).ok_or_else(damaged)?;
+            let kind = Kind::Jpeg { components, inverted: inverted && components == 4 };
+            return Ok((kind, (width, height)));
+        }
+        at += 2 + length;
+    }
+}

data/ext/imprimatur_native/core/src/doc/table.rs

@@ -1,5 +1,12 @@
+use crate::script::Counts;
+use crate::style::TextDirection;
+
 /// A grid of text cells; columns share the page width equally. Short rows
 /// are padded with empty cells.
+///
+/// Each cell reads in the direction of its first letter, a cell of figures
+/// in the table's; a table mostly right to left has its first column on the
+/// right.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct Table {
     pub(crate) rows: Vec<Vec<String>>,
@@ -38,4 +45,18 @@ impl Table {
     pub(crate) const fn has_header(&self) -> bool {
         self.header
     }
+
+    /// The direction most of the table's letters read in; `None` without a
+    /// letter.
+    pub(crate) fn direction(&self) -> Option<TextDirection> {
+        let mut counts = Counts::default();
+        self.count(&mut counts);
+        counts.direction()
+    }
+
+    pub(crate) fn count(&self, counts: &mut Counts) {
+        for cell in self.rows.iter().flatten() {
+            counts.add(cell);
+        }
+    }
 }

data/ext/imprimatur_native/core/src/doc.rs

@@ -22,6 +22,7 @@
 //! ```
 
 mod paragraph;
+pub(crate) mod picture;
 mod table;
 #[cfg(test)]
 mod tests;
@@ -31,24 +32,49 @@ use std::io::{BufWriter, Write};
 use std::path::Path;
 
 pub use paragraph::{Paragraph, Run};
+pub use picture::Picture;
 pub use table::Table;
 
+use crate::script::Counts;
 use crate::{Error, Result};
 
-/// Paper size; pages are portrait.
+/// Paper size; A4 and Letter pages are portrait.
 #[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
 pub enum PageSize {
     #[default]
     A4,
     Letter,
+    /// Width and height in hundredths of a point; see [`PageSize::custom`].
+    Custom(u32, u32),
 }
 
 impl PageSize {
+    /// A page of this width and height, in points (1/72 inch): 36 to 1584
+    /// (half an inch to 22 inches), as both PDF and Word take them.
+    ///
+    /// # Errors
+    /// [`Error::InvalidPageSize`] outside that range.
+    pub fn custom(width: f64, height: f64) -> Result<Self> {
+        let side = |points: f64| {
+            #[expect(
+                clippy::cast_possible_truncation,
+                clippy::cast_sign_loss,
+                reason = "36 to 1584"
+            )]
+            (36.0..=1584.0).contains(&points).then(|| (points * 100.0).round() as u32)
+        };
+        side(width)
+            .zip(side(height))
+            .map(|(width, height)| Self::Custom(width, height))
+            .ok_or(Error::InvalidPageSize(width, height))
+    }
+
     /// Width and height in PDF points (1/72 inch).
-    pub(crate) const fn points(self) -> (f64, f64) {
+    pub(crate) fn points(self) -> (f64, f64) {
         match self {
             Self::A4 => (595.276, 841.89),
             Self::Letter => (612.0, 792.0),
+            Self::Custom(width, height) => (f64::from(width) / 100.0, f64::from(height) / 100.0),
         }
     }
 
@@ -57,6 +83,7 @@ impl PageSize {
         match self {
             Self::A4 => (11_906, 16_838),
             Self::Letter => (12_240, 15_840),
+            Self::Custom(width, height) => (width / 5, height / 5),
         }
     }
 }
@@ -68,6 +95,7 @@ pub enum Block {
     Heading { level: u8, text: String },
     Paragraph(Paragraph),
     Table(Table),
+    Picture(Picture),
     PageBreak,
 }
 
@@ -78,6 +106,8 @@ pub struct Document {
     blocks: Vec<Block>,
     page_size: PageSize,
     page_numbers: bool,
+    /// Hundredths of a point; one inch when unset.
+    margin: Option<u32>,
 }
 
 impl Document {
@@ -91,6 +121,43 @@ impl Document {
         self
     }
 
+    /// The margin on every side, in points: one inch (72) unless set.
+    ///
+    /// # Errors
+    /// [`Error::InvalidMargin`] outside 0 to 144 points.
+    pub fn set_margin(&mut self, points: f64) -> Result<&mut Self> {
+        #[expect(clippy::cast_possible_truncation, clippy::cast_sign_loss, reason = "0 to 144")]
+        let margin = (0.0..=144.0)
+            .contains(&points)
+            .then(|| (points * 100.0).round() as u32)
+            .ok_or(Error::InvalidMargin(points))?;
+        self.margin = Some(margin);
+        Ok(self)
+    }
+
+    /// The margin on every side, in points.
+    #[must_use]
+    pub fn margin(&self) -> f64 {
+        self.margin.map_or(72.0, |margin| f64::from(margin) / 100.0)
+    }
+
+    /// The width and height between the margins, in points.
+    ///
+    /// # Errors
+    /// [`Error::InvalidMargin`] when the margins leave no room.
+    pub(crate) fn room(&self) -> Result<(f64, f64)> {
+        let (width, height) = self.page_size.points();
+        let margin = self.margin();
+        let room = (2.0f64.mul_add(-margin, width), 2.0f64.mul_add(-margin, height));
+        (room.0 >= 1.0 && room.1 >= 1.0).then_some(room).ok_or(Error::InvalidMargin(margin))
+    }
+
+    /// A picture, in the flow of the text.
+    pub fn picture(&mut self, picture: Picture) -> &mut Self {
+        self.blocks.push(Block::Picture(picture));
+        self
+    }
+
     /// Numbers pages `1 / 3` at the bottom of each one.
     pub const fn set_page_numbers(&mut self, enabled: bool) -> &mut Self {
         self.page_numbers = enabled;
@@ -144,6 +211,23 @@ impl Document {
         self
     }
 
+    /// Whether most of the document's letters are right to left: its pages
+    /// are then laid out right to left.
+    pub(crate) fn reads_right_to_left(&self) -> bool {
+        let mut counts = Counts::default();
+        for block in &self.blocks {
+            match block {
+                Block::Heading { text, .. } => counts.add(text),
+                Block::Paragraph(paragraph) => {
+                    paragraph.runs.iter().for_each(|run| counts.add(&run.text));
+                }
+                Block::Table(table) => table.count(&mut counts),
+                Block::Picture(_) | Block::PageBreak => {}
+            }
+        }
+        counts.right_to_left()
+    }
+
     #[must_use]
     pub fn blocks(&self) -> &[Block] {
         &self.blocks

data/ext/imprimatur_native/core/src/docx/picture.rs

@@ -0,0 +1,72 @@
+//! Pictures as inline drawings, their files in `word/media`.
+
+use crate::doc::Picture;
+use crate::doc::picture::Kind;
+use crate::xml::XmlWriter;
+
+pub const WP_NS: &str = "http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing";
+pub const A_NS: &str = "http://schemas.openxmlformats.org/drawingml/2006/main";
+pub const PIC_NS: &str = "http://schemas.openxmlformats.org/drawingml/2006/picture";
+/// English Metric Units a point, as drawings measure.
+const EMU_PER_POINT: f64 = 12_700.0;
+
+/// Its file's extension.
+pub const fn extension(picture: &Picture) -> &'static str {
+    match picture.kind {
+        Kind::Png(_) => "png",
+        Kind::Jpeg { .. } => "jpeg",
+    }
+}
+
+/// Its part in `word/media`, by its number from 1.
+pub fn file_name(picture: &Picture, number: usize) -> String {
+    format!("media/image{number}.{}", extension(picture))
+}
+
+/// A paragraph holding picture `number`, its file `relationship`, at its
+/// size within `room`.
+pub fn paragraph(
+    xml: &mut XmlWriter,
+    picture: &Picture,
+    room: (f64, f64),
+    number: usize,
+    relationship: &str,
+) {
+    let (width, height) = picture.size(room);
+    #[expect(clippy::cast_possible_truncation, clippy::cast_sign_loss, reason = "under 2**31")]
+    let emu = |points: f64| ((points * EMU_PER_POINT).round() as u64).to_string();
+    let (cx, cy, id, name) =
+        (emu(width), emu(height), number.to_string(), format!("Picture {number}"));
+    let extent = [("cx", cx.as_str()), ("cy", cy.as_str())];
+    super::open_paragraph(xml, None, false, picture.align);
+    xml.open("w:r", &[]);
+    xml.open("w:drawing", &[]);
+    xml.open("wp:inline", &[("distT", "0"), ("distB", "0"), ("distL", "0"), ("distR", "0")]);
+    xml.empty("wp:extent", &extent);
+    xml.empty("wp:docPr", &[("id", &id), ("name", &name)]);
+    xml.open("a:graphic", &[]);
+    xml.open("a:graphicData", &[("uri", PIC_NS)]);
+    xml.open("pic:pic", &[]);
+    xml.open("pic:nvPicPr", &[]);
+    xml.empty("pic:cNvPr", &[("id", &id), ("name", &name)]);
+    xml.empty("pic:cNvPicPr", &[]);
+    xml.close("pic:nvPicPr");
+    xml.open("pic:blipFill", &[]);
+    xml.empty("a:blip", &[("r:embed", relationship)]);
+    xml.open("a:stretch", &[]);
+    xml.empty("a:fillRect", &[]);
+    xml.close("a:stretch");
+    xml.close("pic:blipFill");
+    xml.open("pic:spPr", &[]);
+    xml.open("a:xfrm", &[]);
+    xml.empty("a:off", &[("x", "0"), ("y", "0")]);
+    xml.empty("a:ext", &extent);
+    xml.close("a:xfrm");
+    xml.open("a:prstGeom", &[("prst", "rect")]);
+    xml.empty("a:avLst", &[]);
+    xml.close("a:prstGeom");
+    xml.close("pic:spPr");
+    for tag in ["pic:pic", "a:graphicData", "a:graphic", "wp:inline", "w:drawing", "w:r", "w:p"] {
+        xml.close(tag);
+    }
+}

data/ext/imprimatur_native/core/src/docx.rs

@@ -2,13 +2,14 @@
 //! Word paragraphs, runs and tables, with real Heading 1-3 styles so Word's
 //! navigation pane and table of contents see them.
 
+mod picture;
 #[cfg(test)]
 mod tests;
 
 use std::io::Write;
 
 use crate::Result;
-use crate::doc::{Block, Document, Paragraph, Run, Table};
+use crate::doc::{Block, Document, Paragraph, Picture, Run, Table};
 use crate::opc;
 use crate::style::{Align, Color, TextDirection};
 use crate::xml::XmlWriter;
@@ -16,39 +17,58 @@ use crate::zip::ZipWriter;
 
 const W_NS: &str = "http://schemas.openxmlformats.org/wordprocessingml/2006/main";
 const WORD_TYPE: &str = "application/vnd.openxmlformats-officedocument.wordprocessingml";
-/// One inch, Word's default margin, in twips.
-const MARGIN: u32 = 1_440;
 /// A header row's shading.
 const HEADER_FILL: &str = "D9E2F3";
 
 pub fn write<W: Write>(document: &Document, out: W) -> Result<W> {
+    let room = document.room()?;
     let footer = document.has_page_numbers();
-    let mut parts = vec![("styles", "styles.xml")];
+    let mut parts = vec![("styles", "styles.xml".to_owned())];
     if footer {
-        parts.push(("footer", "footer1.xml"));
+        parts.push(("footer", "footer1.xml".to_owned()));
+    }
+    // Pictures' files follow, their relationships numbered from here.
+    let first_media = parts.len() + 1;
+    let pictures: Vec<&Picture> = document
+        .blocks()
+        .iter()
+        .filter_map(|block| if let Block::Picture(picture) = block { Some(picture) } else { None })
+        .collect();
+    for (number, picture) in (1..).zip(&pictures) {
+        parts.push(("image", picture::file_name(picture, number)));
     }
     let mut zip = ZipWriter::new(out);
-    zip.add("[Content_Types].xml", content_types(footer).as_bytes())?;
+    zip.add("[Content_Types].xml", content_types(footer, &pictures).as_bytes())?;
     let package = opc::relationships(&[("officeDocument", "word/document.xml")]);
     zip.add("_rels/.rels", package.as_bytes())?;
-    zip.add("word/document.xml", body(document).as_bytes())?;
+    zip.add("word/document.xml", body(document, room, first_media).as_bytes())?;
     zip.add("word/_rels/document.xml.rels", opc::relationships(&parts).as_bytes())?;
     zip.add("word/styles.xml", styles().as_bytes())?;
     if footer {
         zip.add("word/footer1.xml", page_number_footer().as_bytes())?;
     }
+    for (number, picture) in (1..).zip(&pictures) {
+        zip.add(&format!("word/{}", picture::file_name(picture, number)), &picture.data)?;
+    }
     zip.finish()
 }
 
-/// One override per part: the document, its styles and the footer.
-fn content_types(footer: bool) -> String {
+/// One override per part: the document, its styles and the footer; the
+/// pictures' types by extension.
+fn content_types(footer: bool, pictures: &[&Picture]) -> String {
     let mut parts = vec![("/word/document.xml", "document.main"), ("/word/styles.xml", "styles")];
     if footer {
         parts.push(("/word/footer1.xml", "footer"));
     }
     let overrides: Vec<(&str, String)> =
         parts.into_iter().map(|(part, kind)| (part, format!("{WORD_TYPE}.{kind}+xml"))).collect();
-    opc::content_types(&[], &overrides)
+    let mut defaults = Vec::new();
+    for (extension, content_type) in [("png", "image/png"), ("jpeg", "image/jpeg")] {
+        if pictures.iter().any(|picture| picture::extension(picture) == extension) {
+            defaults.push((extension, content_type));
+        }
+    }
+    opc::content_types(&defaults, &overrides)
 }
 
 /// `word/footer1.xml`: a centered `PAGE / NUMPAGES`, which Word computes.
@@ -82,18 +102,34 @@ fn page_number_footer() -> String {
     xml.finish()
 }
 
-fn body(document: &Document) -> String {
+fn body(document: &Document, room: (f64, f64), first_media: usize) -> String {
+    // What reads in no direction of its own (figures, punctuation) takes the
+    // document's.
+    let rtl = document.reads_right_to_left();
     let mut xml = XmlWriter::new();
-    xml.open("w:document", &[("xmlns:w", W_NS), ("xmlns:r", opc::RELATIONSHIPS)]);
+    let namespaces = [
+        ("xmlns:w", W_NS),
+        ("xmlns:r", opc::RELATIONSHIPS),
+        ("xmlns:wp", picture::WP_NS),
+        ("xmlns:a", picture::A_NS),
+        ("xmlns:pic", picture::PIC_NS),
+    ];
+    xml.open("w:document", &namespaces);
     xml.open("w:body", &[]);
+    let mut pictures = 0;
     for block in document.blocks() {
         match block {
             Block::Heading { level, text } => {
                 let style = format!("Heading{level}");
-                simple_paragraph(&mut xml, Some(&style), text, Look::default());
+                simple_paragraph(&mut xml, Some(&style), text, Look::default(), rtl);
+            }
+            Block::Paragraph(content) => paragraph(&mut xml, content, rtl),
+            Block::Table(content) => table(&mut xml, content, document, rtl),
+            Block::Picture(content) => {
+                pictures += 1;
+                let relationship = format!("rId{}", first_media + pictures - 1);
+                picture::paragraph(&mut xml, content, room, pictures, &relationship);
             }
-            Block::Paragraph(content) => paragraph(&mut xml, content),
-            Block::Table(content) => table(&mut xml, content, document),
             Block::PageBreak => {
                 xml.open("w:p", &[]);
                 xml.open("w:r", &[]);
@@ -107,25 +143,37 @@ fn body(document: &Document) -> String {
     if matches!(document.blocks().last(), Some(Block::Table(_))) {
         xml.empty("w:p", &[]);
     }
-    section(&mut xml, document);
+    section(&mut xml, document, rtl);
     xml.close("w:body");
     xml.close("w:document");
     xml.finish()
 }
 
-fn paragraph(xml: &mut XmlWriter, content: &Paragraph) {
-    let rtl = content.direction == Some(TextDirection::RightToLeft);
+/// Each run reads in the direction of its own first letter, as Word sets
+/// them: the Latin runs of a Hebrew paragraph left to right, the Arabic
+/// ones of an English paragraph right to left.
+fn paragraph(xml: &mut XmlWriter, content: &Paragraph, document_rtl: bool) {
+    let rtl = right_to_left(content.effective_direction(), document_rtl);
     open_paragraph(xml, None, rtl, content.align);
     for item in &content.runs {
-        run(xml, &item.text, Look::of(item), rtl);
+        run(xml, &item.text, Look::of(item), right_to_left(TextDirection::of(&item.text), rtl));
     }
     xml.close("w:p");
 }
 
-/// A one-run paragraph straight from borrowed text: headings and table cells.
-fn simple_paragraph(xml: &mut XmlWriter, style: Option<&str>, text: &str, look: Look) {
-    open_paragraph(xml, style, false, None);
-    run(xml, text, look, false);
+/// Whether `direction` is right to left; `otherwise` when there is none:
+/// text with no letter (figures, punctuation) takes the direction of what
+/// holds it.
+fn right_to_left(direction: Option<TextDirection>, otherwise: bool) -> bool {
+    direction.map_or(otherwise, |direction| direction == TextDirection::RightToLeft)
+}
+
+/// A one-run paragraph straight from borrowed text: headings and table
+/// cells, in the direction of their first letter, or of what holds them.
+fn simple_paragraph(xml: &mut XmlWriter, style: Option<&str>, text: &str, look: Look, rtl: bool) {
+    let rtl = right_to_left(TextDirection::of(text), rtl);
+    open_paragraph(xml, style, rtl, None);
+    run(xml, text, look, rtl);
     xml.close("w:p");
 }
 
@@ -207,16 +255,20 @@ fn run(xml: &mut XmlWriter, text: &str, look: Look, rtl: bool) {
     xml.close("w:r");
 }
 
-fn table(xml: &mut XmlWriter, content: &Table, document: &Document) {
+fn table(xml: &mut XmlWriter, content: &Table, document: &Document, document_rtl: bool) {
+    let rtl = right_to_left(content.direction(), document_rtl);
     let columns = content.columns();
     let (page_width, _) = document.page_size().twips();
-    let usable = page_width - 2 * MARGIN;
+    let usable = page_width - 2 * margin(document);
     // Never 0: a table has at least one column.
     let column_width = (usable / u32::try_from(columns).unwrap_or(1).max(1)).to_string();
 
     xml.open("w:tbl", &[]);
     xml.open("w:tblPr", &[]);
     xml.empty("w:tblStyle", &[("w:val", "TableGrid")]);
+    if rtl {
+        xml.empty("w:bidiVisual", &[]);
+    }
     xml.empty("w:tblW", &[("w:w", "5000"), ("w:type", "pct")]);
     xml.close("w:tblPr");
     xml.open("w:tblGrid", &[]);
@@ -244,7 +296,7 @@ fn table(xml: &mut XmlWriter, content: &Table, document: &Document) {
             }
             xml.close("w:tcPr");
             let text = row.get(column).map_or("", String::as_str);
-            simple_paragraph(xml, None, text, Look { bold: header, ..Look::default() });
+            simple_paragraph(xml, None, text, Look { bold: header, ..Look::default() }, rtl);
             xml.close("w:tc");
         }
         xml.close("w:tr");
@@ -252,9 +304,17 @@ fn table(xml: &mut XmlWriter, content: &Table, document: &Document) {
     xml.close("w:tbl");
 }
 
-fn section(xml: &mut XmlWriter, document: &Document) {
+/// The document's margin in twips.
+fn margin(document: &Document) -> u32 {
+    #[expect(clippy::cast_possible_truncation, clippy::cast_sign_loss, reason = "0 to 2880")]
+    let twips = (document.margin() * 20.0).round() as u32;
+    twips
+}
+
+fn section(xml: &mut XmlWriter, document: &Document, rtl: bool) {
     let (width, height) = document.page_size().twips();
-    let (width, height, margin) = (width.to_string(), height.to_string(), MARGIN.to_string());
+    let (width, height, margin) =
+        (width.to_string(), height.to_string(), margin(document).to_string());
     xml.open("w:sectPr", &[]);
     if document.has_page_numbers() {
         // rId2: the footer, after the styles (see `write`).
@@ -264,6 +324,9 @@ fn section(xml: &mut XmlWriter, document: &Document) {
     let margins =
         [("w:top", &margin), ("w:right", &margin), ("w:bottom", &margin), ("w:left", &margin)];
     xml.empty("w:pgMar", &margins.map(|(key, value)| (key, value.as_str())));
+    if rtl {
+        xml.empty("w:bidi", &[]);
+    }
     xml.close("w:sectPr");
 }