From 908d553f5b83bea039a29ba207697fd3f2723c2a Mon Sep 17 00:00:00 2001
From: Jessica Hamilton <jessica.l.hamilton@gmail.com>
Date: Thu, 22 Aug 2024 03:08:44 +0000
Subject: [PATCH] html2myst: support nested <pre> in <li>, handle more ref
 types.

Also removes warning about acronyms, as they're not actually
used as such in the source HTML.
---
 html2myst/html2myst.py                        | 30 ++++++++++++++++---
 html2myst/nodes.py                            |  4 ++-
 kits/application/message-filter.md            | 14 ++++-----
 kits/application/messenger.md                 | 10 ++++---
 kits/interface/picture.md                     |  4 ++-
 kits/storage/path.md                          |  7 +++--
 system-overview/application/message-filter.md |  2 +-
 system-overview/interface/list-item.md        |  5 ++--
 topics/device-drivers/driver-settings-api.md  |  9 +++---
 9 files changed, 58 insertions(+), 27 deletions(-)

diff --git a/html2myst/html2myst.py b/html2myst/html2myst.py
index 40fa70f..d1c9c21 100755
--- a/html2myst/html2myst.py
+++ b/html2myst/html2myst.py
@@ -22,6 +22,7 @@
 operator_re = re.compile(r'(operator([+\-*\/%^&|~!=<>,()[\]]{1,3}|\s+new|\s+delete))\(')
 reference_re = re.compile(r'#([^_]+)_([^_]+)$')
 enum_re = re.compile(r'^([A-Z0-9_]+)$')
+global_function_re = re.compile(r'([a-z]+_?)+')
 
 def text_content(element, clean=True):
 	if clean:
@@ -402,9 +403,12 @@ def process_inline(self, element):
 					content += f'_{result}_'
 
 			elif child.name == 'acronym':
-				# no acronym support in markdown...
-				print(fg.li_yellow, 'WARNING: missing acronym support in markdown', reset)
+				# these aren't actually treated as acronyms in the source HTML,
+				# just a stylistic convention; will treat as plaintext, as no
+				# benefit to explain widely understood terms:
+				#   AIFF, API, ASCII, ATAPI, AVI, BFS, CPU, DAC, DMA, GIF, GUI, IEC, I/O, IP, ISO, MIDI, MIME, MPEG, MUX, NTSC, PAL, PCI, PCMCIA, PNG, POP, RGB, RS-232, SCSI, SMTP, TCP, TLS, TV, UDP, URL, USB, UTF-8, VBL, WAVE
 				content += text_content(child)
+
 			elif child.name == 'br':
 				content += '\n\n'
 			else:
@@ -454,13 +458,31 @@ def process_link(self, element):
 				ref_method = f'{ref_class}()'
 			if content_matches:
 				if '::' in content:
+					# a fully qualified reference to a class method
 					return f'{{cpp:func}}`{ref_class}::{ref_method}()`'
 				else:
+					# a reference to a class method, with class name hidden
 					return f'{{cpp:func}}`~{ref_class}::{ref_method}()`'
 			else:
-					return f'{{cpp:func}}`{content} <{ref_class}::{ref_method}>`'
+				# a reference with a name different to link
+				return f'{{cpp:func}}`{content} <{ref_class}::{ref_method}>`'
 		else:
-			if ref_type == 'ref':
+			ref = ''
+
+			if match:
+				ref = match.group(0)[1:]
+			enum_match = enum_re.match(ref)
+			function_match = global_function_re.match(ref)
+
+			if match and (enum_match or function_match):
+				if enum_match:
+					return f'{{cpp:enumerator}}`{ref}`'
+				elif function_match:
+					if ref == content.replace('()', '') or ref == content:
+						return f'{{cpp:func}}`{ref}()`'
+					else:
+						return f'{{cpp:func}}`{content} <{ref}>`'
+			elif ref_type == 'ref':
 				print(fg.li_red, 'WARNING:', reset, 'unable to parse reference:', reset, fg.li_green, element, reset)
 			return f'{{{ref_type}}}`{content}`'
 
diff --git a/html2myst/nodes.py b/html2myst/nodes.py
index 89629af..99d3c11 100644
--- a/html2myst/nodes.py
+++ b/html2myst/nodes.py
@@ -199,7 +199,9 @@ def __str__(self):
 		return super().wrap_content()
 
 	def wrap(self, block):
-		lines = str(block).split('\n')
+		# a block (pre) can contain explicit line breaks using '\r',
+		# so use `splitlines()` instead of `split('\n')`
+		lines = str(block).splitlines()
 		content = ''
 		for index, line in enumerate(lines):
 			if index == 0 and len(line) == 0:
diff --git a/kits/application/message-filter.md b/kits/application/message-filter.md
index 5a92d08..ca2f63d 100644
--- a/kits/application/message-filter.md
+++ b/kits/application/message-filter.md
@@ -59,10 +59,10 @@ widths: auto
 Messages that don't fit the definition won't be sent to the object's filter
 function.
 
-The {hparam}`filter` argument is a pointer to a {cpp:func}`filter_hook`
+The {hparam}`filter` argument is a pointer to a {cpp:func}`filter_hook()`
 function. This is the function that's invoked when a message needs to be
