Merge branch 'develop' into release-prep-v32.4.1

Author: AyanSinhaMahapatra

docs/source/cli-reference/basic-options.rst

@@ -623,8 +623,8 @@
         The option ``--license-text-diagnostics`` is a sub-option of and requires the options
         ``--license`` and ``--license-text``.
 
-    In the matched license text, include diagnostic highlights surrounding with square brackets []
-    words that are not matched.
+    This adds a new attribute like the matched license text, but includes diagnostic highlights
+    surrounding with square brackets ``[]`` for words that are not matched.
 
     In a normal scan, whole lines of text are included in the matched license text, including parts
     that are possibly unmatched.
@@ -645,9 +645,14 @@
         obtaining a copy of this software and associated documentation files (the \"Software\"),
         to deal in the Software without restriction
 
-    With Diagnostics on::
+    With Diagnostics on (new attribute with the matched text diagnostics)::
 
         "matched_text":
+        "License Copyright (c) 2000 - 2006 The Legion Of The Bouncy Castle
+        (http://www.bouncycastle.org) Permission is hereby granted, free of charge, to any person
+        obtaining a copy of this software and associated documentation files (the \"Software\"),
+        to deal in the Software without restriction
+        "matched_text_diagnostics":
         "License [Copyright] ([c]) [2000] - [2006] [The] [Legion] [Of] [The] [Bouncy] [Castle]
         ([http]://[www].[bouncycastle].[org]) Permission is hereby granted, free of charge, to any person
         obtaining a copy of this software and associated documentation files (the \"Software\"),

docs/source/cli-reference/scan-options-pre.rst

@@ -68,9 +68,11 @@ Pre-Scan Options
 
     - key-file
 
-        A KEY file is a generic file extension used by various programs when registering legal copies
-        of the software. It may be saved in a plain text format, but generally contains some form of
-        encrypted key string that authenticates the purchase and registers the software.
+        A KEY file serves as a keystone element, containing essential
+        information about a software package — such as its dependencies,
+        versioning, licensing, and more. It often contains the
+        ``primary-license`` or the overall license of the package, among
+        other package metadata which are general or ecosystem specific.
 
     As in, to the JSON object of each file scanned, these extra attributes are added::
 

docs/source/getting-started/install.rst

@@ -146,6 +146,7 @@ under assets options.
         sudo add-apt-repository ppa:deadsnakes/ppa --yes
         sudo apt-get install python3.9 python3.9-distutils
 
+.. _linux_mac_app_install:
 
 Installation on Linux and Mac
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -212,7 +213,7 @@ Installation on Windows 10/11
 
 .. note::
 
-  On Windows 10, double-click the new folder, select one of the files inside the folder
+  On Windows, double-click the new folder, select one of the files inside the folder
   (e.g., 'setup.py'), and right-click.
 
 - In the pop-up menu select 'Properties'.
@@ -259,6 +260,14 @@ Un-installation
   under a ScanCode-prefixed directory such as .scancode-tk or .cache/scancode-tk.
 
 
+.. note::
+
+  The above installation process can be used with **Command Prompt**
+  ``cmd``, and **PowerShell**. **Git Bash** is not tested and using it may
+  introduce unexpected behavior. If you're using **Windows Subsystem for
+  Linux** ``WSL2``, please refer to :ref:`linux_mac_app_install` section
+  above.
+
 ----
 
 .. _docker_install:

docs/source/misc/faq.rst

@@ -82,3 +82,53 @@ When scanning binaries, the line numbers are just a relative indication of where
 a detection was found: there is no such thing as lines in a binary. The numbers
 reported are based on the strings extracted from the binaries, typically broken
 as new lines with each NULL character.
+
+
+How does ``--license-text`` for ScanCode works exactly?
+-------------------------------------------------------------
+
+Is the matched text that gets included into the result exactly the lines of text
+from the input file that are covered by the ``start_line`` and ``end_line``
+fields of the result? I.e., if I would post-process the input file and extract
+``start_line`` to ``end_line`` from it, would I get exactly the ``matched_text``
+contents? Or is there some more "magic" involved when populating the
+``matched_text`` field?
+
+ScanCode is a bit smarter than just start and end line, as matching is based on
+words, not lines of the actual scanned text. And a whole line may not always be matched.
+
+For instance with this command::
+
+    $ echo "Foo is a wonder piece of code. Licensed under the GPL. " \
+        "For support contact [email protected] " > tst
+    $ scancode --license --license-text --license-text-diagnostics --yaml - tst
+    ...
+        license_detections:
+            -   license_expression: gpl-1.0-plus
+                license_expression_spdx: GPL-1.0-or-later
+                matches:
+                    -   license_expression: gpl-1.0-plus
+                        license_expression_spdx: GPL-1.0-or-later
+                        from_file: tst
+                        start_line: 1
+                        end_line: 1
+                        matcher: 2-aho
+                        score: '100.0'
+                        matched_length: 4
+                        match_coverage: '100.0'
+                        rule_relevance: 100
+                        rule_identifier: gpl_85.RULE
+                        rule_url: https://github.com/nexB/scancode-toolkit/tree/develop/src/licensedcode/data/rules/gpl_85.RULE
+                        matched_text: Foo is a wonder piece of code. Licensed under the GPL.
+                            For support contact [email protected]
+                        matched_text_diagnostics: Licensed under the GPL.
+    ...
+
+then:
+
+- ``matched_text`` is based on ``start_line`` and ``end_line``
+- ``matched_text_diagnostics`` is based on the exact matched words
+
+Note that ``matched_text_diagnostics`` also includes "tagged" gaps or extra
+unmatched words highlighted between the matched words.
+