Health sciences education: materials, pronunciation, and study workflows

This report says what students and faculty in medicine, nursing, dentistry, pharmacy, physician assistant programs, public health, and biomedical research need from a reading and writing tool, and what textweaver should build for them. It is for the maintainers planning alpha.8 and alpha.9, and for the accommodations office that will deploy it. Written Friday, October 2, 2026, against the repository at 0.1.0-alpha.7. Claims about textweaver's own behavior marked "measured" were checked that day by running the normalization pipeline from crates/textweaver-speech/src/normalize/mod.rs on clinical sentences through a scratch program kept outside the repository.

Who the users are

According to PubMed, Meeks and colleagues surveyed US medical schools in 2016 and 2019 and found more students disclosing a disability, with ADHD, learning disabilities, and psychological disabilities the largest groups (DOI, source 17). In a national AAMC questionnaire, 10.2 percent of responding second-year students reported a disability and half of them used accommodations (DOI, source 18). A reading tool serves alternate formats and text-to-speech. Faculty and the office are the second user group: they convert course packs, check documents before posting, and keep records.

1. The materials

The table lists each kind of material, what breaks when it is read aloud, and what textweaver does today, naming the file.

What a reader must do for all of these: keep reading order, say tables as tables, name symbols the engine would skip, expand only the abbreviations that are safe to expand, and let the student fix a pronunciation once and keep it.

2. Pronunciation

How engines go wrong

Rule-based engines pronounce an unknown word by letter-to-sound rules. espeak-ng's English word list en_list has 5,794 lines and its rule file 7,132 (source 27). On Friday, October 2, 2026, en_list had no entry for acetaminophen, metformin, warfarin, lisinopril, atorvastatin, dyspnea, or ischemia, so each is read by rule. Piper voices take their phonemes from espeak-ng (crates/textweaver-piper/src/phonemes.rs; the Piper project embeds espeak-ng, source 28), so a Piper voice inherits every espeak-ng mistake, however natural it sounds. The failures that matter:

• stress on the wrong syllable in drug names and anatomical compounds;
• "-emia", "-itis", "-ectomy" endings with the wrong vowel;
• French and German eponyms (Guillain-Barré, Sjögren, Raynaud, Wernicke) read as English;
• look-alike pairs read alike (hydroxyzine, hydralazine), a safety problem;
• Tall Man capitals split. Measured with split caps on: "hydrOXYzine" becomes "hydr OX Yzine" and "DOPamine" becomes "DO Pamine" (normalize/punctuation.rs, SplitCaps).

Term sources and their licenses

Tall Man lettering is made for labels. A nine-year series in 42 children's hospitals found no change in look-alike error rates after it was introduced (DOI, source 15), and a study of 7,987 nonproprietary names showed how shared stems make names similar by design (DOI, source 16). For speech the lesson is to make the two names sound different by stress and syllable, not by capitals.

Lexicon formats the engines accept

• CMUdict ARPAbet: W AO1 R F ER0 IH0 N, respelled for reading aloud as WAR-fuh-rin (crates/textweaver-lexicon/src/pronounce.rs).
• espeak-ng: its own mnemonics in en_list, plus an en_extra file for user words, compiled into en_dict (source 26). Whether the bundled Rust port compiles en_extra is unverified.
• Piper: IPA, one id per character from the voice's phoneme_id_map (crates/textweaver-piper/src/config.rs); textweaver builds the id list itself in phonemes.rs::prepare.
• SAPI 5: ISpLexicon::AddPronunciation adds a word in the SAPI phone set to a user lexicon shared by every application (source 29).
• Eloquence: main, abbr, and root dictionaries, one word<TAB>respelling per line (normalize/community.rs).
• NVDA: default, voice, and temporary dictionaries; an entry is a pattern, a text replacement, case sensitivity, and a type of anywhere, whole word, or regular expression (source 30).
• JAWS: Dictionary Manager writes .jdf files, one default and one per application (source 31).

A student on NVDA or JAWS already keeps a dictionary; textweaver should import it.

Proposal: a medical lexicon