-examined (see {cpp:func}`filter_hook` for the protocol). You don't have to
-supply a {cpp:func}`filter_hook` function; instead, you can implement
+examined (see {cpp:func}`filter_hook()` for the protocol). You don't have
+to supply a {cpp:func}`filter_hook()` function; instead, you can implement
 {hclass}`BMessageFilter`'s {cpp:func}`~BMessageFilter::Filter()` function
 in a subclass.
 
@@ -122,10 +122,10 @@ outside the message-passing mechanism), but keep in mind that it's the
 caller's responsibility to interpret the return value.
 
 Rather than implement the  function, you can supply the
-{hclass}`BMessageFilter` with a {cpp:func}`filter_hook` callback when you
-construct the object. If you do both, the {cpp:func}`filter_hook` (and not
-{hmethod}`Filter()`) will be invoked when the object is asked to examine a
-message.
+{hclass}`BMessageFilter` with a {cpp:func}`filter_hook()` callback when you
+construct the object. If you do both, the {cpp:func}`filter_hook()` (and
+not {hmethod}`Filter()`) will be invoked when the object is asked to
+examine a message.
 ::::
 
 ## Member Functions
diff --git a/kits/application/messenger.md b/kits/application/messenger.md
index 857cab4..a97e0fd 100644
--- a/kits/application/messenger.md
+++ b/kits/application/messenger.md
@@ -175,10 +175,12 @@ The target can respond to the message:
   and freeing {hparam}`reply`. {hparam}`message` and {hparam}`reply` can be
   the same object.
 
-  :::{admonition} Warning :class: warning Use caution when requesting a
-  synchronous reply: If you call {hmethod}`SendMessage()` from the target
-  looper's thread, you'll deadlock (or, at best, time out). :::
-
+- :::{admonition} Warning
+  :class: warning
+  Use caution when requesting a synchronous reply: If you call
+  {hmethod}`SendMessage()` from the target looper's thread, you'll deadlock
+  (or, at best, time out).
+  :::
 - If you supply a reply target ({hparam}`replyMessenger` or
   {hparam}`replyHandler`), the response is asynchronous, and is sent to the
   reply target.
diff --git a/kits/interface/picture.md b/kits/interface/picture.md
index 06b85ae..4f6eb5e 100644
--- a/kits/interface/picture.md
+++ b/kits/interface/picture.md
@@ -397,7 +397,9 @@ While many of these functions are similar to those found in
   radians, rather than in degrees. You can convert the value into degrees
   by using the forumla:
 
-  :::{code} cpp degrees = (rotation*180.0) / 3.14159265369); :::
+- :::{code} cpp
+  degrees = (rotation*180.0) / 3.14159265369);
+  :::
 ::::
 
 ## Static Functions
diff --git a/kits/storage/path.md b/kits/storage/path.md
index 9561c1e..b7d6bf2 100644
--- a/kits/storage/path.md
+++ b/kits/storage/path.md
@@ -263,9 +263,10 @@ Other details…
 
 - Destructive setting is safe:
 
-  :::{code} cpp /* This works... */
-path.SetTo(path.Path(), ...); :::
-
+- :::{code} cpp
+  /* This works... */
+  path.SetTo(path.Path(), ...);
+  :::
 - Currently, {hmethod}`SetTo()` only checks pathname and filename length if
   it has to normalize.
 
diff --git a/system-overview/application/message-filter.md b/system-overview/application/message-filter.md
index af272e3..75797c2 100644
--- a/system-overview/application/message-filter.md
+++ b/system-overview/application/message-filter.md
@@ -11,7 +11,7 @@ To define a message filter, you have to provide a message-filtering
 function. You do this by implementing the
 {cpp:func}`~BMessageFilter::Filter()` hook function in a
 {cpp:class}`BMessageFilter` subclass, or by supplying a
-{cpp:func}`filter_hook` function to the {cpp:class}`BMessageFilter`
+{cpp:func}`filter_hook()` function to the {cpp:class}`BMessageFilter`
 constructor. Only one filter function per object is called. If you
 implement {cpp:func}`~BMessageFilter::Filter()` and provide a filter_hook
 function, the filter_hook will win.
diff --git a/system-overview/interface/list-item.md b/system-overview/interface/list-item.md
index 48a9d12..af7414c 100644
--- a/system-overview/interface/list-item.md
+++ b/system-overview/interface/list-item.md
@@ -126,8 +126,9 @@ parameters:
   {cpp:class}`BListItem`. All drawing calls you issue should be made
   through this BView. For example:
 
-  :::{code} cpp owner->DrawString(item_text); :::
-
+- :::{code} cpp
+  owner->DrawString(item_text);
+  :::
 - A {cpp:class}`BRect`, which is the rectangle in which the item should be
   drawn.
 
diff --git a/topics/device-drivers/driver-settings-api.md b/topics/device-drivers/driver-settings-api.md
index ff32e8a..013583f 100644
--- a/topics/device-drivers/driver-settings-api.md
+++ b/topics/device-drivers/driver-settings-api.md
@@ -46,10 +46,11 @@ The settings file is formatted like this:
 - Parameters can have values and subparameters. A parameter has the
   following form in the settings file:
 
-  :::{code} sh name [value]* [{
-[parameter]*
-}] ['n',','] :::
-
+- :::{code} sh
+  name [value]* [{
+  [parameter]*
+  }] ['n',',']
+  :::
   Where [ … ] indicates an optional part, and [ … ]* indicates an optional
   repeated part.