From e5a023cc2aa1aec320574abd92eb9ea24846e0b5 Mon Sep 17 00:00:00 2001
From: Shulhan <ms@kilabit.info>
Date: Wed, 14 Jan 2026 16:55:40 +0700
Subject: README: rewording and update header level on commands

---
 README.md | 61 +++++++++++++++++++++++++++++++++++++------------------------
 1 file changed, 37 insertions(+), 24 deletions(-)

diff --git a/README.md b/README.md
index 1fdf810..436b8ab 100644
--- a/README.md
+++ b/README.md
@@ -54,7 +54,7 @@ copyright as stated.
 User then can repeat edit "spdxconv.cfg", "scan" and "apply" command
 multiple times, until they satisfied with the result.
 
-## init command
+### init command
 
 The first thing to do is to generate the configuration file using
 
@@ -139,7 +139,7 @@ For quick references here are several rules that you need to be aware of,
 The next subsection explain the content of configuration file and how it
 affect the program during scan and apply.
 
-### default section
+#### default section
 
 This section define the default license identifier, year, and copyright text
 to be inserted into file if no `match-license` or `match-copyright` found in
@@ -157,7 +157,7 @@ example, "2000-2026"), or list of year with comma separated (for example,
 
 The `file_copyright_text` set the default author and contact in
 `SPDX-FileCopyrightText`.
-For example, "John Doe <john.doe@example>".
+For example, "John Doe \<john.doe@example\>".
 
 You should fill the `license_identifier`, `copyright_year`, and
 `file_copyright_text` before continue running the program.
@@ -183,7 +183,10 @@ That means, if the file name match, it will create new file with ".license"
 suffix that contains SPDX identifiers only, instead of inserting to the file
 directly.
 
-### match-license section
+If the file name does not match with one of the "match-file-pattern" then
+the file will be flagged as "unknown".
+
+#### match-license section
 
 <!-- REUSE-IgnoreStart -->
 
@@ -195,7 +198,7 @@ line that match with "SPDX-License-Identifier:".
 If there is a match, at the top or bottom, the scan will stop and continue
 for processing copyright.
 
-If there is no match it will search for a line that match with "pattern"
+If no match it will search for a line that match with "pattern"
 regular expression.
 If there is a line that match with it, the value in
 "match-license::license_identifier" will replace the
@@ -206,7 +209,7 @@ search for the pattern before and after the matched line and delete it.
 The "delete_line_before" and "delete_line_after" can be defined zero or
 multiple times.
 
-### match-copyright section
+#### match-copyright section
 
 The match-copyright section define the pattern to match with old copyright
 text.
@@ -218,30 +221,30 @@ the date of the first commit in history of the file using the Source Code
 Management (SCM).
 In git SCM, it will run "git log --follow file".
 
-Example, given the following old copyright text,
+For example, given the following old copyright text,
 
 ```
-Copyright 2022, John Doe <john.doe@email>. All rights reserved.
+// Copyright 2022, John Doe <john.doe@email>. All rights reserved.
 ```
 
 we can capture the year, author, and contact using the following regex,
 
 ```
-^(//+|#+|/\\*+|<!--+)?\\s*Copyright\\s+(?<year>\\d{4}),?\\s+(?<author>.*)\\s+<(?<contact>.*)>.*$"
+^//+\\s*Copyright\\s+(?<year>\\d{4}),?\\s+(?<author>.*)\\s+<(?<contact>.*)>.*$"
 ```
 
 The `match-copyright` section can also contains zero or more
-`delete_line_before` and `delete_line_after` pattern.
+`delete_line_before` and `delete_line_after` patterns.
 The `delete_line_before` delete lines before matched line pattern, and
 `delete_line_after` contains regex to delete lines after matched line
 pattern.
 
-## scan command
+### scan command
 
 The scan command scan the files that need to be converted or inserted with
 SPDX identifiers in the current directory.
 The result of scan is stored inside a report file named "spdxconv.report".
-There are no other files modified after scan completed.
+There are no other files modified during and after scan completed.
 
 User then can inspect and modify the report to exclude certain files or
 changes the behaviour of apply command.
@@ -256,15 +259,21 @@ configuration.
 (1) Check the file for SPDX-License-Identifier and SPDX-FileCopyrightText.
 If both exist, skip the file.
 
-(2) For each match-license in the configuration,
+(2) If SPDX-License-Identifier line not exist, find the old license using
+the match-license sections.
+
+For each match-license in the configuration,
 
 (2.1) If there is a match, record it as "match" and its line number
 into the report.
 
 (2.2) If no match, use the default license from configuration, record it as
-"default" with 0 line number in the report.
+"default" with "0" as line number in the report.
+
+(3) If SPDX-FileCopyrightText line not exist, find the old copyright text
+using the match-copyright sections.
 
-(3) For each match-copyright in the configuration,
+For each match-copyright in the configuration,
 
 (3.1) If there is a match, get the year, author, and contact; and record it
 as "match" and its line number into the report.
@@ -275,9 +284,9 @@ If no commit history or its not using git, use default copyright year from
 configuration.
 
 (3.2) If there is no match, use default copyright year and text from
-configuration, and record as "default" in the report.
+configuration, and record it as "default" in the report.
 
-### spdxconv.report file format
+#### spdxconv.report file format
 
 Each line in the report file is formatted using CSV and has several columns
 separated by comma,
@@ -295,8 +304,10 @@ path              = { unicode_char }
 license_id        = "default" | "exist" | "match"
 idx_license_id    = 1 * decimal_digit
 
-year              = 4 * decimal_digit ("," year)
-                  | 4 * decimal_digit "-" 4*decimal_digit
+year              = single_year { "," single_year }
+                  | single_year "-" single_year
+
+single_year       = 4 * decimal_digit
 
 copyright_id      = "default" | "exist" | "match"
 idx_copyright_id  = 1 * decimal_digit
@@ -306,11 +317,12 @@ The `path` column define the path to the file that will be processed by
 `apply` command.
 
 The `license_id` column define the license identifier to be used.
-The value either,
+The value is either,
 
 - default - insert new identifier and using the default license_identifier
   value from configuration.
-- exist - the SPDX-License-Identifier already exist in file.
+- exist - the SPDX-License-Identifier already exist in file, at line number
+  set in `idx_license_id`
 - match - one of the pattern in match-license found in file at line number
   set in `idx_license_id`.
 
@@ -331,7 +343,8 @@ The value is either,
 
 - default - insert new identifier using the default copyright_text value from
   configuration.
-- exist - the SPDX-FileCopyrightText already exist in file.
+- exist - the SPDX-FileCopyrightText already exist in file, at line number
+  set in `idx_copyright_id`.
 - match - one of the pattern in the match-copyright found in file at line
   number set in `idx_copyright_id`.
 
@@ -343,7 +356,7 @@ found at the bottom.
 The `comment_prefix` and `comment_suffix` contains the prefix and suffix
 used as comment in the file.
 
-### spdxconv.report file groups
+#### spdxconv.report file groups
 
 Each file in the report file is collected into three groups: regular,
 binary, and unknown files.
@@ -376,7 +389,7 @@ to be used.
 This files will not be processed, it is listed here so user can inspect,
 modify the configuration, and rerun the scan command for the next cycle.
 
-## apply command
+### apply command
 
 The apply command read the "spdxconv.report" and apply the license and
 copyright in the file as stated on each line in the report.
-- 
cgit v1.3