From 3bc7ca445ada8d1415d383ffe498014b5c1c05f7 Mon Sep 17 00:00:00 2001 From: Leynos Date: Thu, 31 Jul 2025 11:33:19 +0100 Subject: [PATCH 1/5] Document footnotes option --- README.md | 23 +++++++++++++++++++---- docs/architecture.md | 3 ++- src/process.rs | 6 ++++-- 3 files changed, 25 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 4934a7c9..3d36c416 100644 --- a/README.md +++ b/README.md @@ -135,16 +135,31 @@ fn main() -> std::io::Result<()> { ..Default::default() }; let fixed = process_stream_opts(&lines, opts); - println!("{}", fixed.join("\n")); - rewrite(Path::new("table.md"))?; - Ok(()) + println!("{}", fixed.join("\n")); + rewrite(Path::new("table.md"))?; + Ok(()) } ``` +The `footnotes` option also rewrites bare numeric references: + +```rust +use mdtablefix::{process_stream_opts, Options}; + +let lines = vec![ + "A tip.1".to_string(), + "", + "1. Footnote text".to_string(), +]; +let opts = Options { footnotes: true, ..Default::default() }; +let out = process_stream_opts(&lines, opts); +assert_eq!(out[0], "A tip.[^1]"); +``` + - `process_stream_opts(lines: &[String], opts: Options) -> Vec` rewrites tables in memory. The options enable paragraph wrapping, ellipsis substitution, fence normalization and footnote conversion when `footnotes` is - set to `true`. + set to `true`. The flag is `false` by default. - `rewrite(path: &Path) -> std::io::Result<()>` modifies a Markdown file on disk in-place. diff --git a/docs/architecture.md b/docs/architecture.md index 22fc4d56..d271f33b 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -97,7 +97,8 @@ returns the updated stream for writing to disk or further manipulation. GitHub-flavoured Markdown footnotes. The `convert_footnotes` function performs this operation and is exposed via the higher-level `process_stream_opts` helper. Set `Options { footnotes: true, ..Default::default() }` when calling -`process_stream_opts` to enable the conversion logic. +`process_stream_opts` to enable the conversion logic. The parameter defaults to +`false`. Inline references that appear after punctuation are rewritten as footnote links. diff --git a/src/process.rs b/src/process.rs index 8d6ac124..eddf4fb9 100644 --- a/src/process.rs +++ b/src/process.rs @@ -41,7 +41,7 @@ pub struct Options { pub ellipsis: bool, /// Normalise code block fences. pub fences: bool, - /// Convert bare numeric references to footnotes. + /// Convert bare numeric references to footnotes (default: `false`). pub footnotes: bool, } @@ -234,7 +234,9 @@ pub fn process_stream_no_wrap(lines: &[String]) -> Vec { /// Runs [`process_stream_inner`] with custom [`Options`]. /// /// This is exposed for advanced use cases where callers want precise -/// control over the processing pipeline. +/// control over the processing pipeline. Set `footnotes: true` in `opts` +/// to convert bare numeric references into GitHub-flavoured footnote +/// links. The flag defaults to `false`. /// /// # Examples /// From b9cf82446fd9d8426edcd328fefafa0b4e29be77 Mon Sep 17 00:00:00 2001 From: Leynos Date: Thu, 31 Jul 2025 18:24:14 +0100 Subject: [PATCH 2/5] Clarify bare numeric references --- README.md | 3 ++- docs/architecture.md | 13 ++++++++++--- 2 files changed, 12 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 3d36c416..7b96c9fe 100644 --- a/README.md +++ b/README.md @@ -52,7 +52,8 @@ mdtablefix [--wrap] [--renumber] [--breaks] [--ellipsis] [--fences] [--footnotes other processing. - Use `--footnotes` to convert bare numeric references and the final numbered - list into GitHub-flavoured footnote links. + list into GitHub-flavoured footnote links. A bare numeric reference is a + trailing number after punctuation, like `An example.1`. - Use `--in-place` to modify files in-place. diff --git a/docs/architecture.md b/docs/architecture.md index d271f33b..d7d09dd5 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -94,9 +94,16 @@ returns the updated stream for writing to disk or further manipulation. ## Footnote Conversion `mdtablefix` can optionally convert bare numeric references into -GitHub-flavoured Markdown footnotes. The `convert_footnotes` function performs -this operation and is exposed via the higher-level `process_stream_opts` -helper. Set `Options { footnotes: true, ..Default::default() }` when calling +GitHub-flavoured Markdown footnotes. A bare numeric reference is a number that +appears after punctuation with no footnote formatting, for example: + +```markdown +An example of a bare numeric reference.1 +``` + +The `convert_footnotes` function performs this operation and is exposed via the +higher-level `process_stream_opts` helper. Set +`Options { footnotes: true, ..Default::default() }` when calling `process_stream_opts` to enable the conversion logic. The parameter defaults to `false`. From f56eb15e524030a691d1e8200a70994b62d74387 Mon Sep 17 00:00:00 2001 From: Leynos Date: Thu, 31 Jul 2025 19:01:19 +0100 Subject: [PATCH 3/5] Add footnote list example --- README.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/README.md b/README.md index 7b96c9fe..7ad48eca 100644 --- a/README.md +++ b/README.md @@ -157,6 +157,22 @@ let out = process_stream_opts(&lines, opts); assert_eq!(out[0], "A tip.[^1]"); ``` +It converts a trailing numbered list into footnote definitions: + +```rust +use mdtablefix::{process_stream_opts, Options}; + +let lines = vec![ + "More text.".to_string(), + "".to_string(), + "1. First note".to_string(), + "2. Second note".to_string(), +]; +let opts = Options { footnotes: true, ..Default::default() }; +let out = process_stream_opts(&lines, opts); +assert_eq!(out[2], "[^1] First note"); +``` + - `process_stream_opts(lines: &[String], opts: Options) -> Vec` rewrites tables in memory. The options enable paragraph wrapping, ellipsis substitution, fence normalization and footnote conversion when `footnotes` is From d8d4c6542df8a4105f13a1a1e819ebd28ba0513e Mon Sep 17 00:00:00 2001 From: Leynos Date: Sat, 2 Aug 2025 08:55:27 +0100 Subject: [PATCH 4/5] Fix indentation and clarify footnotes field --- README.md | 6 +++--- src/process.rs | 3 ++- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 7ad48eca..ef156040 100644 --- a/README.md +++ b/README.md @@ -136,9 +136,9 @@ fn main() -> std::io::Result<()> { ..Default::default() }; let fixed = process_stream_opts(&lines, opts); - println!("{}", fixed.join("\n")); - rewrite(Path::new("table.md"))?; - Ok(()) + println!("{}", fixed.join("\n")); + rewrite(Path::new("table.md"))?; + Ok(()) } ``` diff --git a/src/process.rs b/src/process.rs index eddf4fb9..bab6a077 100644 --- a/src/process.rs +++ b/src/process.rs @@ -41,7 +41,8 @@ pub struct Options { pub ellipsis: bool, /// Normalise code block fences. pub fences: bool, - /// Convert bare numeric references to footnotes (default: `false`). + /// Convert bare numeric references into GitHub-flavoured footnote links. + /// (default: `false`). pub footnotes: bool, } From 1a41cdbd047081efb619e48d36cafcd3f5238a96 Mon Sep 17 00:00:00 2001 From: Leynos Date: Sat, 2 Aug 2025 09:45:09 +0100 Subject: [PATCH 5/5] Wrap footnotes docs to 80 columns --- README.md | 6 ++++-- docs/architecture.md | 4 ++-- src/process.rs | 3 +-- 3 files changed, 7 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index ef156040..42a8271c 100644 --- a/README.md +++ b/README.md @@ -52,8 +52,10 @@ mdtablefix [--wrap] [--renumber] [--breaks] [--ellipsis] [--fences] [--footnotes other processing. - Use `--footnotes` to convert bare numeric references and the final numbered - list into GitHub-flavoured footnote links. A bare numeric reference is a - trailing number after punctuation, like `An example.1`. + list into GitHub-flavoured footnote links. + + A bare numeric reference is a trailing number after punctuation, like + `An example.1`. - Use `--in-place` to modify files in-place. diff --git a/docs/architecture.md b/docs/architecture.md index d7d09dd5..28a6b990 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -101,8 +101,8 @@ appears after punctuation with no footnote formatting, for example: An example of a bare numeric reference.1 ``` -The `convert_footnotes` function performs this operation and is exposed via the -higher-level `process_stream_opts` helper. Set +`convert_footnotes` performs this operation and is exposed via the higher-level +`process_stream_opts` helper. Set `Options { footnotes: true, ..Default::default() }` when calling `process_stream_opts` to enable the conversion logic. The parameter defaults to `false`. diff --git a/src/process.rs b/src/process.rs index bab6a077..d79495d5 100644 --- a/src/process.rs +++ b/src/process.rs @@ -41,8 +41,7 @@ pub struct Options { pub ellipsis: bool, /// Normalise code block fences. pub fences: bool, - /// Convert bare numeric references into GitHub-flavoured footnote links. - /// (default: `false`). + /// Convert bare numeric references into GitHub-flavoured footnote links (default: `false`). pub footnotes: bool, }