From 5600947e3c07ecc4cba99eb2e97d9f902d41fd33 Mon Sep 17 00:00:00 2001 From: Craig Jennings Date: Sun, 28 Jun 2026 03:39:46 -0400 Subject: docs: condense module commentaries to the terse header contract 22 module headers carried long user-manual commentaries (quick-starts, keybinding matrices, setup walkthroughs) that belong in user docs, not source. Each now states the purpose, load contract, and entry points tersely. ai-term also drops its stale F9 keybinding references (the scheme is C-; a plus M-SPC now) and a header line claiming a vertical-split that's really host-aware. --- custom/profile-dotemacs.el | 53 +++-------------- custom/titlecase-data.el | 92 +++--------------------------- custom/utilities/vcf-conversion-helpers.el | 3 + 3 files changed, 17 insertions(+), 131 deletions(-) (limited to 'custom') diff --git a/custom/profile-dotemacs.el b/custom/profile-dotemacs.el index f16e8652f..8baee47b2 100644 --- a/custom/profile-dotemacs.el +++ b/custom/profile-dotemacs.el @@ -20,55 +20,16 @@ ;; along with this program. If not, see . ;;; Commentary: - -;; This is to easily profile your Emacs init file (or any other -;; script-like Emacs Lisp file, for that matter). - -;; It will go over all sexp's (balanced expressions) in the file and -;; run them through `benchmark-run'. It will then show the file with -;; overlays applied in a way that let you easily find out which sexp's -;; take the most time. Since time is relative, it's not the absolute -;; value that counts but the percentage of the total running time. ;; -;; * All other sexp's with a percentage greater than -;; `profile-dotemacs-low-percentage' will be preceded by a -;; highlighted line, showing the results from `benchmark-run'. -;; Also, the more 'reddish' the background of the sexp, the more -;; time it needs. - -;; * All other sexp's will be grayed out to indicate that their -;; running time is miniscule. You can still see the benchmark -;; results in the minibuffer by hovering over the sexp with the -;; mouse. - -;; You can only benchmark full sexp's, so if you wrapped large parts -;; of your init file in some conditional clause, you'll have to remove -;; that for getting finer granularity. - -;;; Usage: - -;; Start emacs as follows: +;; Profiles profile-dotemacs-file by evaluating top-level sexps with +;; benchmark-run, then overlays the source buffer so expensive forms stand out +;; by percentage of total runtime. ;; -;; emacs -Q -l /profile-dotemacs.el -f profile-dotemacs +;; Run with: +;; emacs -Q -l /path/to/profile-dotemacs.el -f profile-dotemacs ;; -;; with being the path to where this file resides. - -;;; Caveats (thanks to Raffaele Ricciardi for reporting those): - -;; - The usual `--debug-init' for debugging your init file won't work -;; with profile-dotemacs, so you'll have to call -;; `toggle-debug-on-error', either on the commandline or at the -;; beginning of your init file. -;; - `load-file-name' is nil when the init file is being loaded -;; by the profiler. This might matter if you perform the -;; bulk of initializations in a different file. -;; - Starting external shells like IELM or eshell in your init file -;; might mess with overlay creation, so this must not be done. - -;;; Download: - -;; You can always get the latest version from -;; http://randomsample.de/profile-dotemacs.el +;; Full sexps are the unit of measurement; split large conditional blocks before +;; profiling if finer detail is needed. ;;; Code: diff --git a/custom/titlecase-data.el b/custom/titlecase-data.el index a64685861..7415a2104 100644 --- a/custom/titlecase-data.el +++ b/custom/titlecase-data.el @@ -18,91 +18,13 @@ ;; along with this program. If not, see . ;;; Commentary: - -;; Since the `titlecase' package requires a lot of data, that data lives here so -;; as to not clog up the main package. - -;; Since [[https://github.com/duckwork/titlecase.el/issues/23][Issue #23]] makes -;; a good point that I should like, make more sense in the commentary and README -;; of this repository. At the same time, those couple of comments I wrote in -;; there I don't want to just /delete/, so until I write this up in a proper -;; blog post, I've included it here, in the data file, because this is where -;; these implementation notes will be of most interest. - -;; The only setting you really should need to set is =titlecase-style=, which -;; see. Each of these styles has a different set of rules regarding which words -;; to capitalize in a title. After you've set =titlecase-style=, you can bind -;; the command =titlecase-dwim= to a key, or call it using M-x, and it will -;; either title-case your region (if it's active) or the current line. - -;; The tricky part is figuring out what words to capitalize in the title. - -;; Articles (~a~, ~an~, ~the~) are downcased. - -;; The first word of a title and all "important words" (generally nouns, -;; pronouns, adjectives, verbs, and adverbs) are capitalized. The last word of -;; a title is always capitalized, but only in Chicago, AP, Bluebook, AMA, NY -;; Times, and Wikipedia. - -;; /All/ prepositions are downcased in Chicago, MLA, AP, NY Times, and -;; Wikipedia, regardless of length; for APA, Bluebook, AMA, and Wikipedia, only -;; prepositions shorter than 5 letters are (presumably, capitalize those longer -;; than 5 letters, however only Wikipedia was clear on that point). - -;; Coordinating conjunctions are capitalized in Chicago and APA (presumably), -;; but downcased in MLA, AP, Bluebook, AMA, NY Times, and Wikipedia. - -;; Hyphenated words are tricky: I could possibly figure out a way to have lookup -;; tables to determine when to capitalize the second part of a hyphenated word, -;; but I haven't implemented them yet. At any rate, the rules tend to be vague -;; enough that it's hard to program anyway: For example, Chicago, APA, MLA, and -;; AP lowercase the second word "after a hyphenated prefix (e.g., Mid-, Anti-, -;; Super, etc.) in compound modifiers," but MLA and APA capitalize the second -;; part of "hyphenated major words (e.g., Self-Report not Self-report). - -;; Perhaps unsurprisingly, the AMA (American Medical Association, used in the -;; scientific community) has the most comprehensive capitalization rules around -;; hyphenated words. I'll just copy-paste the bullet points here: - -;; - Lowercase the second word in a hyphenated compound when it is -;; a prefix or suffix (e.g., "Anti-itch","world-wide") or part of a single word. -;; - Capitalize the second word in a hyphenated compound if both words are equal -;; and not suffices or prefixes (e.g., "Cost-Benefit") -;; - Capitalize the first non-Greek letter after a lowercase Greek letter (e.g., -;; "ω-Bromohexanoic") -;; - Lowercase the first non-Greek letter after a capital Greek letter (e.g., -;; "Δ-9-tetrahydrocannabinol") #+end_quote - -;; (The AMA also has a rule about capitilizing the genus but not species -;; epithet, but the lookup on that would be wild as hell, so I trust yall to -;; know on that one.) - -;; ~To~ as an infinitive is downcased in all /except/ AP. This is a rule I -;; simply cannot implement without knowing whether the /next/ word is a verb, -;; which would require expensive lookups, which even then wouldn't be foolproof. - -;; Now that I'm thinking about it, most styles count phrasal verbs (like "play -;; with") as important enough to capitalize, when "with" would usually /not/ be -;; capitalized, but again, open categories like phrasal verbs simply do not work -;; in a package like this. - -;; ALL OF THIS IS TO SAY that titlecase offers a best-effort attempt to -;; titlecase a line or region of text, but you should absolutely -;; double-triple-check against the style guide you're writing for if you're -;; trying for publication or something like that. - -;; SEE ALSO: - -;; Prior art: - -;; - https://emacs.stackexchange.com/questions/66361/#66362 -;; - https://github.com/novoid/title-capitalization.el -;; - https://hungyi.net/posts/programmers-way-to-title-case/ - -;; Rules: - -;; - https://capitalizemytitle.com/#capitalizationrules -;; - https://titlecaseconverter.com/rules/ +;; +;; Data tables for titlecase.el: style-specific lowercase word lists, phrasal +;; verbs, and exceptions used by the title-casing engine. +;; +;; Title casing is best-effort because English style guides disagree and some +;; cases require grammatical knowledge this package does not model. Proofread +;; output before publication. ;;; Code: diff --git a/custom/utilities/vcf-conversion-helpers.el b/custom/utilities/vcf-conversion-helpers.el index 334edc4e2..d336eac8e 100644 --- a/custom/utilities/vcf-conversion-helpers.el +++ b/custom/utilities/vcf-conversion-helpers.el @@ -2,6 +2,9 @@ ;;; Commentary: ;; +;; Helpers for converting exported VCF contacts into org-contacts data. The +;; cleaner normalizes folded fields, birthdays, item-prefixed email/phone fields, +;; and removes cards without useful identifying data before import. ;;; Code: -- cgit v1.2.3