- Internal development documentation for the Mingling codebase — design notes, issue discussions, and architectural decisions. -
- -This site is separate from the [main helpdoc](https://mingling-rs.github.io/mingling/docs/doc.html). The helpdoc is user-facing: tutorials, feature guides, and how-to content for developers _using_ Mingling to build CLI applications. This dev-docs site is for developers _working on_ Mingling itself — understanding internal mechanisms, tracking unresolved problems, and recording design rationale. - -## What's here - -- **Issues** — Collected notes on known pain points, unresolved trade-offs, and feature gaps in the current implementation. - -## How this is different from GitHub Issues - -Mingling is hosted on [GitHub](https://github.com/mingling-rs/mingling), and the [Issues page](https://github.com/mingling-rs/mingling/issues) there is primarily for discussion. In contrast, an issue in this document exists only when it is being planned or actively worked on. diff --git a/docs/dev-docs/_sidebar.md b/docs/dev-docs/_sidebar.md deleted file mode 100644 index dd735c4..0000000 --- a/docs/dev-docs/_sidebar.md +++ /dev/null @@ -1,10 +0,0 @@ -- [Welcome!](README) -* Abouts - * [AI Translation Rule](pages/abouts/ai-translation-rule) - * [Markdown Code Verification System](pages/abouts/code-verify-system) -* Issues - * [remove-r-print-macro](pages/issues/remove-r-print-macro) - * [The Mod Pathfinder](pages/issues/the-mod-pathfinder) - * [Some Situations Where You'd Be Like "Shit!"](pages/issues/the-shit-time) -* Templates - * [Helpdoc Template](pages/templates/doc) diff --git a/docs/dev-docs/index.html b/docs/dev-docs/index.html deleted file mode 100644 index e62268d..0000000 --- a/docs/dev-docs/index.html +++ /dev/null @@ -1,187 +0,0 @@ - - - - - - -- Translation prompt for your AI Agent -
- -# Translation Style Guide - -## 1. Tone & Voice - -### Preserve original tone - -Maintain the author's attitude, formality, and emotional register exactly as in the source. - -### Synonymous substitution - -Use words with close or equivalent meaning where direct translation is awkward or unnatural. - -## 2. Vocabulary & Abbreviation - -### Abbreviation - -Apply standard English abbreviations (e.g., _info_ for information, _dept_ for department) -to avoid overlong words, -but only when clarity is not sacrificed. - -### Concise expression - -Prefer shorter, more common alternatives (e.g., _use_ over _utilize_, _help_ over _facilitate_) -unless the original tone demands formality. - -## 3. Structural Rules - -### Paragraph integrity - -Keep the original paragraph breaks and line spacing. - -### Tag preservation - -Any inline Markdown formatting (bold, italic, code, links, lists) must be replicated exactly in translation. - -### Example - -- Before: “请保持专业语气，但避免使用过长的学术词汇。” -- After: “Keep a prof. tone, but avoid long academic words.” - -### Minimal diff - -When translating or syncing English content against a known Chinese original, -if the Chinese original's meaning is extremely close to the current English meaning, -do not modify the English text. -This is to keep git diffs friendly _(only modify parts that have truly changed)_. - -## 4. Exceptions - -- If a term has no common abbreviation, use the full word. -- If preserving tone requires a longer phrase, prioritize tone over brevity. - -## 5. Original Text - -```markdown -# Translation Style Guide - -## 1. Tone & Voice - -### Preserve original tone - -Maintain the author's attitude, formality, and emotional register exactly as in the source. - -### Synonymous substitution - -Use words with close or equivalent meaning where direct translation is awkward or unnatural. - -## 2. Vocabulary & Abbreviation - -### Abbreviation - -Apply standard English abbreviations (e.g., _info_ for information, _dept_ for department) -to avoid overlong words, -but only when clarity is not sacrificed. - -### Concise expression - -Prefer shorter, more common alternatives (e.g., _use_ over _utilize_, _help_ over _facilitate_) -unless the original tone demands formality. - -## 3. Structural Rules - -### Paragraph integrity - -Keep the original paragraph breaks and line spacing. - -### Tag preservation - -Any inline Markdown formatting (bold, italic, code, links, lists) must be replicated exactly in translation. - -### Example - -- Before: “请保持专业语气，但避免使用过长的学术词汇。” -- After: “Keep a prof. tone, but avoid long academic words.” - -### Minimal diff - -When translating or syncing English content against a known Chinese original, -if the Chinese original's meaning is extremely close to the current English meaning, -do not modify the English text. -This is to keep git diffs friendly _(only modify parts that have truly changed)_. - -## 4. Exceptions - -- If a term has no common abbreviation, use the full word. -- If preserving tone requires a longer phrase, prioritize tone over brevity. -``` - -- Written by @Weicao-CatilGrass -
diff --git a/docs/dev-docs/pages/abouts/code-verify-system.md b/docs/dev-docs/pages/abouts/code-verify-system.md deleted file mode 100644 index 61b66e8..0000000 --- a/docs/dev-docs/pages/abouts/code-verify-system.md +++ /dev/null @@ -1,242 +0,0 @@ -- A system that verifies every identified code block can be compiled -
- -This system automatically extracts and compiles Rust code blocks from docs, ensuring all example code stays usable in CI. - -## Config - -Specify which Markdown files to verify via [`verified-docs.toml`](https://github.com/mingling-rs/mingling/blob/main/verified-docs.toml) in the project root. - -You can also test a single file via command-line arg: - -```sh -./run-tools.sh test-all-markdown-code docs/pages/1-getting-started.md -``` - -```powershell -.\run-tools.ps1 test-all-markdown-code docs/pages/1-getting-started.md -``` - -## Default Rules - -Every verified ` ```rust ` code block gets the following injected automatically at compile time — no need to write them explicitly in the block: - -### 1. `#![allow(dead_code)]` and `#![allow(unused)]` - -Added at the top of the generated `main.rs` to suppress dead-code warnings from partial code snippets. - -### 2. `use mingling::prelude::*;` - -If the block already has `use mingling::prelude::*;`, it won't be inserted again. - -Otherwise it's inserted automatically (with `#[allow(unused_imports)]`). - -### 3. `fn main() {}` - -If the block **does not contain** a `fn main` definition, an empty `fn main() {}` is appended, - -so the block can compile as a standalone binary project. - -### 4. `mingling::macros::gen_program!();` - -If the block **does not contain** a `gen_program!()` call, - -`mingling::macros::gen_program!();` is appended automatically. - -This call is required by the mingling framework. - -### 5. Build Cache Dedup — Shared Dep Hash - -Code blocks with the same `Features` and `Dependencies` are automatically grouped into the same compile group, sharing one `Cargo.toml` and build artifacts, avoiding redundant compilations. - -> [!NOTE] -> -> Hash input (all sorted): -> -> 1. Feature list -> 2. External dep name list -> 3. External dep version list -> 4. `name=version` pairs -> -> Uses FNV-1a 64-bit hash, stable across runs. - -## Verification Steps - -After the **default rules** are applied, each block goes through: - -### 1. Block Extraction - -- Only ` ```rust ` fenced code blocks are extracted. -- Empty blocks (no code lines) are skipped. -- Blocks with `// NOT VERIFIED` alone are skipped. - -### 2. Temp Project Generation - -Each block (or each dedup-hash group) gets its own Cargo project: - -``` -.temp/doc-test/- A build-time analyzer that computes full module paths for Mingling types, resolving path ambiguity in macros. -
- -## Background - -Currently, `gen_program!` requires all involved types to be `use`d within their module. Mingling lacks a complete module path analyzer — waiting for `proc-macro-span` to stabilize is clearly not practical, so a solution for obtaining module paths is needed. - -## Solution - -We plan to create an analyzer called `mingling-mod-pathf`, enabled via Mingling's `"pathf"` feature, to compute the full paths of all defined Mingling types. - -### Behavior When Enabled - -**`mingling_core`**: If the `builds` feature is enabled, introduces the `mingling::build::analyze_and_build_type_mapping()` method (analysis completed at Build-Time) - -**`mingling_macros`**: Modifies the behavior of the `gen_program!()` macro — automatically loads the mapping table from the analysis file generated by `mingling::build::analyze_and_build_type_mapping()`, and directly uses the full `mod::path` instead of `TypeName` (injected at Compile-Time) - -## Challenges - -`mingling-mod-pathf` needs to understand **all** Mingling syntax features. -Fortunately, Mingling's type creation is almost always explicit: - -```rust -mod sub { - mingling::macros::pack!(ResultMyName = String); // directly creates ..::sub::ResultMyName -} -``` - -There are a few exceptions, such as the implicit Dispatcher provided by `extra_macros`, but these can be inferred from the node name: - -```rust -dispatcher!("remote.add"); // although the type is unknown, we can infer CMDRemoteAdd and EntryRemoteAdd -``` - -And also `#[program_setup]`: - -```rust -#[program_setup] // can infer CustomSetup from the function name `custom_setup` -fn custom_setup(program: &mut Program- This document collects the discomforts currently experienced while using Mingling. -
- -This document collects the discomforts currently experienced while using Mingling. - -Of course, you can also contribute to this document. - ---- - -## Why is there no fallback completion logic? - -(completion) (fallback) - -Currently, Mingling's Completion only supports providing completion logic for specific subcommands, with no way to provide global completion. - -For example: - -``` -mycmd- A template for writing documentation -
- -When writing a Helpdoc, you can use the following template to draft - -```markdown -- Description -
- -Content here - - - - -- Written by @Your-Name -
-``` - -- Written by @Weicao-CatilGrass -
diff --git a/docs/dev/README.md b/docs/dev/README.md new file mode 100644 index 0000000..a2eede9 --- /dev/null +++ b/docs/dev/README.md @@ -0,0 +1,15 @@ ++ Internal development documentation for the Mingling codebase — design notes, issue discussions, and architectural decisions. +
+ +This site is separate from the [main helpdoc](https://mingling-rs.github.io/mingling/docs/doc.html). The helpdoc is user-facing: tutorials, feature guides, and how-to content for developers _using_ Mingling to build CLI applications. This dev-docs site is for developers _working on_ Mingling itself — understanding internal mechanisms, tracking unresolved problems, and recording design rationale. + +## What's here + +- **Issues** — Collected notes on known pain points, unresolved trade-offs, and feature gaps in the current implementation. + +## How this is different from GitHub Issues + +Mingling is hosted on [GitHub](https://github.com/mingling-rs/mingling), and the [Issues page](https://github.com/mingling-rs/mingling/issues) there is primarily for discussion. In contrast, an issue in this document exists only when it is being planned or actively worked on. diff --git a/docs/dev/_sidebar.md b/docs/dev/_sidebar.md new file mode 100644 index 0000000..0c49615 --- /dev/null +++ b/docs/dev/_sidebar.md @@ -0,0 +1,10 @@ +- [Welcome!](README) +* Abouts + * [AI Translation Rule](pages/abouts/ai-translation-rule) + * [Markdown Code Verification System](pages/abouts/code-verify-system) +* Issues + * [Remove r_print! and r_println! Macros](pages/issues/remove-r-print-macro) + * [The Mod Pathfinder](pages/issues/the-mod-pathfinder) + * [Some Situations Where You'd Be Like "Shit!"](pages/issues/the-shit-time) +* Templates + * [Helpdoc Template](pages/templates/doc) diff --git a/docs/dev/index.html b/docs/dev/index.html new file mode 100644 index 0000000..e62268d --- /dev/null +++ b/docs/dev/index.html @@ -0,0 +1,187 @@ + + + + + + ++ Translation prompt for your AI Agent +
+ +# Translation Style Guide + +## 1. Tone & Voice + +### Preserve original tone + +Maintain the author's attitude, formality, and emotional register exactly as in the source. + +### Synonymous substitution + +Use words with close or equivalent meaning where direct translation is awkward or unnatural. + +## 2. Vocabulary & Abbreviation + +### Abbreviation + +Apply standard English abbreviations (e.g., _info_ for information, _dept_ for department) +to avoid overlong words, +but only when clarity is not sacrificed. + +### Concise expression + +Prefer shorter, more common alternatives (e.g., _use_ over _utilize_, _help_ over _facilitate_) +unless the original tone demands formality. + +## 3. Structural Rules + +### Paragraph integrity + +Keep the original paragraph breaks and line spacing. + +### Tag preservation + +Any inline Markdown formatting (bold, italic, code, links, lists) must be replicated exactly in translation. + +### Example + +- Before: “请保持专业语气，但避免使用过长的学术词汇。” +- After: “Keep a prof. tone, but avoid long academic words.” + +### Minimal diff + +When translating or syncing English content against a known Chinese original, +if the Chinese original's meaning is extremely close to the current English meaning, +do not modify the English text. +This is to keep git diffs friendly _(only modify parts that have truly changed)_. + +## 4. Exceptions + +- If a term has no common abbreviation, use the full word. +- If preserving tone requires a longer phrase, prioritize tone over brevity. + +## 5. Original Text + +```markdown +# Translation Style Guide + +## 1. Tone & Voice + +### Preserve original tone + +Maintain the author's attitude, formality, and emotional register exactly as in the source. + +### Synonymous substitution + +Use words with close or equivalent meaning where direct translation is awkward or unnatural. + +## 2. Vocabulary & Abbreviation + +### Abbreviation + +Apply standard English abbreviations (e.g., _info_ for information, _dept_ for department) +to avoid overlong words, +but only when clarity is not sacrificed. + +### Concise expression + +Prefer shorter, more common alternatives (e.g., _use_ over _utilize_, _help_ over _facilitate_) +unless the original tone demands formality. + +## 3. Structural Rules + +### Paragraph integrity + +Keep the original paragraph breaks and line spacing. + +### Tag preservation + +Any inline Markdown formatting (bold, italic, code, links, lists) must be replicated exactly in translation. + +### Example + +- Before: “请保持专业语气，但避免使用过长的学术词汇。” +- After: “Keep a prof. tone, but avoid long academic words.” + +### Minimal diff + +When translating or syncing English content against a known Chinese original, +if the Chinese original's meaning is extremely close to the current English meaning, +do not modify the English text. +This is to keep git diffs friendly _(only modify parts that have truly changed)_. + +## 4. Exceptions + +- If a term has no common abbreviation, use the full word. +- If preserving tone requires a longer phrase, prioritize tone over brevity. +``` + ++ Written by @Weicao-CatilGrass +
diff --git a/docs/dev/pages/abouts/code-verify-system.md b/docs/dev/pages/abouts/code-verify-system.md new file mode 100644 index 0000000..61b66e8 --- /dev/null +++ b/docs/dev/pages/abouts/code-verify-system.md @@ -0,0 +1,242 @@ ++ A system that verifies every identified code block can be compiled +
+ +This system automatically extracts and compiles Rust code blocks from docs, ensuring all example code stays usable in CI. + +## Config + +Specify which Markdown files to verify via [`verified-docs.toml`](https://github.com/mingling-rs/mingling/blob/main/verified-docs.toml) in the project root. + +You can also test a single file via command-line arg: + +```sh +./run-tools.sh test-all-markdown-code docs/pages/1-getting-started.md +``` + +```powershell +.\run-tools.ps1 test-all-markdown-code docs/pages/1-getting-started.md +``` + +## Default Rules + +Every verified ` ```rust ` code block gets the following injected automatically at compile time — no need to write them explicitly in the block: + +### 1. `#![allow(dead_code)]` and `#![allow(unused)]` + +Added at the top of the generated `main.rs` to suppress dead-code warnings from partial code snippets. + +### 2. `use mingling::prelude::*;` + +If the block already has `use mingling::prelude::*;`, it won't be inserted again. + +Otherwise it's inserted automatically (with `#[allow(unused_imports)]`). + +### 3. `fn main() {}` + +If the block **does not contain** a `fn main` definition, an empty `fn main() {}` is appended, + +so the block can compile as a standalone binary project. + +### 4. `mingling::macros::gen_program!();` + +If the block **does not contain** a `gen_program!()` call, + +`mingling::macros::gen_program!();` is appended automatically. + +This call is required by the mingling framework. + +### 5. Build Cache Dedup — Shared Dep Hash + +Code blocks with the same `Features` and `Dependencies` are automatically grouped into the same compile group, sharing one `Cargo.toml` and build artifacts, avoiding redundant compilations. + +> [!NOTE] +> +> Hash input (all sorted): +> +> 1. Feature list +> 2. External dep name list +> 3. External dep version list +> 4. `name=version` pairs +> +> Uses FNV-1a 64-bit hash, stable across runs. + +## Verification Steps + +After the **default rules** are applied, each block goes through: + +### 1. Block Extraction + +- Only ` ```rust ` fenced code blocks are extracted. +- Empty blocks (no code lines) are skipped. +- Blocks with `// NOT VERIFIED` alone are skipped. + +### 2. Temp Project Generation + +Each block (or each dedup-hash group) gets its own Cargo project: + +``` +.temp/doc-test/+ A build-time analyzer that computes full module paths for Mingling types, resolving path ambiguity in macros. +
+ +## Background + +Currently, `gen_program!` requires all involved types to be `use`d within their module. Mingling lacks a complete module path analyzer — waiting for `proc-macro-span` to stabilize is clearly not practical, so a solution for obtaining module paths is needed. + +## Solution + +We plan to create an analyzer called `mingling-mod-pathf`, enabled via Mingling's `"pathf"` feature, to compute the full paths of all defined Mingling types. + +### Behavior When Enabled + +**`mingling_core`**: If the `builds` feature is enabled, introduces the `mingling::build::analyze_and_build_type_mapping()` method (analysis completed at Build-Time) + +**`mingling_macros`**: Modifies the behavior of the `gen_program!()` macro — automatically loads the mapping table from the analysis file generated by `mingling::build::analyze_and_build_type_mapping()`, and directly uses the full `mod::path` instead of `TypeName` (injected at Compile-Time) + +## Challenges + +`mingling-mod-pathf` needs to understand **all** Mingling syntax features. +Fortunately, Mingling's type creation is almost always explicit: + +```rust +mod sub { + mingling::macros::pack!(ResultMyName = String); // directly creates ..::sub::ResultMyName +} +``` + +There are a few exceptions, such as the implicit Dispatcher provided by `extra_macros`, but these can be inferred from the node name: + +```rust +dispatcher!("remote.add"); // although the type is unknown, we can infer CMDRemoteAdd and EntryRemoteAdd +``` + +And also `#[program_setup]`: + +```rust +#[program_setup] // can infer CustomSetup from the function name `custom_setup` +fn custom_setup(program: &mut Program+ This document collects the discomforts currently experienced while using Mingling. +
+ +This document collects the discomforts currently experienced while using Mingling. + +Of course, you can also contribute to this document. + +--- + +## Why is there no fallback completion logic? + +(completion) (fallback) + +Currently, Mingling's Completion only supports providing completion logic for specific subcommands, with no way to provide global completion. + +For example: + +``` +mycmd+ A template for writing documentation +
+ +When writing a Helpdoc, you can use the following template to draft + +```markdown ++ Description +
+ +Content here + + + + ++ Written by @Your-Name +
+``` + ++ Written by @Weicao-CatilGrass +
-- cgit