pubmarq 0.1.0__py3-none-any.whl

pubmarq/__init__.py

@@ -0,0 +1,45 @@
+# pubmarq/__init__.py
+
+"""
+Scientific articles and theses from markdown, set for a journal or a school:
+PDF through pdfmarq, DOCX through docmarq.
+
+The article says what it is, a journal profile how it looks,
+so one source goes to any journal pubmarq has a profile for.
+
+Example:
+  >>> from pubmarq import build
+  >>> build("paper.md", "ijet", out_dir="out").files
+"""
+
+#--------------------------------------------------------------------------- Metadata for auto-toml
+
+__version__ = "0.1.0"
+__repo__ = "Xaeian/PubMarQ"
+__python__ = ">=3.12" # as xaeian
+__description__ = "Scientific articles and theses from markdown, set for a journal as PDF and DOCX"
+__author__ = "Xaeian"
+__keywords__ = ["journal", "article", "thesis", "markdown", "pdf", "docx", "ieee"]
+__dependencies__ = [
+  "docmarq[md]>=0.5.1", "pdfmarq[md]>=0.7.1", "markdown-it-py", "Pillow", "xaeian>=1.2.2",
+  "rlPyCairo", # docmarq's, named so CI installs the system cairo pycairo builds against
+]
+__scripts__ = {"pubmarq": "pubmarq.cli:main"}
+
+#--------------------------------------------------------------------------------------- Public API
+
+from .langs import Lang, LANGS
+from .journal import Foot, Head, Journal, RunIn, School, Type
+from .journals import JOURNALS, get_journal
+from .article import Article, Parser, read
+from .check import Issue, check
+from .to_docx import write_docx
+from .to_pdf import write_pdf
+from .build import Result, build, preflight, read_md, read_file
+
+__all__ = [
+  "Lang", "LANGS", "Foot", "Head", "RunIn", "School", "Type", "Journal", "JOURNALS", "get_journal",
+  "Article", "Parser", "read", "Issue", "check",
+  "write_docx", "write_pdf",
+  "Result", "build", "preflight", "read_md", "read_file",
+]

pubmarq/__main__.py

@@ -0,0 +1,6 @@
+# pubmarq/__main__.py
+
+import sys
+from .cli import main
+
+sys.exit(main())

pubmarq/article.py