Data. Ship lexicon/medical-en.toml, a term = "respelling" file in the format [normalization.pronunciations] already reads (speech guide), with an optional IPA column for Piper. Seed it with the Telnyx data (966 entries, credited in THIRD-PARTY-NOTICES.md), then grow it to about 2,500 entries from RxNorm ingredient names and the top terms of the medical word list, with respellings checked by ear. Record sources and checksums in third_party/, as third_party/lexicon/README.md does. About 120 KB on disk; no binary growth.

Pipeline. The Pronunciations transform (normalize/abbreviations.rs) builds one regular expression alternation of every term, rebuilt whenever settings change. That is right for a few dozen user entries and wrong for 2,500. Add a MedicalLexicon transform modeled on CommunityLexicon (community.rs): a hash map lookup per word, lower-casing a capitalized word and splitting a hyphenated one. Order: user entries, then medical, then community, so the student always wins. Switch: [normalization.medical_lexicon] enabled, on in a health sciences profile. For Piper, a hook in phonemes.rs::prepare cuts out words with an IPA entry before the clause is phonemized and splices the IPA in with its word owner, so the highlight stays exact.

Run-time cost. One hash lookup per word on the speech thread, where normalization already runs before the two-sentence lookahead (architecture); nothing on the input thread. Budget: no measurable change in cargo xtask bench --only first_speech on 1 MB and under 5 percent on the 10 MB narration plan. Loading 2,500 lines takes about a millisecond.

Adding terms. For a student: a palette command add pronunciation on the word at the cursor, which asks for the respelling, says it back, and writes [normalization.pronunciations], which already syncs (sync guide). For an office: [normalization] lexicon_files = ["\\\\share\\osa\\pronunciations.toml"], read at startup and when changed, so one coordinator maintains it for every student. tw lexicon import nvda.dic and tw lexicon import jaws.jdf take whole-word text entries and report the rest. tw speak --backend null --json shows what will be said (math.md).

Twenty test terms

Each row is a test for the lexicon. The expected column is the respelling the lexicon carries; what each engine says without it is to be checked by ear and is not claimed here.

3. Numbers, units, and safety

Measured outputs of the default pipeline (punctuation "some", split caps off, engine without native normalization), and what a health sciences reader needs.

A European decimal comma, "2,5%", is read as "2,five percent" and should follow the document language.

What an abbreviation expander must never expand

The ISMP List of Error-Prone Abbreviations (source 11, updated 2024, source 12) and The Joint Commission's Do Not Use list, summarized by Wick (DOI, source 47), name abbreviations that caused harm because they are misread. A reader has the same problem in sound. Rule: an abbreviation on those lists is spelled letter by letter, never guessed, and at high verbosity the reader adds "error-prone abbreviation". The deny list, checked in normalize/abbreviations.rs before any expansion:

• U and IU: spell; a lexicon may say "units" only after a number and a known drug.
• QD, QOD, q.d., q.o.d.: spell, never "every day" or "four times".
• MS, MSO4, MgSO4: spell; morphine and magnesium must not be guessed.
• cc: spell; mL is the unit to expand. µg: say "micrograms", because the symbol is the hazard.
• SC, SQ, HS, TIW, AD, AS, AU, OD, OS, OU: spell.
• "@", "<", ">": name the symbol, which punctuation.rs already does.
• Trailing zero and missing leading zero: read the digits as written; measured, both are right today.
• Drug-name abbreviations such as TPA and HCTZ: spell, never expand to a drug.

Safe expansions: PRN, PO, BID, TID, QID, q4h, q6h, q8h, NPO, stat.

Tests to add

Add clinical_vectors to crates/textweaver-speech/src/normalize/tests.rs, in the style of normalize_numbers_vectors: the table above, the deny list (each entry unchanged or spelled), the range rule, the identifier rule (CPT, PMID, NCT, ZIP, DOI, ISBN, phone), and the 24-hour time rule, each checking the offset-map invariants so a dosage expansion still highlights "5 mg".

4. Math and chemistry

Statistics and pharmacokinetics formulas written as LaTeX are already spoken well. Measured:

