with nothing but (non-breaking) spaces or
. Empty
s are layout helpers (Springer's
div.ClearBoth) and paragraphs holding only anchors are index targets – neither is a scene break."""
return local(el.tag) == "p" and self._is_empty(el) and \
all(local(c.tag) == "br" for c in el if is_element(c))
def _is_prose(self, el: Any) -> bool:
return local(el.tag) in ("p", "div") and not self._is_empty(el) and not self._is_ornament(el) \
and not self._is_poem(el)
@staticmethod
def _element_siblings(el: Any, forward: bool) -> Any:
node = el.getnext() if forward else el.getprevious()
while node is not None:
if is_element(node):
yield node
node = node.getnext() if forward else node.getprevious()
def _is_ornament(self, el: Any) -> bool:
"""Paragraph that only contains a typographic separator such as *** or ⁂."""
return bool(ORNAMENT.fullmatch(text_content(el).replace("\xa0", " ").strip()))
def _is_scene_gap(self, el: Any) -> bool:
"""Empty paragraph between two prose paragraphs (first of a run of empties) → scene break."""
if not self._is_blank_p(el):
return False
prev = next(self._element_siblings(el, forward=False), None)
if prev is None or not self._is_prose(prev):
return False
for nxt in self._element_siblings(el, forward=True):
if self._is_blank_p(nxt):
continue # further empty paragraphs of the same gap
return self._is_prose(nxt)
return False
def _is_poem(self, el: Any) -> bool:
types = set(epub_types(el))
return bool(types & {"z3998:poem", "z3998:verse", "z3998:song", "z3998:lyrics"}) or \
any(POEM_CLASS.search(c) for c in classes(el))
def poem(self, el: Any) -> list[str]:
"""Verse: one quoted line per verse line, stanzas separated by an empty quote line."""
anchor = self.anchors_of(el)
stanzas: list[list[str]] = [[]]
def new_stanza() -> None:
if stanzas[-1]:
stanzas.append([])
def walk(container: Any) -> None:
for child in container:
if not is_element(child) or self._hidden(child):
continue
if local(child.tag) in ("div", "section") and any(
is_element(c) and local(c.tag) in ("p", "div", "span") for c in child):
new_stanza() # stanza container
walk(child)
new_stanza()
elif self._is_empty(child):
new_stanza()
else:
line = join_inline([("r", self.anchors_of(child))] + self.inline_children(child))
stanzas[-1].append(escape_line_starts(line).replace("\n", "\n> "))
walk(el)
stanzas = [s for s in stanzas if s]
if not stanzas:
return self._flow_with_anchor(el)
self.poems += 1
text = "\n>\n".join("\\\n".join(f"> {line}" for line in stanza) for stanza in stanzas)
return ([anchor] if anchor else []) + [text]
# ------------------------------------------------------------------ info boxes (P2)
def _box_kind(self, el: Any) -> str | None:
"""'' for a box without type hint, a type keyword, or None if ``el`` is no box."""
name = local(el.tag)
types = set(epub_types(el)) | {r.removeprefix("doc-") for r in roles(el)}
hint = " ".join(sorted(types)) + " " + " ".join(classes(el))
semantic = types & {"sidebar", "tip", "notice", "warning", "caution", "important", "help", "example"}
by_class = any(BOX_CLASS.search(c) for c in classes(el))
if name == "p":
return _box_type(hint) if by_class and not self._is_empty(el) else None
if not (semantic or by_class or self._css_framed(el)):
return None
if not text_content(el).strip() or any(local(e.tag) == "pre" for e in iter_elements(el)) \
and not any(local(e.tag) == "p" and text_content(e).strip() for e in iter_elements(el)):
return None # bordered code listings or image frames are no info boxes
if self.ch is not None and any(e is self.ch.title_el for e in iter_elements(el)):
return None # never swallow the chapter heading
return _box_type(hint)
def _css_framed(self, el: Any) -> bool:
"""Block with a visible border or background in the book's CSS, holding short prose."""
if self.css is None or local(el.tag) not in ("div", "section", "aside"):
return False
style = self.css.computed(el)
border = any(k.startswith("border") and not re.search(r"\bnone\b|^0(px)?\b|hidden", v)
for k, v in style.items() if k in ("border", "border-top", "border-left", "border-style",
"border-width", "border-bottom", "border-right"))
bg = style.get("background-color") or style.get("background") or ""
background = bool(bg) and not re.search(r"transparent|none|inherit|initial|^#?fff(fff)?$|white", bg.lower())
if not (border or background):
return False
text = norm_ws(text_content(el))
return 0 < len(text) <= 3000 and any(local(e.tag) == "p" for e in iter_elements(el)) \
and not any(heading_level(e) in (1, 2) for e in iter_elements(el))
def box(self, el: Any, kind: str) -> list[str]:
anchor = self.anchors_of(el)
members = [el]
if local(el.tag) == "p": # paragraph-style boxes: group following siblings of the same kind
for sib in self._element_siblings(el, forward=True):
if local(sib.tag) == "p" and any(BOX_CLASS.search(c) for c in classes(sib)) \
and _box_type(" ".join(classes(sib))) == kind:
members.append(sib)
else:
break
title_el = self._box_title(members)
title = ""
markers: list[str] = [] # page breaks in the title go before the box, like for headings
if title_el is not None:
pieces: list[Piece] = [("t", self._text(title_el.text))] if title_el.text else []
self.marker_sink = markers
try:
for child in title_el:
if is_element(child) and not self._title_symbol(child):
pieces.extend(self.inline(child))
if child.tail:
pieces.append(("t", self._text(child.tail)))
finally:
self.marker_sink = None
title = join_inline(pieces, hard_break=" ").strip()
kind = kind or _box_type(norm_ws(text_content(title_el)))
saved = self.in_box
self.in_box = True
try:
blocks: list[str] = []
for member in members:
if member is title_el:
continue
if local(member.tag) == "p":
blocks.extend(self.flow(member))
else:
blocks.extend(self.render_items(
[(None, x) for x in self._items_without(member, title_el) if not self._box_icon(x)]))
finally:
self.in_box = saved
for sib in members[1:]:
sib.set(CONSUMED, "1")
if not kind and blocks:
kind = _box_type(norm_ws(re.sub(r"[*_\\]", "", blocks[0]))[:30])
kind = kind or "note"
if title and norm_ws(re.sub(r"[*_\\:]", "", title)).lower() in TYPE_WORDS:
title = "" # 'Tipp' as title of a TIP box adds nothing
self.boxes += 1
out = ["".join(markers)] if markers else []
if anchor:
out.append(anchor)
head = [f"**{title}**"] if title else []
if self.opt.boxes == "html":
out.append(f'![Image]()
)."""
if not is_element(node) or text_content(node).strip():
return False
imgs = [e for e in iter_elements(node) if local(e.tag) == "img"]
return bool(imgs) and (any(re.search(r"icon|box_?img|symbol", c) for c in classes(node))
or all((i.get("alt") or "").strip().lower() in ("", "image", "icon", "bild") for i in imgs))
def _flow_with_anchor(self, el: Any) -> list[str]:
anchor = self.anchors_of(el)
if self.ch is not None and {"index", "index-persons", "glossary"} & set(self.ch.types):
special = self._index_block(el, anchor)
if special is not None:
return special
italic = bold = False
if self.opt.css_emphasis and local(el.tag) in ("p", "div") and not self.in_heading \
and not any(local(d.tag) in BLOCK_TAGS for d in iter_elements(el) if d is not el) \
and text_content(el).strip():
e = self._emphasis(el)
italic, bold = e["italic"] and not self.em, e["bold"] and not self.strong
self.em += italic
self.strong += bold
try:
blocks = self.flow(el)
finally:
self.em -= italic
self.strong -= bold
if (italic or bold) and len(blocks) == 1 and not _is_block_syntax(blocks[0]) and not blocks[0].startswith("<"):
for flag, marker, key in ((italic, "*", "italic"), (bold, "**", "bold")):
if flag:
blocks[0] = _wrap_text(blocks[0], marker)
self.css_applied[key] += 1
blocks = self._block_styles(el, blocks)
if anchor:
if blocks and not blocks[0].startswith(("#", "`", "|", " ", "- ", "$$", "\\[", "* * *")) \
and not re.match(r"\d+\. ", blocks[0]):
blocks[0] = anchor + blocks[0]
else:
blocks.insert(0, anchor)
return blocks
def _index_block(self, el: Any, anchor: str) -> list[str] | None:
"""Register/glossary layout: letter groups become headings, sub-entries keep their depth."""
cls = classes(el)
if any(c in ("heading", "indexheading", "letter", "groupletter", "index-letter") for c in cls):
text = norm_ws(text_content(el))
if 0 < len(text) <= 3:
return ([anchor] if anchor else []) + [f"## {md_escape(text)}"]
depth = 0
for c in cls:
if re.search(r"(tertiary|index-?3|level-?3|ie3|subsubentry)", c):
depth = 2
elif re.search(r"(secondary|index-?2|level-?2|ie2|subentry|sub-entry)", c):
depth = max(depth, 1)
if not depth:
return None
blocks = self.flow(el)
if blocks:
blocks[0] = "– " * depth + anchor + blocks[0]
return blocks
def heading(self, el: Any, forced_level: int = 0) -> list[str]:
ch = self.ch
if forced_level:
level = forced_level
elif ch is not None and el is ch.title_el:
level = 1
else:
level = heading_level(el) - (ch.shift if ch else 0)
level = max(self.min_level, min(6, level))
anchors = self.anchors_of(el, subtree=True)
markers = "".join(self.page_marker(e) for e in iter_elements(el))
self.in_heading = True
try:
text = join_inline(self.inline_children(el), hard_break=" ")
finally:
self.in_heading = False
text = re.sub(r"", "", text).strip()
out = [markers] if markers else []
if anchors:
out.append(anchors)
if not text:
if any(local(e.tag) in ("img", "svg") for e in iter_elements(el)):
out.extend(self.flow(el))
return out
text = re.sub(r"\s*#+\s*$", lambda m: m.group(0).replace("#", "\\#"), text)
out.append("#" * level + " " + text)
return out
def code_block(self, el: Any) -> list[str]:
code = code_text(el)
anchors = self.anchors_of(el, subtree=True)
out = [anchors] if anchors else []
if not code.strip():
return out
joined = 0
if not self.opt.keep_wrap_markers:
code, joined = join_wrap_markers(code)
lang, how = detect_language(el)
if not lang:
lang = detect_language_from_content(code)
how = "content" if lang else ""
if not lang and self.opt.code_language:
lang, how = self.opt.code_language, "option"
if self.ch:
self.ch.stats.code_blocks += 1
if not lang:
self.ch.stats.code_blocks_unlabeled += 1
self.code_blocks.append({"source": self._source(el), "chapter": self.file, "language": lang,
"detected_by": how, "lines": code.count("\n") + 1, "wrap_lines_joined": joined})
fence = fence_for(code)
out.append(f"{fence}{lang}\n{code}\n{fence}")
return out
def blockquote(self, el: Any) -> list[str]:
anchor = self.anchors_of(el)
inner = "\n\n".join(self.flow(el))
if not inner.strip():
return [anchor] if anchor else []
quoted = "\n".join("> " + line if line.strip() else ">" for line in inner.split("\n"))
return ([anchor] if anchor else []) + [quoted]
def list_block(self, el: Any) -> list[str]:
anchor = self.anchors_of(el)
ordered = local(el.tag) == "ol"
try:
number = int(el.get("start", "1"))
except ValueError:
number = 1
items = [c for c in el if is_element(c) and local(c.tag) == "li"]
labeled = bool(items) and all(self._list_label(li) is not None for li in items)
style = (el.get("style") or "").replace(" ", "").lower()
if "list-style-type:none" in style or "list-style:none" in style:
labeled = labeled or True
rendered: list[str] = []
loose = False
for li in items:
label_el = self._list_label(li) if labeled else None
if label_el is not None:
label = norm_ws(text_content(label_el))
rest = [(None, x) for x in self._items_after(li, label_el)]
blocks = self.render_items(rest)
if blocks:
blocks[0] = md_escape(label) + " " + blocks[0]
else:
blocks = [md_escape(label)]
else:
blocks = self.flow(li)
li_anchor = self.anchors_of(li)
if li_anchor:
blocks = [li_anchor + (blocks[0] if blocks else "")] + blocks[1:]
if len(blocks) > 1:
loose = True
body = "\n\n".join(blocks) if blocks else ""
if ordered and not labeled:
marker = f"{number}."
number += 1
else:
marker = "-"
rendered.append(indent_block(body, marker + " ", " " * (len(marker) + 1)))
if not rendered:
return [anchor] if anchor else []
joined = ("\n\n" if loose else "\n").join(rendered)
return ([anchor] if anchor else []) + [joined]
def _list_label(self, li: Any) -> Any:
first = next((c for c in li if is_element(c)), None)
if first is None or (li.text and li.text.strip()):
return None
if any(LABEL_CLASS.search(c) for c in classes(first)):
return first
return None
def _items_after(self, li: Any, label_el: Any) -> list[Any]:
out: list[Any] = []
seen = False
for child in li:
if child is label_el:
seen = True
if child.tail:
out.append(child.tail)
continue
if seen:
if is_element(child):
out.append(child)
if child.tail:
out.append(child.tail)
return out
def definition_list(self, el: Any) -> list[str]:
anchor = self.anchors_of(el)
out: list[str] = [anchor] if anchor else []
terms: list[str] = []
term_anchors = "" # anchors of elements go in front of the bold term, not inside it
for child in el:
if not is_element(child):
continue
name = local(child.tag)
if name == "dt":
terms.append(join_inline(self.inline_children(child), hard_break=" "))
term_anchors += self.anchors_of(child)
elif name == "dd":
blocks = self.flow(child)
a = self.anchors_of(child)
term = " / ".join(terms) if terms else ""
ta, terms, term_anchors = term_anchors, [], ""
if term and len(blocks) == 1 and "\n" not in blocks[0] and not blocks[0].startswith(("```", "|", "<")):
out.append(f"{ta}**{term}:** {a}{blocks[0]}")
else:
if term:
out.append(f"{ta}**{term}**")
elif ta:
out.append(ta)
if a:
out.append(a)
out.extend(blocks)
elif name == "div": # HTML5 allows
\n\n' + "\n\n".join(head + blocks) + "\n\n
")
return out
body = "\n\n".join(head + blocks)
if self.opt.boxes == "callout":
body = f"[!{CALLOUT[kind]}]\n" + body
out.append("\n".join("> " + line if line.strip() else ">" for line in body.split("\n")))
return out
def _box_title(self, members: list[Any]) -> Any:
first = members[0]
if local(first.tag) == "p":
text = norm_ws(text_content(first))
return first if len(members) > 1 and 0 < len(text) <= 40 and not text.endswith((".", "!", "?")) else None
for child in first:
if not is_element(child) or self._box_icon(child):
continue
if heading_level(child) or any(re.search(r"heading|title|head$|ueberschrift", c) for c in classes(child)):
return child
return None
return None
@staticmethod
def _title_symbol(node: Any) -> bool:
"""Decorative symbol in a box title, e.g. [»]."""
text = norm_ws(text_content(node))
return any(re.search(r"icon|symbol", c) for c in classes(node)) and len(text) <= 5 \
and not re.search(r"\w", text)
@staticmethod
def _box_icon(node: Any) -> bool:
"""Decorative icon container inside a box (e.g. grouping inside
-
out.extend(self.definition_list(child))
if terms:
out.append(term_anchors + " / ".join(f"**{t}**" for t in terms))
return out
def figure(self, el: Any) -> list[str]:
anchor = self.anchors_of(el)
caption_el = next((c for c in el if is_element(c) and local(c.tag) == "figcaption"), None)
caption = ""
if caption_el is not None:
caption = join_inline(self.inline_children(caption_el), hard_break=" ")
old = self.figure_caption
self.figure_caption = norm_ws(text_content(caption_el)) if caption_el is not None else ""
items = [(None, x) for x in self._items_without(el, caption_el)]
try:
blocks = self.render_items(items)
finally:
self.figure_caption = old
out = ([anchor] if anchor else []) + blocks
if caption:
cap_anchor = self.anchors_of(caption_el, subtree=False) if caption_el is not None else ""
out.append(f"{cap_anchor}*{caption}*" if not caption.startswith("*") else cap_anchor + caption)
return out
def _items_without(self, el: Any, skip: Any) -> list[Any]:
out: list[Any] = []
if el.text:
out.append(el.text)
for child in el:
if child is not skip and is_element(child):
out.append(child)
if child.tail:
out.append(child.tail)
return out
def media_block(self, el: Any) -> list[str]:
name = local(el.tag)
srcs = [el.get("src") or el.get("data") or ""]
srcs += [s.get("src", "") for s in el if is_element(s) and local(s.tag) == "source"]
out = []
for src in [s for s in srcs if s]:
if self.resolver.is_external(src):
out.append(f"[{name.capitalize()}: {md_escape(src)}]({self._url(src)})")
continue
path = resolve_href(self.doc, unquote(src.split("#")[0]))
if path and self._exists(path):
if self.opt.extract_media:
mf = self.media.register(path, role=name)
label = {"audio": "Audio", "video": "Video"}.get(name, "Medium")
out.append(f"[{label}: {md_escape(path.rsplit('/', 1)[-1])}]({url_path(rel_link(self.file, mf.output))})")
else:
out.append(f"*[{name}: {md_escape(path)}]*")
self.diag.info("media-link", f"{name}-Element als Link erhalten (in Markdown nicht direkt abspielbar).", self._source(el))
else:
self.diag.warn("media-missing", f"Medienquelle {src} nicht im EPUB gefunden.", self._source(el))
if name in ("object", "iframe", "embed"):
self.diag.unsupported_element(name, self._source(el))
if not out:
out = self.flow(el)
return out
# ================================================================== tables
def table(self, el: Any) -> list[str]:
anchor = self.anchors_of(el)
rows = self._rows(el)
if self.ch:
self.ch.stats.tables += 1
cells_total = sum(len(r) for r in rows)
if cells_total <= 1 and not self._has_nested_table(el):
# single-cell layout table: keep its content as normal flow
cell = rows[0][0] if rows and rows[0] else None
return ([anchor] if anchor else []) + (self.flow(cell) if cell is not None else [])
reason = self._complex_reason(el, rows)
caption_el = next((c for c in el if is_element(c) and local(c.tag) == "caption"), None)
if reason:
if self.ch:
self.ch.stats.tables_html += 1
self.diag.warn("table-html", f"Tabelle enthält {reason}; als HTML erhalten.", self._source(el), self.file)
return [self.clean_html(el)] # clean_html keeps the id on