rolfedh-doc-utils 0.1.32__py3-none-any.whl → 0.1.34__py3-none-any.whl

callout_lib/converter_deflist.py

@@ -16,7 +16,8 @@ class DefListConverter:
     USER_VALUE_PATTERN = re.compile(r'(?<!<)<([a-zA-Z][^>]*)>')
 
     @staticmethod
-    def convert(callout_groups: List[CalloutGroup], explanations: Dict[int, Callout], table_title: str = "") -> List[str]:
+    def convert(callout_groups: List[CalloutGroup], explanations: Dict[int, Callout], table_title: str = "",
+                definition_prefix: str = "") -> List[str]:
         """
         Create definition list from callout groups and explanations.
 
@@ -31,6 +32,7 @@ class DefListConverter:
             explanations: Dict mapping callout numbers to Callout objects
             table_title: Optional table title (e.g., ".Descriptions of delete event")
                         Will be converted to lead-in sentence (e.g., "Descriptions of delete event, where:")
+            definition_prefix: Optional prefix to add before each definition (e.g., "Specifies ")
 
         Returns:
             List of strings representing the definition list
@@ -48,22 +50,29 @@ class DefListConverter:
             code_line = group.code_line
             callout_nums = group.callout_numbers
 
-            # Check if this is a user-replaceable value (contains angle brackets but not heredoc)
-            # User values are single words/phrases in angle brackets like <my-value>
-            user_values = DefListConverter.USER_VALUE_PATTERN.findall(code_line)
-
-            if user_values and len(user_values) == 1 and len(code_line) < 100:
-                # This looks like a user-replaceable value placeholder
-                # Format the value (ensure it has angle brackets)
-                user_value = user_values[0]
-                if not user_value.startswith('<'):
-                    user_value = f'<{user_value}>'
-                if not user_value.endswith('>'):
-                    user_value = f'{user_value}>'
-                term = f'`{user_value}`'
-            else:
-                # This is a code line - strip whitespace before wrapping in backticks
-                term = f'`{code_line.strip()}`'
+            # COMMENTED OUT: User-replaceable value detection causes false positives
+            # with Java generics (e.g., <MyEntity, Integer>) and other valid syntax
+            # that uses angle brackets. Always use the full code line as the term.
+            #
+            # # Check if this is a user-replaceable value (contains angle brackets but not heredoc)
+            # # User values are single words/phrases in angle brackets like <my-value>
+            # user_values = DefListConverter.USER_VALUE_PATTERN.findall(code_line)
+            #
+            # if user_values and len(user_values) == 1 and len(code_line) < 100:
+            #     # This looks like a user-replaceable value placeholder
+            #     # Format the value (ensure it has angle brackets)
+            #     user_value = user_values[0]
+            #     if not user_value.startswith('<'):
+            #         user_value = f'<{user_value}>'
+            #     if not user_value.endswith('>'):
+            #         user_value = f'{user_value}>'
+            #     term = f'`{user_value}`'
+            # else:
+            #     # This is a code line - strip whitespace before wrapping in backticks
+            #     term = f'`{code_line.strip()}`'
+
+            # Always use the full code line - strip whitespace before wrapping in backticks
+            term = f'`{code_line.strip()}`'
 
             # Add blank line before each term
             lines.append('')
@@ -101,9 +110,20 @@ class DefListConverter:
                         lines.append('+')
                         need_continuation = False
 
-                    # Add the line
-                    if line_idx == 0 and explanation.is_optional:
-                        lines.append(f'Optional. {line}')
+                    # Add the line with optional prefix
+                    if line_idx == 0:
+                        # First line of definition
+                        if explanation.is_optional:
+                            # Optional marker takes precedence, then prefix
+                            if definition_prefix:
+                                lines.append(f'Optional. {definition_prefix}{line}')
+                            else:
+                                lines.append(f'Optional. {line}')
+                        elif definition_prefix:
+                            # Add prefix to first line
+                            lines.append(f'{definition_prefix}{line}')
+                        else:
+                            lines.append(line)
                     else:
                         lines.append(line)
 

callout_lib/detector.py

@@ -46,9 +46,10 @@ class CalloutDetector:
     CALLOUT_IN_CODE = re.compile(r'<(\d+)>')
 
     # Pattern for callout with optional preceding comment syntax
-    # Matches common comment styles: //, #, --, ;, followed by optional whitespace and <number>
-    # The comment syntax must be preceded by whitespace to avoid matching code operators
-    CALLOUT_WITH_COMMENT = re.compile(r'\s*(?://|#|--|;)\s*<\d+>|\s*<\d+>')
+    # Matches common comment styles: //, #, --, followed by optional whitespace and <number>
+    # Note: Semicolon (;) removed because it's a statement terminator in Java/C/C++/JavaScript
+    # and causes false positives (e.g., "name; <1>" would incorrectly remove the semicolon)
+    CALLOUT_WITH_COMMENT = re.compile(r'\s*(?://|#|--)\s*<\d+>|\s*<\d+>')
 
     # Pattern for callout explanation line: <1> Explanation text
     CALLOUT_EXPLANATION = re.compile(r'^<(\d+)>\s+(.+)$')
@@ -141,16 +142,23 @@ class CalloutDetector:
                 # Use CALLOUT_WITH_COMMENT to remove both comment syntax and callout
                 line_without_callouts = self.CALLOUT_WITH_COMMENT.sub('', line).rstrip()
 
-                # Find all angle-bracket enclosed values
-                user_values = self.USER_VALUE_PATTERN.findall(line_without_callouts)
-
-                # Determine what to use as the code line term
-                if user_values:
-                    # Use the rightmost (closest to the callout) user value
-                    code_line = user_values[-1]
-                else:
-                    # No angle-bracket value found - use the actual code line
-                    code_line = line_without_callouts
+                # COMMENTED OUT: User-replaceable value detection causes false positives
+                # with Java generics (e.g., <MyEntity, Integer>) and other valid syntax
+                # that uses angle brackets. Always use the full code line.
+                #
+                # # Find all angle-bracket enclosed values
+                # user_values = self.USER_VALUE_PATTERN.findall(line_without_callouts)
+                #
+                # # Determine what to use as the code line term
+                # if user_values:
+                #     # Use the rightmost (closest to the callout) user value
+                #     code_line = user_values[-1]
+                # else:
+                #     # No angle-bracket value found - use the actual code line
+                #     code_line = line_without_callouts
+
+                # Always use the full code line
+                code_line = line_without_callouts
 
                 # Collect all callout numbers on this line
                 callout_nums = [int(m.group(1)) for m in callout_matches]

convert_callouts_interactive.py

@@ -127,24 +127,30 @@ class InteractiveCalloutConverter:
         print("  [d] Use Definition list format instead")
         print("  [b] Use Bulleted list format instead")
         print("  [k] Skip this block")
-        print("  [q] Quit")
+        print("  [q] Skip current file")
+        print("  [Q] Quit script entirely (Ctrl+C)")
 
         while True:
             try:
-                choice = input("\nYour choice [s/d/b/k/q]: ").strip().lower()
-
-                if choice in ['q', 'quit', 'exit']:
+                choice = input("\nYour choice [s/d/b/k/q/Q]: ").strip()
+
+                if choice in ['Q', 'QUIT', 'EXIT']:
+                    # Quit script entirely
+                    print_colored("\nQuitting script...", Colors.YELLOW)
+                    sys.exit(0)
+                elif choice.lower() in ['q', 'quit', 'exit']:
+                    # Skip current file
                     return None
-                elif choice in ['s', 'shorten', 'short']:
+                elif choice.lower() in ['s', 'shorten', 'short']:
                     return 'shorten'
-                elif choice in ['d', 'deflist']:
+                elif choice.lower() in ['d', 'deflist']:
                     return 'deflist'
-                elif choice in ['b', 'bullets', 'bullet']:
+                elif choice.lower() in ['b', 'bullets', 'bullet']:
                     return 'bullets'
-                elif choice in ['k', 'skip']:
+                elif choice.lower() in ['k', 'skip']:
                     return 'skip'
                 else:
-                    print_colored("Invalid choice. Please enter s, d, b, k, or q.", Colors.RED)
+                    print_colored("Invalid choice. Please enter s, d, b, k, q, or Q.", Colors.RED)
 
             except (KeyboardInterrupt, EOFError):
                 print()
@@ -168,23 +174,29 @@ class InteractiveCalloutConverter:
         print("  [c] Inline comments")
         print("  [s] Skip this block")
         print("  [a] Apply choice to All remaining blocks")
-        print("  [q] Quit")
+        print("  [q] Skip current file")
+        print("  [Q] Quit script entirely (Ctrl+C)")
 
         while True:
             try:
-                choice = input("\nYour choice [d/b/c/s/a/q]: ").strip().lower()
-
-                if choice in ['q', 'quit', 'exit']:
+                choice = input("\nYour choice [d/b/c/s/a/q/Q]: ").strip()
+
+                if choice in ['Q', 'QUIT', 'EXIT']:
+                    # Quit script entirely
+                    print_colored("\nQuitting script...", Colors.YELLOW)
+                    sys.exit(0)
+                elif choice.lower() in ['q', 'quit', 'exit']:
+                    # Skip current file
                     return None
-                elif choice in ['s', 'skip']:
+                elif choice.lower() in ['s', 'skip']:
                     return 'skip'
-                elif choice in ['d', 'deflist']:
+                elif choice.lower() in ['d', 'deflist']:
                     return 'deflist'
-                elif choice in ['b', 'bullets', 'bullet']:
+                elif choice.lower() in ['b', 'bullets', 'bullet']:
                     return 'bullets'
-                elif choice in ['c', 'comments', 'comment']:
+                elif choice.lower() in ['c', 'comments', 'comment']:
                     return 'comments'
-                elif choice in ['a', 'all']:
+                elif choice.lower() in ['a', 'all']:
                     # Ask for the format to apply to all
                     print("\nWhat format should be applied to all remaining blocks?")
                     print("  [d] Definition list")
@@ -257,7 +269,7 @@ class InteractiveCalloutConverter:
             choice = self.get_user_choice(idx, total_blocks)
 
             if choice is None:
-                print_colored("\nConversion cancelled by user.", Colors.YELLOW)
+                print_colored("\nSkipping remaining blocks in this file.", Colors.YELLOW)
                 return 0, False
             elif choice == 'skip':
                 print_colored("Skipping this block.\n", Colors.YELLOW)
@@ -279,7 +291,7 @@ class InteractiveCalloutConverter:
                     long_choice = self.get_user_choice_for_long_comments(block, long_warnings)
 
                     if long_choice is None:
-                        print_colored("\nConversion cancelled by user.", Colors.YELLOW)
+                        print_colored("\nSkipping remaining blocks in this file.", Colors.YELLOW)
                         return 0, False
                     elif long_choice == 'skip':
                         print_colored("Skipping this block.\n", Colors.YELLOW)
@@ -518,8 +530,8 @@ Examples:
                 total_conversions += conversions
 
         except KeyboardInterrupt:
-            print_colored("\n\nOperation cancelled by user", Colors.YELLOW)
-            break
+            print_colored("\n\nScript interrupted by user (Ctrl+C)", Colors.YELLOW)
+            sys.exit(0)
         except Exception as e:
             print_colored(f"\nUnexpected error processing {file_path}: {e}", Colors.RED)
             import traceback

convert_callouts_to_deflist.py

@@ -46,12 +46,13 @@ class CalloutConverter:
     """Converts callout-style documentation to various formats."""
 
     def __init__(self, dry_run: bool = False, verbose: bool = False, output_format: str = 'deflist',
-                 max_comment_length: int = 120, force: bool = False):
+                 max_comment_length: int = 120, force: bool = False, definition_prefix: str = ""):
         self.dry_run = dry_run
         self.verbose = verbose
         self.output_format = output_format  # 'deflist', 'bullets', or 'comments'
         self.max_comment_length = max_comment_length  # Max length for inline comments
         self.force = force  # Force strip callouts even with warnings
+        self.definition_prefix = definition_prefix  # Prefix to add before definitions (e.g., "Specifies ")
         self.changes_made = 0
         self.warnings = []  # Collect warnings for summary
         self.long_comment_warnings = []  # Warnings for comments exceeding max length
@@ -195,7 +196,7 @@ class CalloutConverter:
                     # Fall back to definition list
                     self.log(f"Falling back to definition list for block at line {block.start_line + 1}")
                     converted_content = self.detector.remove_callouts_from_code(block.content)
-                    output_list = DefListConverter.convert(callout_groups, explanations, self.detector.last_table_title)
+                    output_list = DefListConverter.convert(callout_groups, explanations, self.detector.last_table_title, self.definition_prefix)
                     use_deflist_fallback = True
                 else:
                     output_list = []  # No separate list after code block for comments
@@ -206,7 +207,7 @@ class CalloutConverter:
                 if self.output_format == 'bullets':
                     output_list = BulletListConverter.convert(callout_groups, explanations, self.detector.last_table_title)
                 else:  # default to 'deflist'
-                    output_list = DefListConverter.convert(callout_groups, explanations, self.detector.last_table_title)
+                    output_list = DefListConverter.convert(callout_groups, explanations, self.detector.last_table_title, self.definition_prefix)
 
             # Replace in document
             # Check if block has [source] prefix
@@ -474,6 +475,17 @@ Example transformation (deflist format):
         action='store_true',
         help='Force strip callouts from code blocks even with warnings (USE WITH CAUTION: only after reviewing and fixing callout issues)'
     )
+    parser.add_argument(
+        '-s', '--specifies',
+        action='store_true',
+        help='Add "Specifies " prefix before each definition (only applies to deflist format)'
+    )
+    parser.add_argument(
+        '--prefix',
+        type=str,
+        default='',
+        help='Custom prefix to add before each definition (only applies to deflist format, e.g., "Indicates ")'
+    )
 
     args = parser.parse_args()
 
@@ -526,9 +538,20 @@ Example transformation (deflist format):
             sys.exit(0)
         print()
 
+    # Determine definition prefix
+    definition_prefix = ""
+    if args.specifies:
+        definition_prefix = "Specifies "
+    elif args.prefix:
+        definition_prefix = args.prefix
+        # Add trailing space if user didn't include one
+        if definition_prefix and not definition_prefix.endswith(' '):
+            definition_prefix += ' '
+
     # Create converter
     converter = CalloutConverter(dry_run=args.dry_run, verbose=args.verbose, output_format=args.format,
-                                 max_comment_length=args.max_comment_length, force=args.force)
+                                 max_comment_length=args.max_comment_length, force=args.force,
+                                 definition_prefix=definition_prefix)
 
     # Process each file
     files_processed = 0

doc_utils/version.py

@@ -1,7 +1,7 @@
 """Version information for doc-utils."""
 
 # This should match the version in pyproject.toml
-__version__ = "0.1.32"
+__version__ = "0.1.34"
 
 def get_version():
     """Return the current version string."""

{rolfedh_doc_utils-0.1.32.dist-info → rolfedh_doc_utils-0.1.34.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rolfedh-doc-utils
-Version: 0.1.32
+Version: 0.1.34
 Summary: CLI tools for AsciiDoc documentation projects
 Author: Rolfe Dlugy-Hegwer
 License: MIT License

{rolfedh_doc_utils-0.1.32.dist-info → rolfedh_doc_utils-0.1.34.dist-info}/RECORD

@@ -1,8 +1,8 @@
 archive_unused_files.py,sha256=OJZrkqn70hiOXED218jMYPFNFWnsDpjsCYOmBRxYnHU,2274
 archive_unused_images.py,sha256=fZeyEZtTd72Gbd3YBXTy5xoshAAM9qb4qFPMjhHL1Fg,1864
 check_scannability.py,sha256=O6ROr-e624jVPvPpASpsWo0gTfuCFpA2mTSX61BjAEI,5478
-convert_callouts_interactive.py,sha256=9mmXEIbJo8G2Drj0uMWHFsF59zwJtNPgR2MNsisELLE,22160
-convert_callouts_to_deflist.py,sha256=zbQeig2d69gHJPVEiV9jPUg2IzYFPjVzj1GIUacRk7Q,24895
+convert_callouts_interactive.py,sha256=4PjiVIOWxNJiJLQuBHT3x6rE46-hgfFHSaoo5quYIs8,22889
+convert_callouts_to_deflist.py,sha256=BoqW5_GkQ-KqNzn4vmE6lsQosrPV0lkB-bfAx3dzyMw,25886
 doc_utils_cli.py,sha256=J3CE7cTDDCRGkhAknYejNWHhk5t9YFGt27WDVfR98Xk,5111
 extract_link_attributes.py,sha256=wR2SmR2la-jR6DzDbas2PoNONgRZ4dZ6aqwzkwEv8Gs,3516
 find_unused_attributes.py,sha256=77CxFdm72wj6SO81w-auMdDjnvF83jWy_qaM7DsAtBw,4263
@@ -12,8 +12,8 @@ validate_links.py,sha256=lWuK8sgfiFdfcUdSVAt_5U9JHVde_oa6peSUlBQtsac,6145
 callout_lib/__init__.py,sha256=8B82N_z4D1LaZVYgd5jZR53QAabtgPzADOyGlnvihj0,665
 callout_lib/converter_bullets.py,sha256=nfH0hz4p8qNM2F-MhtBjwH-lUYcNf2m1sdJebRlCxoo,4405
 callout_lib/converter_comments.py,sha256=do0dH8uOyNFpn5CDEzR0jYYCMIPP3oPFM8cEB-Fp22c,9767
-callout_lib/converter_deflist.py,sha256=LphSVdvCAcH1k7ysiBRQcrfaXRs48lmygSijYXVpu40,4942
-callout_lib/detector.py,sha256=oU36eaSz-damdylPuOftTwNU5ZjVf8GMJ44txcFAFOM,15474
+callout_lib/converter_deflist.py,sha256=Ocr3gutTo_Sl_MkzethZH1UO6mCDEcuExGMZF5MfZFg,6131
+callout_lib/detector.py,sha256=S0vZDa4zhTSn6Kv0hWfG56W-5srGxUc-nvpLe_gIx-A,15971
 callout_lib/table_parser.py,sha256=ZucisADE8RDAk5HtIrttaPgBi6Hf8ZUpw7KzfbcmEjc,31450
 doc_utils/__init__.py,sha256=qqZR3lohzkP63soymrEZPBGzzk6-nFzi4_tSffjmu_0,74
 doc_utils/extract_link_attributes.py,sha256=U0EvPZReJQigNfbT-icBsVT6Li64hYki5W7MQz6qqbc,22743
@@ -27,12 +27,12 @@ doc_utils/unused_adoc.py,sha256=2cbqcYr1os2EhETUU928BlPRlsZVSdI00qaMhqjSIqQ,5263
 doc_utils/unused_attributes.py,sha256=OHyAdaBD7aNo357B0SLBN5NC_jNY5TWXMwgtfJNh3X8,7621
 doc_utils/unused_images.py,sha256=nqn36Bbrmon2KlGlcaruNjJJvTQ8_9H0WU9GvCW7rW8,1456
 doc_utils/validate_links.py,sha256=iBGXnwdeLlgIT3fo3v01ApT5k0X2FtctsvkrE6E3VMk,19610
-doc_utils/version.py,sha256=0NJYwHS5xU9zjMDJzmJazrS_NbnmIeQhFMCZS7ZUNvQ,203
+doc_utils/version.py,sha256=LpXe7kXo5uNMJOga179IYdU101aWLSTOnciZkUlrK0E,203
 doc_utils/version_check.py,sha256=-31Y6AN0KGi_CUCAVOOhf6bPO3r7SQIXPxxeffLAF0w,7535
 doc_utils/warnings_report.py,sha256=20yfwqBjOprfFhQwCujbcsvjJCbHHhmH84uAujm-y-o,8877
-rolfedh_doc_utils-0.1.32.dist-info/licenses/LICENSE,sha256=vLxtwMVOJA_hEy8b77niTkdmQI9kNJskXHq0dBS36e0,1075
-rolfedh_doc_utils-0.1.32.dist-info/METADATA,sha256=PVHT2JPkbSx-8AY7xGOYqI-RHT-2I2YTmS41EZmsma8,8325
-rolfedh_doc_utils-0.1.32.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-rolfedh_doc_utils-0.1.32.dist-info/entry_points.txt,sha256=vL_LlLKOiurRzchrq8iRUQG19Xi9lSAFVZGjO-xyErk,577
-rolfedh_doc_utils-0.1.32.dist-info/top_level.txt,sha256=J4xtr3zoyCip27b3GnticFVZoyz5HHtgGqHQ-SZONCA,265
-rolfedh_doc_utils-0.1.32.dist-info/RECORD,,
+rolfedh_doc_utils-0.1.34.dist-info/licenses/LICENSE,sha256=vLxtwMVOJA_hEy8b77niTkdmQI9kNJskXHq0dBS36e0,1075
+rolfedh_doc_utils-0.1.34.dist-info/METADATA,sha256=uDcruRVK6RPRkZtBtM5DsH9FZ5q9LXEf8hEqOsg3mig,8325
+rolfedh_doc_utils-0.1.34.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+rolfedh_doc_utils-0.1.34.dist-info/entry_points.txt,sha256=vL_LlLKOiurRzchrq8iRUQG19Xi9lSAFVZGjO-xyErk,577
+rolfedh_doc_utils-0.1.34.dist-info/top_level.txt,sha256=J4xtr3zoyCip27b3GnticFVZoyz5HHtgGqHQ-SZONCA,265
+rolfedh_doc_utils-0.1.34.dist-info/RECORD,,