• $\chi^2 = 3.84$: "chi squared equals three point eight four".
• $\hat{\beta}_1 \pm 1.96\,\mathrm{SE}$: "beta hat sub 1 plus or minus one point nine six SE".
• $\bar{x} \pm \frac{s}{\sqrt{n}}$: "x bar plus or minus the fraction with numerator s and denominator square root of n".
• $t_{1/2} = \frac{0.693}{k_e}$: "t sub 1 divided by 2 end sub equals the fraction with numerator zero point six nine three and denominator k sub e".
• $C(t) = C_0 e^{-k_e t}$: "C t equals C sub 0 e raised to the negative k sub e t power".
• $\mathrm{CL} = \frac{\text{Dose}}{\mathrm{AUC}}$: "CL equals the fraction with numerator Dose and denominator AUC".

Two gaps. "t sub 1 divided by 2" should be "t one half"; a table of named subscripts (1/2, max, ss) in crates/textweaver-math fixes it. And most statistics in papers is prose, so the range rule in section 3 matters more than the math engine.

MathCAT (ADR-0029) has a Chemistry preference whose default reads "H two O" for H₂O and whose Off value says "H sub 2 O" (source 32). It applies only to MathML inside math delimiters. textweaver's own engine does not know mhchem: $\ce{Na+ + Cl- -> NaCl}$ is "ce N a plus positive C l minus negative greater than N a C l" (measured). mhchem is the standard LaTeX and MathJax package for formulas and equations (source 33); Chemical Markup Language is the XML form (source 34) and SMILES the line notation (source 35), and students almost never meet either.

Alpha scope:

1. \ce{} in crates/textweaver-math: elements by name or letter at the student's choice, digits as counts, trailing + and - as charge, -> as "yields", <=> as "in equilibrium with", ^ for isotope mass, and (s), (l), (g), (aq) as states. Medium. tw convert can emit the formula as <mi> and <msub> so MathCAT's rules apply in a browser.
2. A plain-text formula reader, off by default: tokens matching element, digit, and charge patterns ("Ca2+", "NaCl") spoken as formulas. Small, after item 1.
3. CML and SMILES: out of scope; read as code.

5. Study workflows

Reading a chapter before lecture

The student hears the outline (Alt+O, reading guide), summarizes the chapter at the cursor (ADR-0037; tw summarize), checks the reading level, and reads at speed. Rate runs from 50 to 900 words per minute, default 265 (docs/speech.md). The largest study of listening rates, 453 participants on LabintheWild, found a mean comprehension-limited rate near 300 words per minute, with visually impaired participants faster and each year of screen reader experience adding to it (source 36). A health sciences profile should preset study near 300 and review near 450 through the F8 presets (speech guide). For Piper, synthesis must stay ahead of playback at 450, so the two-sentence lookahead (architecture) should be measured at that rate on the slowest supported machine, with cargo xtask bench --only first_speech as the proxy.

Re-reading with highlights and making study sheets

Highlights are yellow only, with no key to choose a color (notes guide). Students sort passages by kind: high-yield, unclear, drug, mechanism. The fix is categories, not colors: a named category from a list, spoken by name, shown by the theme's styles, exported under its name. The study sheet export groups notes and highlights by heading (export study sheet, crates/textweaver-app/src/study.rs); add a category filter there and in the highlights list. The Obsidian vault export writes one note per textweaver note with front matter and tags (vault guide). For flashcards without spaced repetition (out of scope, roadmap), tw marks --export csv with question and answer columns from notes written as "Q: ... A: ..." lets any tool import them.

Spaced re-reading

Spaced re-reading means returning to a chapter on a schedule the student sets. textweaver records reading time, furthest point, and sessions per document (reading statistics; tw stats), and Continue reading lists documents by last place (library guide). A Review list ordered by days since last read and by notes tagged #review is a small addition on the same list model and stats.json.

Citing in APA and AMA, PubMed and DOI lookups

tw cite formats APA and AMA among about 80 styles and adds references by DOI through doi.org (citations guide). Health sciences students cite by PMID as often. NCBI's E-utilities serve PubMed records at three requests a second without a key and ten with one (source 43). Add tw cite add PMID:31769816: one efetch call, the DOI from the record when it has one, else CSL-JSON built from the PubMed XML, cached like DOI answers. The planned PubMed quick-open (roadmap) can use the same call to open an abstract as a document with its citation already in the folder library.

Clinical rotations