@@ -0,0 +1,600 @@
+# pubmarq/article.py
+
+"""
+An article read from markdown: its parts, in the order and with the numbers a journal sets.
+
+`read` takes the text and an engine's `Parser`, and resolves for one journal:
+abstracts and keywords, heading numbers, figures and tables with their captions,
+citations as reference numbers, mentions of figures, tables and labelled formulas, typography.
+Writers draw the blocks, and nothing here knows Word, PDF or an engine.
+
+Example:
+  >>> article = read(open("paper.md").read(), get_journal("ijet"), parser)
+  >>> [b.kind for b in article.blocks][:3]
+  ['heading', 'para', 'para']
+"""
+import re
+from dataclasses import dataclass, field, replace
+from typing import Callable
+from markdown_it.token import Token
+from .journal import Journal
+from .langs import LANGS
+from .refs import entries, format_ref, has_doi, inline, text
+from .typography import EN_DASH, NBSP, bind, counter, roman, smarten
+
+# The names a source is read by, in every language: a heading or an opening, to its language
+_ABSTRACT = {lang.abstract.lower(): key for key, lang in LANGS.items()}
+_KEYWORD_NAMES = {name: key for key, lang in LANGS.items()
+  for name in (lang.keywords.lower(), *lang.keyword_names)}
+_KEYWORDS = re.compile(rf"\s*({'|'.join(map(re.escape, _KEYWORD_NAMES))})\s*:?\s*(.*)",
+  re.I | re.S)
+_TABLES = "|".join(lang.table for lang in LANGS.values())
+_FIGURES = "|".join(lang.figure for lang in LANGS.values())
+_NUMBER = r"\d+(?:\.\d+)*" # of a figure or table as a source writes it: `3`, or `2.1` by chapter
+_CAPTION = re.compile(
+  rf"(?:(?P<table>{_TABLES})|(?P<figure>{_FIGURES}))\s*(?P<number>{_NUMBER})\.?", re.I)
+# `Table 2`, `Tables 1 and 3`, `Figs. 2-4`, `Rys. 1 i 2`: the word, and the numbers after it
+_TABLE_NAMES = "|".join(lang.table_mention for lang in LANGS.values())
+_FIGURE_NAMES = "|".join(lang.figure_mention for lang in LANGS.values())
+_JOINS = "|".join(word for lang in LANGS.values() for word in lang.joins)
+_LIST = (rf"{_NUMBER}(?:(?:\s*,\s*(?:(?:{_JOINS})\s+)?|\s+(?:{_JOINS}|&)\s+|\s*[-–]\s*)"
+  rf"{_NUMBER})*")
+_MENTION = re.compile(
+  rf"\b(?P<word>(?P<table>{_TABLE_NAMES})|(?P<figure>{_FIGURE_NAMES}))\s+(?P<list>{_LIST})\b")
+# A formula named as LaTeX names it, `\label{ohm}` in its `$$`, and mentioned so in the text,
+# in `$...$` or out of it: `\eqref{ohm}` its number in brackets, `\ref{ohm}` the number alone
+_LABEL = re.compile(r"\\label\{([^{}]+)\}")
+_EQREF = re.compile(r"\\(eq)?ref\{([^{}]+)\}")
+# Chapters of a thesis named as lists of figures or tables, in any language, which list them
+_LISTS = {"figure": re.compile("|".join(lang.figure_list for lang in LANGS.values()), re.I),
+  "table": re.compile("|".join(lang.table_list for lang in LANGS.values()), re.I)}
+_RANGE = re.compile(r"\s*[-–]\s*")
+_DROPPED = re.compile("(" + "|".join(name for lang in LANGS.values() for name in lang.refs) + ")",
+  re.I)
+_ACK = re.compile("(" + "|".join(lang.ack for lang in LANGS.values()) + ")", re.I)
+# `published: IJET 2027, 73(1), 245-250`: journal, year, volume(issue), pages, as written
+_PUBLISHED = re.compile(r"(?P<journal>.+?)\s+(?P<year>\S+),\s*(?P<volume>[^\s(,]+)"
+  r"\((?P<issue>[^)]*)\),\s*(?P<pages>\S+)")
+_ANONYMOUS = re.compile(r"Anonymous(?:(?:,? and |, )Anonymous)+") # authors of one reference
+_BREAKS = ("softbreak", "hardbreak") # where a line of the source ends within a paragraph
+
+@dataclass(frozen=True)
+class Parser:
+  """What reading takes from an engine: its markdown, as the engine reads it."""
+  parse: Callable[[str], list[Token]] # `MarkdownRenderer.parse`
+  blocks: Callable[[list[Token]], list[tuple[int, int]]] # `top_blocks`
+  frontmatter: Callable[[str], tuple[dict, str]] # `split_frontmatter`
+  people: Callable[[object], list[dict]] # `people`
+  group_options: Callable[[str], list[str]] # `group_options`
+
+@dataclass
+class Author:
+  name: str
+  aff: tuple = () # keys of `Article.affiliations`
+  email: str = ""
+  orcid: str = ""
+  corresponding: bool = False # the one to write to, `corresponding: true` in the frontmatter
+
+@dataclass
+class Block:
+  """One part a writer draws: the tokens an engine draws, and what pubmarq sets around them."""
+  # One of heading, para, figure, table, math, raw, wide, narrow, pages of a PDF set in,
+  # and abstract, keywords, authors, refs, summary where the layout's `flow` puts them
+  kind: str
+  tokens: list = field(default_factory=list)
+  text: Token|None = None # inline text of a heading or a caption
+  label: str = "" # `II.`, `Fig. 3.`, `TABLE II`
+  level: int = 0 # of a heading, from 1
+  first: bool = False # the paragraph a drop cap opens
+  ack: bool = False # part of the acknowledgment, which a blind copy leaves out
+  number: str = "" # the author's own number of a figure or table, as written: `3`, `2.1`
+  n: int = 0 # its number in reading order
+  lang: str = "" # of an abstract a thesis sets on a page of its own at the back
+
+@dataclass
+class Ref:
+  number: int
+  text: Token # inline, set in the journal's style
+  doi: bool
+
+@dataclass
+class Article:
+  title: str
+  short_title: str
+  authors: list
+  affiliations: dict
+  funding: str
+  abstracts: dict # language → inline tokens, one per paragraph
+  keywords: dict # language → words
+  blocks: list
+  refs: list
+  published: dict # `journal`, `year`, `volume`, `issue`, `pages` and `doi` known so far
+  meta: dict # the frontmatter as written
+  facts: dict # what reading noticed, for the preflight
+  lang: str = "en" # language it is written in, as `lang:` says, else its journal's
+
+  def title_in(self, lang:str) -> str:
+    """The title in `lang`: `title` in its own language, else `title_<lang>` of the frontmatter."""
+    return self.title if lang == self.lang else str(self.meta.get(f"title_{lang}") or "")
+
+  def blind(self) -> "Article":
+    """
+    The article for blind review: no authors, affiliations, funding or acknowledgment,
+    and in the references `Anonymous` for the names of its authors.
+    """
+    names = re.compile("|".join(_name(a.name) for a in self.authors)) if self.authors else None
+    return replace(self, authors=[], affiliations={}, funding="",
+      blocks=[b for b in self.blocks if not b.ack],
+      refs=[replace(r, text=_unnamed(r.text, names)) for r in self.refs] if names else self.refs)
+
+def plain(inline:Token, math:bool=False) -> str:
+  """
+  Words of an inline token, code among them, markup dropped, formulas as written by `math`,
+  a space where a line of the source ends.
+  """
+  kinds = ("text", "code_inline", "math_inline") if math else ("text", "code_inline")
+  return "".join(" " if c.type in _BREAKS else c.content for c in inline.children or []
+    if c.type in kinds + _BREAKS)
+
+#--------------------------------------------------------------------------------------------- Read
+
+def read(md_text:str, journal:Journal, parser:Parser) -> Article:
+  """
+  The article `md_text` holds, resolved for `journal`, its tokens from an engine's `parser`,
+  in the language its frontmatter's `lang:` names, else the journal's.
+  """
+  fm, _ = parser.frontmatter(md_text)
+  journal = journal.speaking(fm.get("lang"))
+  tokens = parser.parse(md_text)
+  title = str(fm.get("title") or "")
+  facts = {"uncited": [], "missing": [], "renumbered": [], "mentioned": set(), "images": [],
+    "plain": 0, "bold": 0, "labels": {}, "referred": set(), "unlabelled": [], "doubled": [],
+    "apart": set()}
+  blocks, abstracts, keywords = _structure(_items(tokens, parser), title, fm, journal)
+  refs = _cite(blocks, abstracts, _notes(tokens), journal, facts)
+  _number(blocks, journal, facts)
+  _formulas(blocks, abstracts, facts)
+  cells = {id(t) for b in blocks if b.kind == "table" for t in b.tokens if t.type == "inline"}
+  for piece in _inlines(blocks, abstracts):
+    _polish(piece, journal, facts, bold=journal.bold != "drop" or id(piece) in cells,
+      text=id(piece) not in cells)
+  if not journal.caption_stop:
+    for b in blocks:
+      if b.kind in ("figure", "table") and b.text is not None: _unstopped(b.text)
+  _run_in(blocks, journal)
+  authors, affiliations = _authors(fm, parser.people)
+  return Article(title=title, short_title=str(fm.get("short_title") or title),
+    authors=authors, affiliations=affiliations, funding=str(fm.get("funding") or "").strip(),
+    abstracts=abstracts, keywords=keywords, blocks=blocks, refs=refs,
+    published=_published(fm, facts), meta=fm, facts=facts, lang=journal.lang)
+
+def _items(tokens:list[Token], parser:Parser) -> list[tuple[str, list[Token]]]:
+  """
+  Top-level blocks as `(kind, tokens)`, captions paired with what they name.
+  A group is opened, and a `wide` one set between `wide` and `narrow` marks.
+  """
+  items = []
+  for start, end in parser.blocks(tokens):
+    part, t = tokens[start:end], tokens[start]
+    if t.type == "html_block":
+      if len(part) == 1: continue # a comment, not a group `blocks` cut out
+      inner = _items(part[1:-1], parser)
+      wide = "wide" in parser.group_options(t.content)
+      items += ([("wide", [])] + inner + [("narrow", [])]) if wide else inner
+    elif t.type == "paragraph_open":
+      images = all(c.type in ("image", "softbreak") for c in part[1].children or [])
+      items.append(("image" if images else "para", part))
+    elif t.type == "blockquote_open": items.append(("caption" if _caption(part) else "raw", part))
+    elif t.type in ("heading_open", "table_open", "math_block"):
+      items.append((t.type.split("_")[0], part))
+    elif t.type != "footnote_block_open": items.append(("raw", part))
+  return items
+
+def _caption(part:list[Token]) -> tuple[str, str, Token]|None:
+  """
+  `(kind, number, text)` of a quote reading `> **Table 2.** ...` or `> **Rysunek 2.1.** ...`,
+  `None` for any other quote.
+  """
+  inlines = [t for t in part if t.type == "inline"]
+  if len(inlines) != 1: return None
+  kids = [c for c in inlines[0].children or [] if c.type != "text" or c.content]
+  if len(kids) < 3 or kids[0].type != "strong_open" or kids[2].type != "strong_close": return None
+  m = _CAPTION.fullmatch(kids[1].content.strip())
+  if not m: return None
+  rest = kids[3:]
+  if rest and rest[0].type == "text": rest = [text(rest[0].content.lstrip())] + rest[1:]
+  kind = "table" if m["table"] else "figure"
+  return kind, m["number"], Token("inline", "", 0, children=rest)
+
+def _structure(
+  items:list, title:str, fm:dict, journal:Journal,
+) -> tuple[list[Block], dict, dict]:
+  """Blocks of the text, and the abstracts and keywords taken out of it."""
+  levels = [int(p[0].tag[1]) for kind, p in items if kind == "heading"
+    and plain(p[1]).strip().lower() not in _ABSTRACT and plain(p[1]).strip() != title]
+  base = min(levels, default=2)
+  blocks, abstracts, keywords = [], {}, {}
+  mode, ack, dropped = None, False, False
+  i = 0
+  while i < len(items):
+    kind, part = items[i]
+    after = items[i + 1] if i + 1 < len(items) else ("", [])
+    i += 1
+    if kind == "heading":
+      name = plain(part[1]).strip()
+      mode = _ABSTRACT.get(name.lower())
+      dropped = bool(_DROPPED.fullmatch(name))
+      level = int(part[0].tag[1]) - base + 1
+      # What follows the references' name goes, as they come from the notes, but a thesis keeps
+      # a chapter of that name: they stand in its place
+      kept = dropped and journal.school is not None and level == 1
+      if mode or (dropped and not kept) or name == title: continue
+      ack = bool(_ACK.fullmatch(name))
+      blocks.append(Block("heading", part, part[1], level=level, ack=ack))
+      continue
+    if dropped: continue
+    if kind == "para":
+      m = _KEYWORDS.fullmatch(plain(part[1]))
+      if m:
+        lang = _KEYWORD_NAMES[m[1].lower()]
+        keywords[lang] = [w for w in re.split(r"\s*[;,]\s*", m[2].strip().rstrip(".")) if w]
+        mode = None
+      elif mode: abstracts.setdefault(mode, []).append(part[1])
+      else: blocks.append(Block("para", part, ack=ack))
+      continue
+    caption = _caption(after[1]) if after[0] == "caption" else None
+    if kind == "image" and caption and caption[0] == "figure":
+      blocks.append(Block("figure", part, caption[2], number=caption[1], ack=ack))
+      i += 1
+    elif kind == "image" and journal.school is not None and pages_file(part):
+      blocks.append(Block("pages", part, ack=ack)) # a thesis sets in a PDF that has no caption
+    elif kind == "caption" and after[0] == "table" and _caption(part)[0] == "table":
+      _, number, words = _caption(part)
+      blocks.append(Block("table", after[1], words, number=number, ack=ack))
+      i += 1
+    elif kind in ("wide", "narrow", "math"): blocks.append(Block(kind, part, ack=ack))
+    else: blocks.append(Block("raw", part, ack=ack))
+  if not keywords and fm.get("keywords"):
+    words = fm["keywords"]
+    keywords[journal.lang] = words if isinstance(words, list) else str(words).split(", ")
+  return blocks, abstracts, keywords
+
+def pages_file(tokens:list[Token]) -> str:
+  """
+  The PDF a paragraph of one image names, `![](paper.pdf)`, whose pages a document sets in
+  as its own, as a dissertation sets in its published articles: `""` for any other paragraph.
+  """
+  images = [c for t in tokens if t.type == "inline" for c in t.children or []
+    if c.type == "image"]
+  src = images[0].attrGet("src") if len(images) == 1 else ""
+  return src if str(src).lower().endswith(".pdf") else ""
+
+def _authors(fm:dict, people) -> tuple[list[Author], dict]:
+  """
+  Authors of `author:`, as the engine's `people` reads it, and the places of `affiliations:`.
+  One with no `aff` is with the issuer of the document, `entity` at `address`.
+  """
+  places = {str(k): str(v) for k, v in (fm.get("affiliations") or {}).items()}
+  issuer = ", ".join(str(fm[k]) for k in ("entity", "address") if fm.get(k))
+  authors = []
+  for p in people(fm.get("author")):
+    aff = tuple(_listed(p.get("aff"))) or (("entity",) if issuer else ())
+    authors.append(Author(p["name"], aff, str(p.get("email") or ""), str(p.get("orcid") or ""),
+      bool(p.get("corresponding"))))
+  if any("entity" in a.aff for a in authors): places.setdefault("entity", issuer)
+  return authors, places
+
+def _listed(value) -> list[str]:
+  if isinstance(value, list): return [str(v).strip() for v in value]
+  return [v.strip() for v in str(value).split(",")] if value else []
+
+def _published(fm:dict, facts:dict) -> dict:
+  """`published:` read into its fields as written, and `doi:`, for the journal's lines."""
+  out = {"doi": str(fm["doi"])} if fm.get("doi") else {}
+  if not fm.get("published"): return out
+  m = _PUBLISHED.fullmatch(str(fm["published"]).strip())
+  if m: return m.groupdict() | out
+  facts["published"] = str(fm["published"])
+  return out
+
+def _name(name:str) -> str:
+  """Pattern of `name`, its given names in full or as initials: `Anna Nowak`, `A. Nowak`."""
+  *given, surname = name.split() or [""]
+  if not given: return re.escape(surname)
+  space = r"\s+" # a no-break space too
+  full = space.join(map(re.escape, given))
+  initials = r"\s*".join(rf"{re.escape(g[0])}\." for g in given)
+  return rf"(?:{full}|{initials}){space}{re.escape(surname)}"
+
+def _unnamed(piece:Token, names:re.Pattern) -> Token:
+  """`piece` with `names` as `Anonymous`, the authors of one reference as one."""
+  return inline([text(_ANONYMOUS.sub("Anonymous", names.sub("Anonymous", c.content)))
+    if c.type == "text" else c for c in piece.children or []])
+
+#---------------------------------------------------------------------------------------- Citations
+
+def _notes(tokens:list[Token]) -> dict[str, Token]:
+  """Footnote definitions by label: the inline of the first paragraph of each."""
+  notes, label = {}, None
+  for t in tokens:
+    if t.type == "footnote_open": label = (t.meta or {}).get("label")
+    elif t.type == "inline" and label is not None and label not in notes: notes[label] = t
+    elif t.type == "footnote_close": label = None
+  return notes
+
+def _inlines(blocks:list[Block], abstracts:dict) -> list[Token]:
+  """Every inline token in reading order: abstracts, then the blocks, captions where they stand."""
+  out = [t for parts in abstracts.values() for t in parts]
+  for b in blocks:
+    if b.kind == "figure": out += [t for t in b.tokens if t.type == "inline"] + [b.text]
+    elif b.kind == "table": out += [b.text] + [t for t in b.tokens if t.type == "inline"]
+    elif b.kind == "heading": out.append(b.text)
+    else: out += [t for t in b.tokens if t.type == "inline"]
+  return out
+
+def _cite(
+  blocks:list[Block], abstracts:dict, notes:dict, journal:Journal, facts:dict,
+) -> list[Ref]:
+  """
+  Footnote marks turned into reference numbers in the order of first citation.
+  A footnote naming several references gives each its own number.
+  """
+  refs, numbers = [], {}
+  def number(label:str) -> list[int]:
+    if label not in numbers:
+      numbers[label] = []
+      for entry in entries(notes[label]):
+        refs.append(Ref(len(refs) + 1, format_ref(entry, journal.cite, journal.lang, journal.dash),
+          has_doi(entry)))
+        numbers[label].append(len(refs))
+    return numbers[label]
+  for piece in _inlines(blocks, abstracts):
+    out, group = [], []
+    for c in (piece.children or []) + [None]:
+      if c is not None and c.type == "footnote_ref":
+        group.append((c.meta or {}).get("label"))
+        continue
+      if group:
+        cited = sorted({n for g in group for n in number(g)})
+        _bind_mark(out, marks(cited, journal.cite_sep, journal.cite_joined))
+        group = []
+      if c is not None: out.append(c)
+    piece.children = out
+  facts["uncited"] = [label for label in notes if label not in numbers]
+  return refs
+
+def marks(numbers:list[int], sep:str, joined:bool=False) -> str:
+  """
+  `[1],[2]`, and a run of three or more as `[3]` to `[5]` joined by an en dash,
+  or `joined` in one bracket: `[1, 2]`, `[3–5]`, `[6, 10–12, 17]`.
+  """
+  runs, start = [], 0 # `(first, last)` of each run of numbers, a lone one its own run
+  for i in range(1, len(numbers) + 1):
+    if i == len(numbers) or numbers[i] != numbers[i - 1] + 1:
+      run = numbers[start:i]
+      runs += [(run[0], run[-1])] if len(run) > 2 else [(n, n) for n in run]
+      start = i
+  if joined: return "[" + sep.join(str(a) if a == b else f"{a}{EN_DASH}{b}" for a, b in runs) + "]"
+  return sep.join(f"[{a}]" if a == b else f"[{a}]{EN_DASH}[{b}]" for a, b in runs)
+
+def _bind_mark(out:list[Token], mark:str):
+  """Append citation `mark`, bound to the word before it by a no-break space."""
+  if out and out[-1].type == "text":
+    before = out[-1].content
+    space = "" if before.endswith(("(", "[")) or not before else NBSP
+    out[-1] = text(before.rstrip(" ") + space)
+  elif out: out.append(text(NBSP))
+  out.append(text(mark))
+
+#---------------------------------------------------------------------------------------- Numbering
+
+def _number(blocks:list[Block], journal:Journal, facts:dict):
+  """
+  Labels of headings, figures, tables and formulas,
+  mentions of figures and tables renumbered to match, and of formulas named by their label.
+  A chapter the journal sets without a number, as `Wstęp` of a thesis, and its sections take none.
+  Numbered within chapters, a figure, table or formula of a numbered one bears its number: `2.1`,
+  and one outside them counts apart: `1`, `2`.
+  A source may number them either way, through the text or by chapter.
+  """
+  depth = max(len(journal.heads), 1)
+  counts, maps, totals = [0] * depth, {"figure": {}, "table": {}}, {"figure": 0, "table": 0}
+  shown = {"figure": {}, "table": {}} # each number in reading order as set: `II`, `2.1`
+  within = {"figure": 0, "table": 0, "math": 0} # of the chapter
+  apart = dict(within) # outside the numbered chapters
+  equation, section, opened, loose = 0, False, not journal.dropcap, False
+  def counted(kind:str, n:int) -> str:
+    """How the `n`th of `kind` in reading order is numbered."""
+    if kind == "table" and journal.table_roman: return roman(n)
+    if not journal.by_chapter: return str(n)
+    if loose or not counts[0]:
+      apart[kind] += 1
+      return str(apart[kind])
+    within[kind] += 1
+    return f"{counts[0]}.{within[kind]}"
+  for b in blocks:
+    if b.kind == "heading" and not b.ack:
+      if b.level == 1:
+        loose = unnumbered(b, journal)
+        within = dict.fromkeys(within, 0)
+      if loose: continue
+      level = min(b.level, depth)
+      counts[level - 1] += 1
+      counts[level:] = [0] * (depth - level)
+      b.label = _head_label(counts, level, journal)
+      section = section or level == 1
+    elif b.kind in maps:
+      totals[b.kind] += 1
+      n = b.n = totals[b.kind]
+      maps[b.kind].setdefault(b.number, n)
+      label = shown[b.kind][n] = counted(b.kind, n)
+      if b.number not in (str(n), label): # neither as read nor as set
+        facts["renumbered"].append(f"{b.kind} {b.number} → {label}")
+      if b.kind == "figure":
+        b.label = f"{journal.figure} {label}."
+        facts["images"] += [a for t in b.tokens for c in t.children or [] if c.type == "image"
+          for a in [c.attrGet("src")]]
+      else:
+        b.label = f"{journal.table} {label}"
+        if not journal.table_split: b.label += "."
+    elif b.kind == "math":
+      source = b.tokens[0].content # its label read and left out, which no engine draws
+      names, source = _LABEL.findall(source), _LABEL.sub("", source)
+      if journal.equations:
+        equation += 1
+        number = counted("math", equation)
+        source = f"{source.rstrip()} \\tag{{{number}}}"
+        facts["doubled"] += [name for name in names if name in facts["labels"]]
+        facts["labels"].update(dict.fromkeys(names, number))
+      b.tokens[0].content = source
+    elif b.kind == "para" and section and not opened:
+      b.first = opened = True
+  mention = lambda m: _mention(m, maps, shown, facts)
+  for piece in _inlines(blocks, {}):
+    for c in piece.children or []:
+      if c.type == "text": c.content = _MENTION.sub(mention, c.content)
+
+def _formulas(blocks:list[Block], abstracts:dict, facts:dict):
+  """
+  Mentions of labelled formulas as their numbers, wherever they are written:
+  in the words, in a formula of the text and in the abstracts,
+  a `$...$` holding one mention alone set as words, any other kept a formula.
+  A formula in a list or quote takes no number, so its label is left out and noted.
+  """
+  refer = lambda m: _refer(m, facts)
+  nested = [t for b in blocks if b.kind != "math" for t in b.tokens if t.type == "math_block"]
+  for t in nested:
+    facts["apart"].update(_LABEL.findall(t.content))
+    t.content = _LABEL.sub("", t.content)
+  for t in [t for b in blocks for t in b.tokens if t.type == "math_block"]:
+    t.content = _EQREF.sub(refer, t.content)
+  for piece in _inlines(blocks, abstracts):
+    for c in piece.children or []:
+      if c.type == "text": c.content = _EQREF.sub(refer, c.content)
+      elif c.type == "math_inline" and _EQREF.fullmatch(c.content.strip()):
+        c.type, c.content = "text", _EQREF.sub(refer, c.content.strip())
+      elif c.type == "math_inline": c.content = _EQREF.sub(refer, c.content)
+
+def unnumbered(b:Block, journal:Journal) -> bool:
+  """
+  Whether chapter `b` stands without a number: one the journal so names, an appendix, a part,
+  or the place of a thesis's references.
+  """
+  name = plain(b.text).strip()
+  return references(b, journal) or any(p and re.fullmatch(p, name, re.I)
+    for p in (journal.unnumbered, journal.appendix, journal.parts))
+
+def part(b:Block, journal:Journal) -> bool:
+  """Whether `b` opens a part of the text, as `Część I. Autoreferat`, the contents set apart."""
+  return (b.kind == "heading" and b.level == 1 and bool(journal.parts)
+    and bool(re.fullmatch(journal.parts, plain(b.text).strip(), re.I)))
+
+def references(b:Block, journal:Journal) -> bool:
+  """Whether `b` is a thesis chapter named as references, which stand in its place."""
+  return (b.kind == "heading" and b.level == 1 and journal.school is not None
+    and bool(_DROPPED.fullmatch(plain(b.text).strip())))
+
+def list_of(b:Block, journal:Journal) -> str:
+  """
+  `figure` or `table` for a thesis chapter named as their list, `Wykaz rysunków` or
+  `List of tables`, which lists them where it stands; `""` for any other block.
+  """
+  if b.kind != "heading" or b.level != 1 or journal.school is None: return ""
+  name = plain(b.text).strip()
+  return next((kind for kind, names in _LISTS.items() if names.fullmatch(name)), "")
+
+def appendix(b:Block, journal:Journal) -> bool:
+  """Whether `b` opens a chapter the journal sets after the references, as an appendix."""
+  return (b.kind == "heading" and b.level == 1 and bool(journal.appendix)
+    and bool(re.fullmatch(journal.appendix, plain(b.text).strip(), re.I)))
+
+def _head_label(counts:list[int], level:int, journal:Journal) -> str:
+  """`II.`, `B.`, `2)` or, nested, `2.1.`: the number the level's `Head` asks for."""
+  fmt = journal.head(level).number
+  if not fmt: return ""
+  if journal.nested: return ".".join(str(n) for n in counts[:level]) + fmt[1:]
+  return counter(counts[level - 1], fmt[0]) + fmt[1:]
+
+def _mention(m:re.Match, maps:dict, shown:dict, facts:dict) -> str:
+  """
+  `Tables 1 and 5` as the journal numbers the tables they mean, `shown` by their numbers
+  in reading order, the word bound to the first.
+  """
+  word = m["word"]
+  kind = "table" if m["table"] else "figure"
+  parts = re.split(f"({_NUMBER})", m["list"]) # what comes before each number, then the number
+  out, last = [], None
+  for k in range(1, len(parts), 2):
+    number, ranged = parts[k], last is not None and bool(_RANGE.fullmatch(parts[k - 1]))
+    if ranged: # a range names every number inside it
+      facts["mentioned"] |= {(kind, maps[kind][x]) for x in _inside(last, number)
+        if x in maps[kind]}
+    n = maps[kind].get(number)
+    if n is None: facts["missing"].append(f"{word} {number}")
+    else: facts["mentioned"].add((kind, n))
+    out.append((EN_DASH if ranged else parts[k - 1]) + (shown[kind][n] if n else number))
+    last = number
+  return f"{word}{NBSP}{''.join(out)}"
+
+def _refer(m:re.Match, facts:dict) -> str:
+  """
+  A mention of the formula its label names, as its number: in brackets for `eqref`, `(2.1)`,
+  alone for `ref`, `2.1`; one naming no formula stays as written, for the preflight.
+  """
+  number = facts["labels"].get(m[2])
+  if number is None:
+    facts["unlabelled"].append((m[0], m[2]))
+    return m[0]
+  facts["referred"].add(m[2])
+  return f"({number})" if m[1] else number
+
+def _inside(first:str, last:str) -> list[str]:
+  """Numbers a range names between its ends: `2`–`5` names 3 and 4, `2.1`–`2.4` 2.2 and 2.3."""
+  *head, low = first.split(".")
+  *tail, high = last.split(".")
+  if head != tail: return []
+  return [".".join(head + [str(x)]) for x in range(int(low) + 1, int(high))]
+
+def _run_in(blocks:list[Block], journal:Journal):
+  """Headings of a run-in level opening the paragraph after them, in the level's face."""
+  for b in [b for b in blocks if b.kind == "heading" and journal.head(b.level).run_in]:
+    i = blocks.index(b)
+    after = blocks[i + 1] if i + 1 < len(blocks) else None
+    if after is None or after.kind != "para": continue
+    mode = journal.head(b.level).mode
+    tags = (["strong"] if "Bold" in mode else []) + (["em"] if "Italic" in mode else [])
+    lead = f"{b.label} {plain(b.text).strip()}: ".lstrip()
+    after.tokens[1].children = [Token(f"{t}_open", t, 1) for t in tags] + [text(lead)] + [
+      Token(f"{t}_close", t, -1) for t in reversed(tags)] + (after.tokens[1].children or [])
+    blocks.remove(b)
+
+#--------------------------------------------------------------------------------------- Typography
+
+def _unstopped(inline:Token):
+  """A caption without the full stop it ends with, for a journal whose captions end without one."""
+  texts = [c for c in inline.children or [] if c.type == "text" and c.content.strip()]
+  last = texts[-1] if texts else None
+  if last is None: return
+  words = last.content.rstrip()
+  if words.endswith(".") and not words.endswith(".."): last.content = words[:-1]
+
+def _polish(inline:Token, journal:Journal, facts:dict, bold:bool, text:bool):
+  """
+  Typography of the journal's language on the text of `inline`, code left alone,
+  links kept where the journal keeps them, and bold where `bold` says.
+  Bold set plain is counted for the preflight, and bold kept in the `text`, outside tables.
+  """
+  dropped = set() if journal.links else {"link_open", "link_close"}
+  if not bold: dropped |= {"strong_open", "strong_close"}
+  out, prev = [], " "
+  for c in inline.children or []:
+    if c.type in dropped:
+      facts["plain"] += c.type == "strong_open"
+      continue
+    facts["bold"] += text and c.type == "strong_open"
+    if c.type == "text":
+      c.content = bind(smarten(c.content, journal.lang, prev, journal.dash))
+      prev = c.content[-1:] or prev
+    elif c.type == "code_inline": prev = "x"
+    out.append(c)
+  inline.children = out