Fix some minor formatting issue for the input-main.md (#6983)

* Fix formatting issue for input-main and update type info

- Update the type field of parameter item field where multiple values
  are expected.
- Fixed formatting issue in input-main.md where > and < are not escaped
  correctly.

* Fix more formating issues

Fixed some LaTeX issue and unify the description of types.

* Add automatic escaping for < and >

Escaping is performed when the md file is generated.

* Minor wording updates

Author: zhubonan

docs/CONTRIBUTING.md

@@ -173,10 +173,10 @@ You **must** regenerate `docs/parameters.yaml` whenever you:
 
 ### How to Regenerate
 
-After building ABACUS, run:
+After building and installing ABACUS, run:
 
 ```bash
-./build/abacus --generate-parameters-yaml > docs/parameters.yaml
+abacus --generate-parameters-yaml > docs/parameters.yaml
 ```
 
 Then verify the YAML is valid:
@@ -191,7 +191,7 @@ You can also regenerate the markdown documentation locally:
 python3 docs/generate_input_main.py docs/parameters.yaml --output docs/advanced/input_files/input-main.md
 ```
 
-**Important:** Include the updated `docs/parameters.yaml` in your commit when submitting a PR that modifies INPUT parameters. Reviewers should verify the YAML changes match the C++ source changes.
+**Important:** Include the updated `docs/parameters.yaml` and `input-main.md` in your commit when submitting a PR that modifies INPUT parameters. Reviewers should verify the YAML changes match the C++ source changes and the `input-main.md` is updated.
 
 ### Parameter Documentation Format
 

docs/advanced/input_files/input-main.md

@@ -15,6 +15,7 @@
 """
 
 import argparse
+import html
 import re
 import sys
 from pathlib import Path
@@ -69,6 +70,31 @@
 ]
 
 
+def normalize_type(type_text: str) -> str:
+    """
+    Normalize legacy type labels for cleaner generated docs.
+    """
+    if not type_text:
+        return ''
+
+    normalized = type_text.strip()
+    aliases = {
+        "Bool": "Boolean",
+        "Int*2": "Integer*2",
+    }
+    return aliases.get(normalized, normalized)
+
+
+def escape_md_text(text: str) -> str:
+    """
+    Escape markdown-sensitive angle brackets while avoiding double escaping.
+    """
+    if text is None:
+        return ''
+    normalized = html.unescape(str(text))
+    return normalized.replace('<', '&lt;').replace('>', '&gt;')
+
+
 def format_description(desc: str) -> str:
     """
     Format description text for markdown output.
@@ -79,6 +105,10 @@ def format_description(desc: str) -> str:
     if not desc:
         return ''
 
+    # Prevent placeholder tokens like <property> from being parsed as raw HTML
+    # and breaking list/heading structure in rendered docs.
+    desc = escape_md_text(desc)
+
     lines = desc.split('\n')
     result_lines = []
 
@@ -94,6 +124,10 @@ def format_description(desc: str) -> str:
         if '[WARNING]' in line:
             line = line.replace('[WARNING]', '> Warning:')
 
+        # Normalize doubled note/warning prefixes from legacy content
+        line = re.sub(r'>\s*Note:\s*Note\s*:?\s*', '> Note: ', line)
+        line = re.sub(r'>\s*Warning:\s*Warning\s*:?\s*', '> Warning: ', line)
+
         result_lines.append(line)
 
     # Join and clean up
@@ -115,11 +149,13 @@ def generate_parameter_markdown(param: Dict[str, str]) -> str:
 
     # Type
     if param.get('type', '') != '':
-        lines.append(f"- **Type**: {param['type']}")
+        type_text = escape_md_text(normalize_type(str(param['type'])))
+        lines.append(f"- **Type**: {type_text}")
 
     # Availability (before description, as in original format)
     if param.get('availability', '') != '':
-        lines.append(f"- **Availability**: *{param['availability']}*")
+        availability_text = escape_md_text(str(param['availability']))
+        lines.append(f"- **Availability**: *{availability_text}*")
 
     # Description
     if param.get('description', '') != '':
@@ -137,11 +173,13 @@ def generate_parameter_markdown(param: Dict[str, str]) -> str:
 
     # Default
     if param.get('default_value', '') != '':
-        lines.append(f"- **Default**: {param['default_value']}")
+        default_text = escape_md_text(str(param['default_value']))
+        lines.append(f"- **Default**: {default_text}")
 
     # Unit
     if param.get('unit', '') != '':
-        lines.append(f"- **Unit**: {param['unit']}")
+        unit_text = escape_md_text(str(param['unit']))
+        lines.append(f"- **Unit**: {unit_text}")
 
     lines.append("")
     return '\n'.join(lines)
@@ -156,6 +194,10 @@ def generate_category_markdown(category: str, params: List[Dict[str, str]]) -> s
     for param in params:
         lines.append(generate_parameter_markdown(param))
 
+    # Keep legacy navigation aid used by downstream tooling/rendering.
+    lines.append("[back to top](#full-list-of-input-keywords)")
+    lines.append("")
+
     return '\n'.join(lines)
 
 

docs/generate_input_main.py

@@ -216,7 +216,7 @@ parameters:
     availability: ""
   - name: kspacing
     category: System variables
-    type: Real
+    type: Vector of Real (1 or 3 values)
     description: |
       Set the smallest allowed spacing between k points, unit in 1/bohr. It should be larger than 0.0, and suggest smaller than 0.25. When you have set this value > 0.0, then the KPT file is unnecessary. The default value 0.0 means that ABACUS will read the applied KPT file.
 
@@ -577,7 +577,7 @@ parameters:
     availability: ""
   - name: xc_exch_ext
     category: Electronic structure
-    type: Integer Real ...
+    type: Integer followed by Real values
     description: |
       Customized parameterization on the exchange part of XC functional. The first value should be the LibXC ID of the original functional, and latter values are external parameters. Default values are those of Perdew-Burke-Ernzerhof (PBE) functional. For more information on LibXC ID of functionals, please refer to LibXC. For parameters of functionals of interest, please refer to the source code of LibXC, such as PBE functional interface in LibXC: gga_x_pbe.c.
 
@@ -587,7 +587,7 @@ parameters:
     availability: ""
   - name: xc_corr_ext
     category: Electronic structure
-    type: Integer Real ...
+    type: Integer followed by Real values
     description: |
       Customized parameterization on the correlation part of XC functional. The first value should be the LibXC ID of the original functional, and latter values are external parameters. Default values are those of Perdew-Burke-Ernzerhof (PBE) functional. For more information on LibXC ID of functionals, please refer to LibXC. For parameters of functionals of interest, please refer to the source code of LibXC, such as PBE functional interface in LibXC: gga_c_pbe.c.
 
@@ -713,7 +713,7 @@ parameters:
       At n-th iteration which is calculated by drho<mixing_restart, SCF will start a mixing for real-space density matrix by using the same coefficiences as the mixing of charge density.
     default_value: "false"
     unit: ""
-    availability: "Only for mixing_restart>=0.0"
+    availability: "Only for mixing_restart >= 0.0"
   - name: mixing_gg0
     category: Electronic structure
     type: Real
@@ -1075,7 +1075,7 @@ parameters:
     availability: ""
   - name: bessel_nao_rcut
     category: NAOs
-    type: Real
+    type: Vector of Real (N values)
     description: |
       Cutoff radius (in Bohr) and the common node of spherical Bessel functions used to construct the NAOs.
     default_value: "6.0"
@@ -2316,7 +2316,7 @@ parameters:
     availability: Numerical atomic orbital basis and deepks_scf is true
   - name: deepks_band_range
     category: DeePKS
-    type: "Int*2"
+    type: "Integer*2"
     description: |
       The first value should not be larger than the second one and the meaning differs in different cases below
       * deepks_bandgap is 1: Bandgap label is the energy between LUMO + deepks_band_range[0] and LUMO + deepks_band_range[1]. If not set, it will calculate energy between HOMO and LUMO states.
@@ -2672,7 +2672,7 @@ parameters:
     availability: ""
   - name: lr_init_xc_kernel
     category: Linear Response TDDFT (Under Development Feature)
-    type: String
+    type: "Vector of String (>=1 values)"
     description: |
       The method to initalize the xc kernel.
       * "default": Calculate xc kernel from the ground-state charge density.
@@ -3477,7 +3477,7 @@ parameters:
     availability: ""
   - name: out_wannier_mmn
     category: Berry phase and wannier90 interface
-    type: Bool
+    type: Boolean
     description: |
       Write the "*.mmn" file or not.
       * 0: don't write the "*.mmn" file.
@@ -3487,7 +3487,7 @@ parameters:
     availability: ""
   - name: out_wannier_amn
     category: Berry phase and wannier90 interface
-    type: Bool
+    type: Boolean
     description: |
       Write the "*.amn" file or not.
       * 0: don't write the "*.amn" file.
@@ -3497,7 +3497,7 @@ parameters:
     availability: ""
   - name: out_wannier_eig
     category: Berry phase and wannier90 interface
-    type: Bool
+    type: Boolean
     description: |
       Write the "*.eig" file or not.
       * 0: don't write the "*.eig" file.
@@ -3507,7 +3507,7 @@ parameters:
     availability: ""
   - name: out_wannier_unk
     category: Berry phase and wannier90 interface
-    type: Bool
+    type: Boolean
     description: |
       Write the "UNK.*" file or not.
       * 0: don't write the "UNK.*" file.
@@ -3517,7 +3517,7 @@ parameters:
     availability: ""
   - name: out_wannier_wvfn_formatted
     category: Berry phase and wannier90 interface
-    type: Bool
+    type: Boolean
     description: |
       Write the "UNK.*" file in ASCII format or binary format.
       * 0: write the "UNK.*" file in binary format.
@@ -3840,25 +3840,25 @@ parameters:
     availability: ""
   - name: exx_fock_alpha
     category: Exact Exchange (Common)
-    type: "Real \\Real...\\"
+    type: Real
     description: |
-      Fraction of full-ranged Fock exchange 1/r () in range-separated hybrid funtionals, so that .
+      Fraction of full-ranged Fock exchange $1/r$ in range-separated hybrid functionals.
     default_value: see hybrid_func_params
     unit: ""
     availability: ""
   - name: exx_erfc_alpha
     category: Exact Exchange (Common)
-    type: "Real \\Real...\\"
+    type: Real
     description: |
-      Fraction of short-ranged Fock exchange erfc(wr)/r () in range-separated hybrid funtionals, so that .
+      Fraction of short-ranged Fock exchange $\mathrm{erfc}(\omega r)/r$ in range-separated hybrid functionals.
     default_value: see hybrid_func_params
     unit: ""
     availability: ""
   - name: exx_erfc_omega
     category: Exact Exchange (Common)
-    type: "Real \\Real...\\"
+    type: Real
     description: |
-      Range-separation parameter in exchange, such that
+      Range-separation parameter $\omega$ in the short-ranged Fock term $\mathrm{erfc}(\omega r)/r$.
     default_value: see hybrid_func_params
     unit: ""
     availability: ""
@@ -3890,7 +3890,7 @@ parameters:
     availability: exx_separate_loop==1
   - name: exx_fock_lambda
     category: Exact Exchange (LCAO in PW)
-    type: "Real \\Real...\\"
+    type: Real
     description: |
       It is used to compensate for divergence points at G=0 in the evaluation of Fock exchange using lcao_in_pw method.
     default_value: "0.3"
@@ -4064,7 +4064,7 @@ parameters:
     availability: basis_type==lcao
   - name: orbital_corr
     category: DFT+U correction
-    type: Integer
+    type: Vector of Integer (n values where n is the number of atomic types)
     description: |
       Specifies which orbits need plus U correction for each atom type ( for atom type 1, 2, 3, respectively).
       * -1: The plus U correction will not be calculated for this atom.
@@ -4076,7 +4076,7 @@ parameters:
     availability: ""
   - name: hubbard_u
     category: DFT+U correction
-    type: Real
+    type: Vector of Real (n values where n is the number of atomic types)
     description: |
       Specifies the Hubbard Coulomb interaction parameter U (eV) in plus U correction, which should be specified for each atom unless the Yukawa potential is used.
 
@@ -4119,16 +4119,16 @@ parameters:
       * 1: The first SCF step will use an initial density matrix read from a file named initial_onsite.dm, but for later steps, the onsite density matrix will be updated.
       * 2: The same onsite density matrix from initial_onsite.dm will be used throughout the entire calculation.
 
-      [NOTE] Note : The easiest way to create initial_onsite.dm is to run a DFT+U calculation, look for a file named onsite.dm in the OUT.prefix directory, and make replacements there. The format of the file is rather straight-forward.
+      [NOTE] The easiest way to create initial_onsite.dm is to run a DFT+U calculation, look for a file named onsite.dm in the OUT.prefix directory, and make replacements there. The format of the file is rather straight-forward.
     default_value: "0"
     unit: ""
     availability: ""
   - name: onsite_radius
     category: DFT+U correction
     type: Real
     description: |
-      * The Onsite-radius parameter facilitates modulation of the single-zeta portion of numerical atomic orbitals for projections for DFT+U.
-      * The modulation algorithm includes a smooth truncation applied directly to the tail of the original orbital, followed by normalization. Consider the function: $\sigmar_c\sigmaf'(r)\equiv \mathrm{d}f(r)/\mathrm{d}r\gamma$ is a parameter that adjusts the relative weight of the error function to the derivative error function.
+      * The onsite_radius parameter facilitates modulation of the single-zeta portion of numerical atomic orbitals used for DFT+U projections.
+      * The modulation algorithm applies a smooth truncation to the orbital tail followed by normalization. A representative profile is $f(r)=\frac{1}{2}\left[1+\operatorname{erf}\!\left(\frac{r_c-r}{\sigma}\right)\right]$, where $r_c$ is the cutoff radius and $\sigma=\gamma r_c$ controls smoothness.
     default_value: "3.0"
     unit: Bohr
     availability: dft_plus_u is set to 1
@@ -4233,15 +4233,15 @@ parameters:
     availability: ""
   - name: qo_strategy
     category: Quasiatomic Orbital (QO) analysis
-    type: String
+    type: Vector of String (1 or n values where n is the number of atomic types)
     description: |
       Strategy to generate radial orbitals for QO analysis. For hydrogen: energy-valence, for pswfc and szv: all
     default_value: "for hydrogen: energy-valence, for pswfc and szv: all"
     unit: ""
     availability: ""
   - name: qo_screening_coeff
     category: Quasiatomic Orbital (QO) analysis
-    type: Real
+    type: Vector of Real (n values where n is the number of atomic types; 1 value allowed for qo_basis=pswfc)
     description: |
       The screening coefficient for each atom type to rescale the shape of radial orbitals
     default_value: "0.1"

docs/parameters.yaml

@@ -247,7 +247,7 @@ void ReadInput::item_deepks()
         Input_Item item("deepks_band_range");
         item.annotation = "(int, int) range of bands for bandgap label";
         item.category = "DeePKS";
-        item.type = "Int*2";
+        item.type = "Integer*2";
         item.description = R"(The first value should not be larger than the second one and the meaning differs in different cases below
 * deepks_bandgap is 1: Bandgap label is the energy between LUMO + deepks_band_range[0] and LUMO + deepks_band_range[1]. If not set, it will calculate energy between HOMO and LUMO states.
 * deepks_bandgap is 2: Bandgap labels are energies between HOMO and all states in range [LUMO + deepks_band_range[0], LUMO + deepks_band_range[1]] (Thus there are deepks_band_range[1] - deepks_band_range[0] + 1 bandgaps in total). If HOMO is included in the setting range, it will be ignored since it will always be zero and has no valuable messages (deepks_band_range[1] - deepks_band_range[0] bandgaps in this case). NOTICE: The set range can be greater than, less than, or include the value of HOMO. In the bandgap label, we always calculate the energy of the state in the set range minus the energy of HOMO state, so the bandgap can be negative if the state is lower than HOMO.)";

source/source_io/module_parameter/read_input_item_deepks.cpp

@@ -350,7 +350,7 @@ The other way is only available when compiling with LIBXC, and it allows for sup
         Input_Item item("xc_exch_ext");
         item.annotation = "placeholder for xcpnet exchange functional";
         item.category = "Electronic structure";
-        item.type = "Integer Real ...";
+        item.type = "Integer followed by Real values";
         item.description = "Customized parameterization on the exchange part of XC functional. The first value should be the LibXC ID of the original functional, and latter values are external parameters. Default values are those of Perdew-Burke-Ernzerhof (PBE) functional. For more information on LibXC ID of functionals, please refer to LibXC. For parameters of functionals of interest, please refer to the source code of LibXC, such as PBE functional interface in LibXC: gga_x_pbe.c."
                           "\n\n[NOTE] Solely setting this keyword will take no effect on XC functionals. One should also set "
                           "dft_functional to the corresponding functional to apply the customized parameterization. "
@@ -393,7 +393,7 @@ The other way is only available when compiling with LIBXC, and it allows for sup
         Input_Item item("xc_corr_ext");
         item.annotation = "placeholder for xcpnet exchange functional";
         item.category = "Electronic structure";
-        item.type = "Integer Real ...";
+        item.type = "Integer followed by Real values";
         item.description = "Customized parameterization on the correlation part of XC functional. The first value should be the LibXC ID of the original functional, and latter values are external parameters. Default values are those of Perdew-Burke-Ernzerhof (PBE) functional. For more information on LibXC ID of functionals, please refer to LibXC. For parameters of functionals of interest, please refer to the source code of LibXC, such as PBE functional interface in LibXC: gga_c_pbe.c."
                           "\n\n[NOTE] Solely setting this keyword will take no effect on XC functionals. One should also set "
                           "dft_functional to the corresponding functional to apply the customized parameterization. "
@@ -675,7 +675,7 @@ For systems that are difficult to converge, one could try increasing the value o
         item.description = "At n-th iteration which is calculated by drho<mixing_restart, SCF will start a mixing for real-space density matrix by using the same coefficiences as the mixing of charge density.";
         item.default_value = "false";
         item.unit = "";
-        item.availability = "Only for mixing_restart>=0.0";
+        item.availability = "Only for mixing_restart >= 0.0";
         read_sync_bool(input.mixing_dmr);
         this->add_item(item);
     }
@@ -1350,7 +1350,7 @@ Use case: When experimental or high-level theoretical results suggest that the S
         Input_Item item("bessel_nao_rcut");
         item.annotation = "radial cutoff for spherical bessel functions(a.u.)";
         item.category = "NAOs";
-        item.type = "Real";
+        item.type = "Vector of Real (N values)";
         item.description = "Cutoff radius (in Bohr) and the common node of spherical Bessel functions used to construct the NAOs.";
         item.default_value = "6.0";
         item.unit = "";