textweaver is desktop software; on rotation a student has a phone and a few minutes. Audio export is the mobile path: tw export-audio writes M4B audiobooks with a chapter per heading (audio export guide). Sync carries notes, highlights, places, and statistics between computers, not to a phone (sync guide); the study sheet and vault export are Markdown, which Obsidian Mobile reads. A pocket export of only the highlighted passages and their notes, as one short audio file plus a sheet, is the ten-minute review a rotation student needs.

6. Faculty and office workflows

Converting a course pack

A course pack arrives as a zip from the LMS, a folder of PDFs, or a scanned reader. tw convert converts a folder, converts only what changed, and watches a folder (converting guide); archives open directly and scanned pages are recognized with a cache (ADR-0026). Output is tagged PDF checked against PDF/UA-1 while writing (crates/textweaver-writers/src/lib.rs), EPUB 3, DOCX, HTML, and BRF. Missing is a report: which files were OCR'd and with which engine, which had no headings, which images had no description, word counts, and listening time at 265 words per minute. That report is what the office files with the request.

Checking a document before posting

The Department of Justice rule under ADA Title II requires WCAG 2.1 AA of state and local government web content, public universities included, from April 2026 for entities serving 50,000 or more people (source 41). Anthology Ally answers "is this PDF all right to post?" inside the LMS with a score and instructor feedback (source 40). textweaver checks its own output but has no checker for an input document. A tw check FILE that runs the loaders and reports scanned pages without a text layer, missing title and language, skipped heading levels, tables without a header row, images without alternative text, columns detected rather than tagged, and error-prone abbreviations gives faculty an offline answer in seconds. tw lint (editing guide) is the pattern: one line per problem, status 1, --json.

A report for an accommodation file

tw marks --json and tw stats --json already print notes, highlights, places, and reading time (notes guide). A tw report combining the conversion report, checksums, engines used, and dates, with no reading data unless the student exports it, fits how an office documents a request. Reading data belongs to the student; sync never sends recent files for that reason (sync guide).

Bookshare and AccessText Network

Bookshare serves people with a certified print disability, free to US students through an OSEP award, in DAISY and BRF among other formats (source 37); textweaver opens DAISY 3 books and Bookshare zips (ADR-0026). The AccessText Network is the publishers' clearinghouse through which offices request files for qualifying students; member offices report most requests filled within a day and nearly all within three (sources 38). Those files are usually PDF, with or without tags, which is where the PDF loader and OCR earn their keep.

Time per request today

No formal survey of hours per request was found. Institutions publish turnaround times: a few hours to several days per scanned book, two days to two weeks when the office must cut and scan, five to ten business days, up to four weeks with editing (source 39). The time goes to four steps: finding a publisher file, scanning, recognition with structure repair, and delivery. textweaver removes most of the third: OCR with layout recovery, running heads removed, columns in order, headings by size, and audio or EPUB with chapters, in seconds per chapter rather than hours. The honest estimate: a scan-and-convert request drops from days to the same day, and the publisher-file wait is untouched.

7. Ranked improvements

Small is hours, medium a day or two, large a week or more. Every item works with a screen reader, a braille display, and the keyboard alone, and shows no state by color alone.

Sources

