Merge pull request #34 from redhat-documentation/no-id-prefixes-21

Separate options for the module type prefix in IDs (anchors) and file names

Author: Marek Suchánek

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 The following is a summary of changes in each `newdoc` release, which is also a Git tag by the same name in this repository.
 
+## v2.11.0
+
+* Separate options for the module type prefix in IDs (anchors) and file names.
+
 ## v2.10.6
 
 * A prettier confirmation prompt when overwriting a file.

Cargo.lock

@@ -1,12 +1,12 @@
 [package]
 name = "newdoc"
-version = "2.10.6"
+version = "2.11.0"
 description = "Generate pre-populated module files formatted with AsciiDoc that are used in Red Hat and Fedora documentation."
 authors = ["Marek Suchánek <[email protected]>"]
 license = "GPL-3.0-or-later"
 edition = "2021"
 # Check the Rust version using `cargo msrv verify`.
-rust-version = "1.59"
+rust-version = "1.60"
 documentation = "https://docs.rs/newdoc"
 readme = "README.md"
 repository = "https://github.com/mrksu/newdoc"

Cargo.toml

@@ -280,7 +280,10 @@ $ newdoc --validate modules/con_proper-module.adoc
 
 * To generate the file without the example, placeholder content, add the `--no-examples` or `-E` option when creating documents.
 
-* To create the file without the module type prefix in the ID and the file name, add the `--no-prefixes` or `-P` option.
+* By default, the content type prefix appears in the generated file name and not in the ID (anchor). To change this behavior, use the following options:
++
+`--no-file-prefixes` or `-P`:: Disables the file-name prefix.
+`--anchor-prefixes` or `-A`:: Enables the ID (anchor) prefix.
 
 * To specify the directory where `newdoc` saves the generated file, add the `--target-dir=<directory>` or `-T <directory>` option.
 

docs/using-newdoc.adoc

