From 432a1dc223ab0a29c897fb08dd5435e2bd80e364 Mon Sep 17 00:00:00 2001 From: deeaitch Date: Fri, 28 Aug 2026 00:46:33 -0400 Subject: [PATCH] Rename project to kindle2notes --- CMakeLists.txt | 20 +--- LICENSE | 4 +- README.md | 178 +++++++++++++++----------------- typefactory/convertmarkdown.cpp | 7 -- typefactory/kindle2latex.pro | 7 -- typefactory/kindle2notes.pro | 17 +++ typefactory/typefactory.pro | 1 + 7 files changed, 110 insertions(+), 124 deletions(-) delete mode 100644 typefactory/kindle2latex.pro create mode 100644 typefactory/kindle2notes.pro diff --git a/CMakeLists.txt b/CMakeLists.txt index 81899d7..2500489 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1,12 +1,12 @@ cmake_minimum_required(VERSION 3.16) -project(kindle2latex LANGUAGES CXX) +project(kindle2notes LANGUAGES CXX) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) set(CMAKE_CXX_EXTENSIONS OFF) -function(kindle2latex_enable_warnings target) +function(kindle2notes_enable_warnings target) if(MSVC) target_compile_options(${target} PRIVATE /W4) else() @@ -14,7 +14,7 @@ function(kindle2latex_enable_warnings target) endif() endfunction() -add_executable(kindle2latex_typefactory +add_executable(kindle2notes typefactory/convertlatex.cpp typefactory/convertlatex.h typefactory/convertmarkdown.cpp @@ -24,16 +24,4 @@ add_executable(kindle2latex_typefactory typefactory/main.cpp typefactory/typefactory.h ) -set_target_properties(kindle2latex_typefactory PROPERTIES - OUTPUT_NAME kindle2latex-typefactory -) -kindle2latex_enable_warnings(kindle2latex_typefactory) - -add_executable(kindle2latex_fsm - fsm/main.cpp - fsm/fsm.h -) -set_target_properties(kindle2latex_fsm PROPERTIES - OUTPUT_NAME kindle2latex-fsm -) -kindle2latex_enable_warnings(kindle2latex_fsm) +kindle2notes_enable_warnings(kindle2notes) diff --git a/LICENSE b/LICENSE index fa083b0..cd63fbd 100644 --- a/LICENSE +++ b/LICENSE @@ -208,7 +208,7 @@ If you develop a new program, and you want it to be of the greatest possible use To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively state the exclusion of warranty; and each file should have at least the “copyright” line and a pointer to where the full notice is found. - kindle2latex + kindle2notes Copyright (C) 2026 gpl This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. @@ -221,7 +221,7 @@ Also add information on how to contact you by electronic and paper mail. If the program does terminal interaction, make it output a short notice like this when it starts in an interactive mode: - kindle2latex Copyright (C) 2026 gpl + kindle2notes Copyright (C) 2026 gpl This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'. This is free software, and you are welcome to redistribute it under certain conditions; type `show c' for details. diff --git a/README.md b/README.md index c5ff238..fecf9ab 100644 --- a/README.md +++ b/README.md @@ -1,68 +1,21 @@ -# Kindle Clippings → LaTeX Converter +# kindle2notes -A small console utility that converts Amazon Kindle *My Clippings* text exports into structured LaTeX. +`kindle2notes` is a small C++17 command-line utility that converts Amazon +Kindle `My Clippings.txt` exports into structured notes. -The tool parses Kindle highlights and groups them by book title, producing a LaTeX structure with: +Supported output formats: -* `\section{}` — per book -* `\subsection{}` — per highlight (metadata line) -* Highlight text — inserted as plain LaTeX content -* `\subsubsection{notes}` — placeholder for future comments +- LaTeX (`--type=latex`) +- Markdown (`--type=md`) ---- +Highlights are grouped by book title while preserving the order in which +books first appear in the input file. -## Architecture +## Input format -This project demonstrates **two different parsing approaches** solving the same problem: +Each Kindle clipping is expected to have the following structure: -### 1️⃣ FSM-based parser - -Implemented using a template-based finite state machine (`fsm.h`). - -Characteristics: - -* Compile-time validated transitions -* Strong type safety -* Explicit state/event model -* Strict contract enforcement - -This version is useful when: - -* The input format is more complex -* You want compile-time guarantees for state transitions -* The parsing logic may grow over time - ---- - -### 2️⃣ TypeFactory-based parser - -Implemented using a registration-based factory (`typefactory.h`). - -Characteristics: - -* Stage-driven pipeline -* One handler per parsing stage -* Runtime validation of handler registration -* No per-line allocations (handlers cached once) - -This version is: - -* Simpler -* More readable -* Easier to debug -* Well suited for linear, protocol-like formats - -Both implementations produce identical LaTeX output. - ---- - -## Input Format - -Expected input is a standard Kindle `My Clippings.txt` export. - -Each clipping block follows this structure: - -``` +```text Book Title - Your Highlight on Location 123-125 | Added on ... @@ -71,65 +24,106 @@ Highlighted text line 2 ========== ``` ---- +The final clipping is processed even when the file does not end with the +`==========` separator. Incomplete clipping blocks are ignored. -## Output Format +## Output formats -Generated LaTeX structure: +### LaTeX + +Books become sections, clipping metadata becomes subsections, and every +highlight receives an empty notes subsection: ```latex -\section{Book Title} - - \subsection{- Your Highlight on Location 123-125 | Added on ...} +\section {Book Title} + \subsection {- Your Highlight on Location 123-125 | Added on ...} Highlighted text line 1 Highlighted text line 2 \subsubsection{notes} ``` -Highlights are grouped by book title. +LaTeX special characters are escaped automatically. ---- +### Markdown + +Books and clipping metadata become headings. Highlight text is emitted as a +Markdown block quote, followed by an empty notes heading: + +```markdown +# Book Title + +## - Your Highlight on Location 123-125 | Added on ... + +> Highlighted text line 1 +> Highlighted text line 2 + +### Notes +``` + +Empty lines inside highlights are preserved as `>` lines, and Markdown syntax +characters are escaped automatically. + +## Architecture + +Input parsing is implemented as a stage-driven pipeline with one handler for +each stage: title, metadata, and body. Handlers are registered and created +through the generic `TypeFactory` template, then cached for reuse while the +input is read. + +Output generation uses a common abstract `Converter` interface. Concrete +converters are registered in another `TypeFactory` under their command-line +type names. The selected converter is created at runtime and invoked through +the common virtual `save()` method. Adding a new output format requires a new +`Converter` subclass and a corresponding factory registration. ## Build -Requires a C++17-compatible compiler. +The project has no Qt dependency. It requires a C++17 compiler and CMake 3.16 +or newer. ```bash -g++ -std=gnu++17 -Wall -Wextra -O2 -o kindle2latex main.cpp +cmake -S . -B build -DCMAKE_BUILD_TYPE=Release +cmake --build build --parallel ``` ---- +The resulting executable is: + +```text +build/kindle2notes +``` ## Usage +Generate LaTeX: + ```bash -./kindle2latex --input input.txt --output output.tex +./build/kindle2notes \ + --input "My Clippings.txt" \ + --output notes.tex \ + --type=latex ``` -Arguments: +Generate Markdown: -| Argument | Description | -| ---------- | ----------------------------- | -| `--input` | Path to Kindle clippings file | -| `--output` | Path to generated LaTeX file | +```bash +./build/kindle2notes \ + --input "My Clippings.txt" \ + --output notes.md \ + --type=md +``` ---- +Short options are also available: -## Design Notes +```bash +./build/kindle2notes -i input.txt -o notes.md -t md +``` -* No dynamic allocations per input line (handlers are cached). -* Order of books is preserved as in the original file. -* LaTeX special characters are escaped automatically. -* Incomplete clipping blocks are safely ignored. -* The final block is flushed even if the file does not end with `==========`. +| Argument | Short form | Description | +| --- | --- | --- | +| `--input` | `-i` | Path to the Kindle clippings file | +| `--output` | `-o` | Path to the generated file | +| `--type` | `-t` | Output format: `latex` or `md` | +| `--help` | `-h` | Show usage information | ---- - -## Why Two Implementations? - -This repository intentionally keeps two different parsing styles: - -* The FSM version demonstrates strict compile-time state control. -* The TypeFactory version demonstrates a clean, extensible runtime pipeline. - -The goal is architectural exploration and comparison, not just solving the parsing task. +If an unsupported output type is requested, the program prints the list of +available formats and exits without creating an output file. diff --git a/typefactory/convertmarkdown.cpp b/typefactory/convertmarkdown.cpp index dcfbdbd..0bd3024 100644 --- a/typefactory/convertmarkdown.cpp +++ b/typefactory/convertmarkdown.cpp @@ -11,18 +11,11 @@ static bool markdown_needs_escape (char ch) { case '`': case '*': case '_': - case '{': - case '}': case '[': case ']': case '<': case '>': - case '(': - case ')': case '#': - case '+': - case '-': - case '.': case '!': case '|': return true; diff --git a/typefactory/kindle2latex.pro b/typefactory/kindle2latex.pro deleted file mode 100644 index 595bdaa..0000000 --- a/typefactory/kindle2latex.pro +++ /dev/null @@ -1,7 +0,0 @@ -TEMPLATE = app -CONFIG += console c++17 -CONFIG -= app_bundle -CONFIG -= qt - -SOURCES += \ - main.cpp diff --git a/typefactory/kindle2notes.pro b/typefactory/kindle2notes.pro new file mode 100644 index 0000000..51323a7 --- /dev/null +++ b/typefactory/kindle2notes.pro @@ -0,0 +1,17 @@ +TEMPLATE = app +TARGET = kindle2notes +CONFIG += console c++17 +CONFIG -= app_bundle +CONFIG -= qt + +SOURCES += \ + convertlatex.cpp \ + convertmarkdown.cpp \ + converter.cpp \ + main.cpp + +HEADERS += \ + convertlatex.h \ + convertmarkdown.h \ + converter.h \ + typefactory.h diff --git a/typefactory/typefactory.pro b/typefactory/typefactory.pro index 8101ea3..51323a7 100644 --- a/typefactory/typefactory.pro +++ b/typefactory/typefactory.pro @@ -1,4 +1,5 @@ TEMPLATE = app +TARGET = kindle2notes CONFIG += console c++17 CONFIG -= app_bundle CONFIG -= qt