1. https://support.vitalsource.com/hc/en-us/p/accessibility
2. https://success.vitalsource.com/hc/en-us/articles/360026396654
3. https://about.redshelf.com/accessibility
4. https://solve.redshelf.com/hc/en-us/articles/360015237493-Text-to-Speech-TTS
5. https://leap.ocls.ca/node/1605 (NOSM University assessment of AccessMedicine; not reachable from this machine, unverified)
6. https://www.elsevier.support/ckstudent/answer/what-is-clinicalkey-students-accessibility-policy
7. https://download.lww.com/vpat/wk-thepoint-accessibility.pdf
8. https://www.uworld.com/assets/data/Ada_Request_Form.pdf
9. https://castreader.com/en/blog/uworld-text-to-speech (third party, unverified)
10. https://www.ncbi.nlm.nih.gov/books/ (NCBI Bookshelf, where StatPearls is published)
11. https://home.ecri.org/blogs/ismp-resources/list-of-error-prone-abbreviations
12. https://home.ecri.org/blogs/ismp-news/ismp-updates-list-of-error-prone-abbreviations-symbols-and-dose-designations
13. https://www.fda.gov/drugs/medication-errors-related-cder-regulated-drug-products/fda-name-differentiation-project
14. https://online.ecri.org/hubfs/ISMP/Resources/ISMP_Look-Alike_Tallman_Letters.pdf
15. https://doi.org/10.1136/bmjqs-2015-004562 (Zhong and others, 2016, via PubMed)
16. https://doi.org/10.1371/journal.pone.0145431 (Bryan and others, 2015, via PubMed)
17. https://doi.org/10.1001/jama.2019.15372 (Meeks and others, 2019, via PubMed)
18. https://doi.org/10.1111/medu.14995 (Meeks and others, 2022, via PubMed)
19. https://www.nlm.nih.gov/databases/umls.html
20. https://www.nlm.nih.gov/research/umls/Snomed/snomed_license.html
21. https://www.nlm.nih.gov/research/umls/rxnorm/docs/termsofservice.html
22. https://github.com/cmusphinx/cmudict
23. https://github.com/team-telnyx/medical-pronunciation-dictionary
24. https://github.com/open-dict-data/ipa-dict
25. https://github.com/glutanimate/wordlist-medicalterms-en
26. https://github.com/espeak-ng/espeak-ng/blob/master/docs/dictionary.md
27. https://github.com/espeak-ng/espeak-ng/blob/master/dictsource/en_list
28. https://github.com/OHF-Voice/piper1-gpl
29. https://msdn.microsoft.com/en-us/library/ms717899.aspx (ISpLexicon, SAPI 5.3)
30. https://www.nvaccess.org/files/nvda/documentation/userGuide.html (NVDA User Guide, Speech Dictionaries)
31. https://support.freedomscientific.com/teachers/lessons/9.1_DictionaryManagerIntroduction.htm
32. https://github.com/NSoiffer/MathCAT/blob/main/docs/users.md
33. https://ctan.org/pkg/mhchem
34. http://www.xml-cml.org/
35. http://opensmiles.org/opensmiles.html
36. https://par.nsf.gov/biblio/10063856 (Bragg and others, CHI 2018) and https://doi.org/10.1145/3461700 (the 2021 expansion)
37. https://www.bookshare.org/cms/node/60
38. https://ati.gmu.edu/accessible-text/accessible-textbooks/ and https://news.uga.edu/access-text-network-created-in-collaboration-with-uga-will-improve-student/
39. https://accessibility.ucdavis.edu/textbooks , https://www.uh.edu/accessibility/accommodations/alternate-format-textbooks/ , https://www.towson.edu/accessibility-disability-services/accommodations-services/print-materials.html , https://ds.oregonstate.edu/book/das-student-handbook/chapter-7-accommodation-spelling
40. https://help.blackboard.com/Learn/Administrator/Hosting/Tools_Management/Ally
41. https://doit.illinois.gov/doit-news/accessibility-news/doj-finalizes-rule-on-web-and-mobile-accessibility.html
42. https://www.w3.org/TR/pronunciation-use-cases/
43. https://www.ncbi.nlm.nih.gov/books/NBK25497/ (E-utilities)
44. https://www.mheducation.com/unitas/highered/accessibility/mckinley-human-anatomy-6e.pdf (a McGraw Hill per-title accessibility report)
45. https://www.mass.gov/doc/nclex-applicants-requesting-test-accommodations-due-to-a-disability-0/download
46. https://link.springer.com/chapter/10.1007/978-3-031-08648-9_30 and https://www.perkins.org/resource/how-to-modify-accessible-anatomy-graphics-for-low-vision/
47. https://doi.org/10.4140/tcp.n.2007.870 (Wick, 2007, via PubMed)

See also

• README.md: the research index in this folder.
• Reading and writing math: how formulas are spoken and explored.
• Citations and references: tw cite, APA, AMA, DOI lookups.
• Bookmarks, notes, and highlights: study sheets and exports.
• ADR-0026: OCR, and formats for students: scans, DAISY, archives, slides.
• ADR-0010: PDF loader: columns, running heads, tables.
• ADR-0025: Define word offline: the CMUdict data file.
• Speech: pronunciations, the community lexicon, rate presets.
• Architecture: the speech thread and where normalization runs.