@@ -77,9 +77,13 @@ pub struct Cli {
     #[arg(short = 'E', long = "no-examples", alias = "expert-mode")]
     pub no_examples: bool,
 
-    /// Do not use module type prefixes (such as `proc_`) in IDs and file names
-    #[arg(short = 'P', long = "no-prefixes")]
-    pub no_prefixes: bool,
+    /// Do not use module type prefixes (such as `proc_`) in file names
+    #[arg(short = 'P', long, alias = "no-prefixes")]
+    pub no_file_prefixes: bool,
+
+    /// Add use module type prefixes (such as `proc_`) in AsciiDoc anchors
+    #[arg(short = 'A', long)]
+    pub anchor_prefixes: bool,
 
     /// Save the generated files in this directory
     #[arg(short = 'T', long = "target-dir", value_name = "DIRECTORY")]

src/cmd_line.rs

@@ -57,7 +57,8 @@ const REGEX_ERROR: &str = "Failed to construct a regular expression. Please repo
 #[derive(Debug, Clone)]
 pub struct Options {
     pub comments: bool,
-    pub prefixes: bool,
+    pub file_prefixes: bool,
+    pub anchor_prefixes: bool,
     pub examples: bool,
     pub target_dir: PathBuf,
     pub verbosity: Verbosity,
@@ -83,7 +84,8 @@ impl Options {
             // on the command line. If the no-comments or no-prefixes option is passed,
             // the feature is disabled, so the option is set to false.
             comments: !cli.no_comments,
-            prefixes: !cli.no_prefixes,
+            file_prefixes: !cli.no_file_prefixes,
+            anchor_prefixes: cli.anchor_prefixes,
             examples: !cli.no_examples,
             // Set the target directory as specified or fall back on the current directory
             target_dir: cli.target_dir.clone().unwrap_or_else(|| PathBuf::from(".")),
@@ -96,7 +98,8 @@ impl Default for Options {
     fn default() -> Self {
         Self {
             comments: true,
-            prefixes: true,
+            file_prefixes: true,
+            anchor_prefixes: false,
             examples: true,
             target_dir: PathBuf::from("."),
             verbosity: Verbosity::Default,

src/lib.rs

@@ -61,7 +61,7 @@ pub struct Input {
 pub struct Module {
     mod_type: ContentType,
     title: String,
-    id: String,
+    anchor: String,
     pub file_name: String,
     pub include_statement: String,
     includes: Option<Vec<String>>,
@@ -108,7 +108,7 @@ impl Input {
     /// let options = Options::default();
     /// let input = Input::new(mod_type, title, &options);
     ///
-    /// assert_eq!("con_a-test-with-problematic-characters", input.id());
+    /// assert_eq!("a-test-with-problematic-characters", input.id());
     /// ```
     #[must_use]
     pub fn id(&self) -> String {
@@ -188,34 +188,99 @@ impl Input {
             title_with_replacements = title_with_replacements[..len - 1].to_string();
         }
 
-        let prefix = self.prefix();
-
-        format!("{}{}", prefix, title_with_replacements)
+        title_with_replacements
     }
 
     /// Prepare the file name for the generated file.
     ///
-    /// The file name is based on the module ID, with the `.adoc` extension.
+    /// The file name is based on the module ID,
+    /// with an optional prefix and the `.adoc` extension.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use newdoc::{ContentType, Input, Options};
+    ///
+    /// let mod_type = ContentType::Concept;
+    /// let title = "Default file name configuration";
+    /// let options = Options::default();
+    /// let input = Input::new(mod_type, title, &options);
+    ///
+    /// assert_eq!("con_default-file-name-configuration.adoc", input.file_name());
+    ///
+    /// let mod_type = ContentType::Concept;
+    /// let title = "No prefix file name configuration";
+    /// let options = Options {
+    ///     file_prefixes: false,
+    ///     ..Default::default()
+    /// };
+    /// let input = Input::new(mod_type, title, &options);
+    ///
+    /// assert_eq!("no-prefix-file-name-configuration.adoc", input.file_name());
+    /// ```
     #[must_use]
     pub fn file_name(&self) -> String {
+        // Add a prefix only if they're enabled.
+        let prefix = if self.options.file_prefixes {
+            self.prefix()
+        } else {
+            ""
+        };
+
+        let id = self.id();
+
         let suffix = ".adoc";
 
-        self.id() + suffix
+        [prefix, &id, suffix].join("")
     }
 
-    fn prefix(&self) -> &'static str {
-        if self.options.prefixes {
-            // If prefixes are enabled, pick the right file prefix
-            match self.mod_type {
-                ContentType::Assembly => "assembly_",
-                ContentType::Concept => "con_",
-                ContentType::Procedure => "proc_",
-                ContentType::Reference => "ref_",
-                ContentType::Snippet => "snip_",
-            }
+    /// Prepare the AsciiDoc anchor or ID.
+    ///
+    /// The anchor is based on the module ID, with an optional prefix.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use newdoc::{ContentType, Input, Options};
+    ///
+    /// let mod_type = ContentType::Concept;
+    /// let title = "Default anchor configuration";
+    /// let options = Options::default();
+    /// let input = Input::new(mod_type, title, &options);
+    ///
+    /// assert_eq!("default-anchor-configuration", input.anchor());
+    ///
+    /// let mod_type = ContentType::Concept;
+    /// let title = "Prefix anchor configuration";
+    /// let options = Options {
+    ///     anchor_prefixes: true,
+    ///     ..Default::default()
+    /// };
+    /// let input = Input::new(mod_type, title, &options);
+    ///
+    /// assert_eq!("con_prefix-anchor-configuration", input.anchor());
+    #[must_use]
+    pub fn anchor(&self) -> String {
+        // Add a prefix only if they're enabled.
+        let prefix = if self.options.anchor_prefixes {
+            self.prefix()
         } else {
-            // If prefixes are disabled, use an empty string for the prefix
             ""
+        };
+
+        let id = self.id();
+
+        [prefix, &id].join("")
+    }
+
+    /// Pick the right file and ID prefix depending on the content type.
+    fn prefix(&self) -> &'static str {
+        match self.mod_type {
+            ContentType::Assembly => "assembly_",
+            ContentType::Concept => "con_",
+            ContentType::Procedure => "proc_",
+            ContentType::Reference => "ref_",
+            ContentType::Snippet => "snip_",
         }
     }
 
@@ -285,7 +350,7 @@ impl From<Input> for Module {
         let module = Module {
             mod_type: input.mod_type,
             title: input.title.clone(),
-            id: input.id(),
+            anchor: input.anchor(),
             file_name: input.file_name(),
             include_statement: input.include_statement(),
             includes: input.includes.clone(),
@@ -294,7 +359,7 @@ impl From<Input> for Module {
 
         log::debug!("Generated module properties:");
         log::debug!("Type: {:?}", &module.mod_type);
-        log::debug!("ID: {}", &module.id);
+        log::debug!("Anchor: {}", &module.anchor);
         log::debug!("File name: {}", &module.file_name);
         log::debug!("Include statement: {}", &module.include_statement);
         log::debug!(
@@ -328,7 +393,8 @@ mod tests {
     fn basic_options() -> Options {
         Options {
             comments: false,
-            prefixes: true,
+            file_prefixes: true,
+            anchor_prefixes: false,
             examples: true,
             target_dir: PathBuf::from("."),
             verbosity: Verbosity::Default,
@@ -338,7 +404,8 @@ mod tests {
     fn path_options() -> Options {
         Options {
             comments: false,
-            prefixes: true,
+            file_prefixes: true,
+            anchor_prefixes: false,
             examples: true,
             target_dir: PathBuf::from("repo/modules/topic/"),
             verbosity: Verbosity::Default,
@@ -360,8 +427,8 @@ mod tests {
             "A testing assembly with /special-characters*"
         );
         assert_eq!(
-            assembly.id,
-            "assembly_a-testing-assembly-with-special-characters"
+            assembly.anchor,
+            "a-testing-assembly-with-special-characters"
         );
         assert_eq!(
             assembly.file_name,