rolfedh-doc-utils 0.1.38__tar.gz → 0.1.39__tar.gz

{rolfedh_doc_utils-0.1.38 → rolfedh_doc_utils-0.1.39}/PKG-INFO

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

rolfedh_doc_utils-0.1.39/convert_freemarker_to_asciidoc.py

@@ -0,0 +1,288 @@
+#!/usr/bin/env python3
+"""
+convert-freemarker-to-asciidoc - Convert FreeMarker-templated AsciiDoc to standard AsciiDoc.
+
+Converts Keycloak-style FreeMarker template markup in AsciiDoc files to standard
+AsciiDoc format. This tool:
+
+- Removes FreeMarker import statements (<#import ...>)
+- Converts <@tmpl.guide> blocks to AsciiDoc title and short description
+- Removes closing </@tmpl.guide> tags
+- Converts <@links.*> macros to AsciiDoc xref cross-references
+- Converts <@kc.*> command macros to code blocks
+- Handles <@profile.*> conditional blocks (community vs product)
+- Removes <@opts.*> option macros
+
+Usage:
+    convert-freemarker-to-asciidoc                    # Process current directory
+    convert-freemarker-to-asciidoc docs/guides/       # Process specific directory
+    convert-freemarker-to-asciidoc --dry-run          # Preview changes
+    convert-freemarker-to-asciidoc --structure-only   # Only convert imports and guide blocks
+
+Examples:
+    # Preview changes without modifying files
+    convert-freemarker-to-asciidoc --dry-run docs/guides/
+
+    # Convert all .adoc files in current directory
+    convert-freemarker-to-asciidoc
+
+    # Only convert structure (imports, guide blocks) - leave inline macros
+    convert-freemarker-to-asciidoc --structure-only docs/guides/server/
+
+    # Keep product content instead of community content
+    convert-freemarker-to-asciidoc --product docs/guides/
+"""
+
+import argparse
+import sys
+from pathlib import Path
+
+from doc_utils.convert_freemarker_to_asciidoc import (
+    process_file,
+    find_adoc_files,
+    has_freemarker_content,
+    ConversionStats
+)
+from doc_utils.version_check import check_version_on_startup
+from doc_utils.version import __version__
+
+
+class Colors:
+    """ANSI color codes for terminal output."""
+    RED = '\033[0;31m'
+    GREEN = '\033[0;32m'
+    YELLOW = '\033[1;33m'
+    CYAN = '\033[0;36m'
+    NC = '\033[0m'  # No Color
+
+
+def print_colored(message: str, color: str = Colors.NC) -> None:
+    """Print message with color."""
+    print(f"{color}{message}{Colors.NC}")
+
+
+def aggregate_stats(stats_list: list) -> ConversionStats:
+    """Aggregate statistics from multiple conversion results."""
+    total = ConversionStats()
+    for stats in stats_list:
+        total.imports_removed += stats.imports_removed
+        total.guide_blocks_converted += stats.guide_blocks_converted
+        total.closing_tags_removed += stats.closing_tags_removed
+        total.link_macros_converted += stats.link_macros_converted
+        total.kc_macros_converted += stats.kc_macros_converted
+        total.profile_blocks_handled += stats.profile_blocks_handled
+        total.noparse_blocks_handled += stats.noparse_blocks_handled
+        total.opts_macros_removed += stats.opts_macros_removed
+        total.features_macros_removed += stats.features_macros_removed
+        total.other_macros_removed += stats.other_macros_removed
+        total.directives_marked += stats.directives_marked
+    return total
+
+
+def format_stats_summary(stats: ConversionStats) -> str:
+    """Format statistics as a summary string."""
+    parts = []
+    if stats.imports_removed > 0:
+        parts.append(f"{stats.imports_removed} import(s)")
+    if stats.guide_blocks_converted > 0:
+        parts.append(f"{stats.guide_blocks_converted} guide block(s)")
+    if stats.link_macros_converted > 0:
+        parts.append(f"{stats.link_macros_converted} link(s) -> xref")
+    if stats.kc_macros_converted > 0:
+        parts.append(f"{stats.kc_macros_converted} command(s) -> code")
+    if stats.profile_blocks_handled > 0:
+        parts.append(f"{stats.profile_blocks_handled} profile block(s)")
+    if stats.noparse_blocks_handled > 0:
+        parts.append(f"{stats.noparse_blocks_handled} noparse block(s)")
+    if stats.opts_macros_removed > 0:
+        parts.append(f"{stats.opts_macros_removed} opts macro(s)")
+    if stats.features_macros_removed > 0:
+        parts.append(f"{stats.features_macros_removed} features macro(s)")
+    if stats.directives_marked > 0:
+        parts.append(f"{stats.directives_marked} directive(s) marked")
+    if stats.other_macros_removed > 0:
+        parts.append(f"{stats.other_macros_removed} other macro(s)")
+    return ', '.join(parts) if parts else 'no changes'
+
+
+def main():
+    """Main entry point."""
+    # Check for updates (non-blocking)
+    check_version_on_startup()
+
+    parser = argparse.ArgumentParser(
+        description="Convert FreeMarker-templated AsciiDoc to standard AsciiDoc",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Convert FreeMarker template markup to standard AsciiDoc:
+
+  STRUCTURE (always converted):
+  - Removes <#import ...> statements
+  - Converts <@tmpl.guide title="..." summary="..."> to = Title and summary
+  - Removes </@tmpl.guide> closing tags
+
+  INLINE MACROS (converted by default, skip with --structure-only):
+  - <@links.server id="hostname"/> -> xref:server/hostname.adoc[]
+  - <@kc.start parameters="--hostname x"/> -> code block with bin/kc.sh command
+  - <@profile.ifCommunity> blocks -> kept (or removed with --product)
+  - <@opts.*> macros -> removed (build-time generated)
+
+This tool is designed for converting Keycloak documentation from FreeMarker
+template format to standard AsciiDoc that can be used with other toolchains.
+
+Examples:
+  %(prog)s                                    # Process all .adoc files
+  %(prog)s docs/guides/                       # Process specific directory
+  %(prog)s docs/guides/server/hostname.adoc   # Process single file
+  %(prog)s --dry-run docs/guides/             # Preview changes
+  %(prog)s --structure-only docs/guides/      # Only convert structure
+  %(prog)s --product docs/guides/             # Keep product content
+        """
+    )
+
+    parser.add_argument(
+        'path',
+        nargs='?',
+        default='.',
+        help='File or directory to process (default: current directory)'
+    )
+    parser.add_argument(
+        '-n', '--dry-run',
+        action='store_true',
+        help='Show what would be changed without modifying files'
+    )
+    parser.add_argument(
+        '-v', '--verbose',
+        action='store_true',
+        help='Show detailed output for each file'
+    )
+    parser.add_argument(
+        '--structure-only',
+        action='store_true',
+        help='Only convert structure (imports, guide blocks); leave inline macros'
+    )
+    parser.add_argument(
+        '--product',
+        action='store_true',
+        help='Keep product content in profile blocks (default: keep community)'
+    )
+    parser.add_argument(
+        '--base-path',
+        default='',
+        help='Base path prefix for xref links (e.g., "guides")'
+    )
+    parser.add_argument(
+        '--only-freemarker',
+        action='store_true',
+        help='Only process files that contain FreeMarker markup (faster for mixed repos)'
+    )
+    parser.add_argument(
+        '--version',
+        action='version',
+        version=f'%(prog)s {__version__}'
+    )
+
+    args = parser.parse_args()
+
+    # Convert path to Path object
+    target_path = Path(args.path)
+
+    # Check if path exists
+    if not target_path.exists():
+        print_colored(f"Error: Path does not exist: {target_path}", Colors.RED)
+        sys.exit(1)
+
+    # Display mode messages
+    if args.dry_run:
+        print_colored("DRY RUN MODE - No files will be modified", Colors.YELLOW)
+        print()
+
+    if args.structure_only:
+        print("Converting structure only (imports, guide blocks)")
+        print()
+
+    # Find all AsciiDoc files
+    adoc_files = find_adoc_files(target_path)
+
+    if not adoc_files:
+        if target_path.is_file():
+            print_colored(
+                f"Warning: {target_path} is not an AsciiDoc file (.adoc)",
+                Colors.YELLOW
+            )
+        print("No AsciiDoc files found.")
+        return
+
+    # Filter to only files with FreeMarker content if requested
+    if args.only_freemarker:
+        adoc_files = [f for f in adoc_files if has_freemarker_content(f)]
+        if not adoc_files:
+            print("No files with FreeMarker markup found.")
+            return
+        if args.verbose:
+            print(f"Found {len(adoc_files)} file(s) with FreeMarker markup")
+            print()
+
+    # Process each file
+    files_processed = 0
+    files_modified = 0
+    all_stats = []
+
+    for file_path in adoc_files:
+        try:
+            result = process_file(
+                file_path,
+                dry_run=args.dry_run,
+                verbose=args.verbose,
+                convert_all=not args.structure_only,
+                keep_community=not args.product,
+                base_path=args.base_path
+            )
+
+            # Print verbose messages
+            if args.verbose:
+                for msg in result.messages:
+                    print(msg)
+
+            if result.changes_made:
+                files_modified += 1
+                all_stats.append(result.stats)
+
+                if args.dry_run:
+                    print_colored(f"Would modify: {file_path}", Colors.YELLOW)
+                else:
+                    print_colored(f"Modified: {file_path}", Colors.GREEN)
+
+            files_processed += 1
+
+        except KeyboardInterrupt:
+            print_colored("\nOperation cancelled by user", Colors.YELLOW)
+            sys.exit(1)
+        except IOError as e:
+            print_colored(f"{e}", Colors.RED)
+        except Exception as e:
+            print_colored(f"Unexpected error processing {file_path}: {e}", Colors.RED)
+
+    # Print summary
+    print()
+    print(f"Processed {files_processed} AsciiDoc file(s)")
+
+    if files_modified > 0:
+        if args.dry_run:
+            print(f"Would modify {files_modified} file(s)")
+        else:
+            print(f"Modified {files_modified} file(s)")
+
+        # Detailed stats
+        total_stats = aggregate_stats(all_stats)
+        summary = format_stats_summary(total_stats)
+        print(f"  ({summary})")
+    else:
+        print("No files needed conversion.")
+
+    print()
+    print_colored("FreeMarker to AsciiDoc conversion complete!", Colors.CYAN)
+
+
+if __name__ == "__main__":
+    main()

rolfedh_doc_utils-0.1.39/doc_utils/convert_freemarker_to_asciidoc.py

@@ -0,0 +1,708 @@
+"""
+Convert FreeMarker-templated AsciiDoc to standard AsciiDoc.
+
+Core logic for converting Keycloak-style FreeMarker template markup in AsciiDoc
+files to standard AsciiDoc format. This module handles:
+
+- Removing FreeMarker import statements (<#import ...>)
+- Converting <@tmpl.guide> and <@template.guide> blocks to AsciiDoc title/summary
+- Removing closing </@tmpl.guide> and </@template.guide> tags
+- Converting <@links.*> macros to AsciiDoc xref cross-references
+- Converting <@kc.*> command macros to code blocks
+- Removing or preserving <@profile.*> conditional blocks
+- Removing <@opts.*> option macros (build-time generated content)
+- Removing <@features.table> macros (build-time generated content)
+- Handling <#noparse> blocks (preserving content, removing tags)
+
+PATTERNS THAT CANNOT BE RELIABLY CONVERTED (require manual review):
+- <#list> loops: Dynamic content generation, no static equivalent
+- <#if>/<#else> conditionals: Logic-based content, context-dependent
+- <#assign> variables: Build-time variable assignment
+- <@features.table ctx.*/>: Dynamic feature tables generated at build time
+- Index files with <#list ctx.guides>: Auto-generated navigation
+"""
+
+import re
+from pathlib import Path
+from typing import List, Tuple, Optional, Dict
+from dataclasses import dataclass, field
+
+
+# Mapping of link types to their base paths
+# These are the guide categories used in Keycloak docs
+LINK_TYPE_PATHS: Dict[str, str] = {
+    'server': 'server',
+    'ha': 'high-availability',
+    'gettingstarted': 'getting-started',
+    'operator': 'operator',
+    'migration': 'migration',
+    'securing': 'securing-apps',
+    'securingapps': 'securing-apps',  # Alternative spelling used in some files
+    'observability': 'observability',
+}
+
+# Mapping of kc command types to their shell commands
+KC_COMMAND_MAP: Dict[str, str] = {
+    'start': 'bin/kc.sh start',
+    'startdev': 'bin/kc.sh start-dev',
+    'build': 'bin/kc.sh build',
+    'export': 'bin/kc.sh export',
+    'import': 'bin/kc.sh import',
+    'admin': 'bin/kcadm.sh',
+    'bootstrapadmin': 'bin/kc.sh bootstrap-admin',
+    'updatecompatibility': 'bin/kc.sh update-compatibility',
+}
+
+
+@dataclass
+class ConversionStats:
+    """Statistics for a conversion operation."""
+    imports_removed: int = 0
+    guide_blocks_converted: int = 0
+    closing_tags_removed: int = 0
+    link_macros_converted: int = 0
+    kc_macros_converted: int = 0
+    profile_blocks_handled: int = 0
+    noparse_blocks_handled: int = 0
+    opts_macros_removed: int = 0
+    features_macros_removed: int = 0
+    other_macros_removed: int = 0
+    directives_marked: int = 0
+
+
+@dataclass
+class ConversionResult:
+    """Result of converting a single file."""
+    file_path: Path
+    changes_made: bool
+    stats: ConversionStats = field(default_factory=ConversionStats)
+    messages: List[str] = field(default_factory=list)
+
+
+def extract_guide_attributes(content: str) -> Optional[Tuple[str, str, int, int]]:
+    """
+    Extract title and summary from a <@tmpl.guide> or <@template.guide> block.
+
+    Args:
+        content: The file content to parse
+
+    Returns:
+        Tuple of (title, summary, start_index, end_index) or None if not found
+    """
+    # Match both <@tmpl.guide> and <@template.guide> variants
+    pattern = r'<@(?:tmpl|template)\.guide\s*\n?((?:[^>]|\n)*?)>'
+
+    match = re.search(pattern, content)
+    if not match:
+        return None
+
+    block_content = match.group(1)
+    start_idx = match.start()
+    end_idx = match.end()
+
+    # Extract title attribute
+    title_match = re.search(r'title\s*=\s*"([^"]*)"', block_content)
+    title = title_match.group(1) if title_match else ""
+
+    # Extract summary attribute
+    summary_match = re.search(r'summary\s*=\s*"([^"]*)"', block_content)
+    summary = summary_match.group(1) if summary_match else ""
+
+    return (title, summary, start_idx, end_idx)
+
+
+def remove_freemarker_imports(content: str) -> Tuple[str, int]:
+    """
+    Remove FreeMarker import statements from content.
+
+    Args:
+        content: The file content
+
+    Returns:
+        Tuple of (modified content, count of imports removed)
+    """
+    # Match lines that are FreeMarker imports: <#import "..." as ...>
+    import_pattern = r'^<#import\s+"[^"]+"\s+as\s+\w+>\s*\n?'
+
+    count = len(re.findall(import_pattern, content, re.MULTILINE))
+    new_content = re.sub(import_pattern, '', content, flags=re.MULTILINE)
+
+    return (new_content, count)
+
+
+def convert_guide_block(content: str) -> Tuple[str, bool]:
+    """
+    Convert <@tmpl.guide> or <@template.guide> block to standard AsciiDoc title and summary.
+
+    Args:
+        content: The file content
+
+    Returns:
+        Tuple of (modified content, whether conversion was made)
+    """
+    result = extract_guide_attributes(content)
+    if not result:
+        return (content, False)
+
+    title, summary, start_idx, end_idx = result
+
+    # Build the AsciiDoc replacement
+    replacement_parts = []
+
+    if title:
+        replacement_parts.append(f"= {title}")
+        replacement_parts.append("")  # Blank line after title
+
+    if summary:
+        replacement_parts.append(summary)
+        replacement_parts.append("")  # Blank line after summary
+
+    replacement = "\n".join(replacement_parts)
+
+    # Replace the guide block with the AsciiDoc equivalent
+    new_content = content[:start_idx] + replacement + content[end_idx:]
+
+    # Clean up any excessive blank lines at the start
+    new_content = re.sub(r'^\n+', '', new_content)
+
+    return (new_content, True)
+
+
+def remove_closing_guide_tag(content: str) -> Tuple[str, bool]:
+    """
+    Remove the closing </@tmpl.guide> or </@template.guide> tag.
+
+    Args:
+        content: The file content
+
+    Returns:
+        Tuple of (modified content, whether tag was removed)
+    """
+    # Match both variants
+    pattern = r'\n*</@(?:tmpl|template)\.guide>\s*\n*'
+    if re.search(pattern, content):
+        new_content = re.sub(pattern, '\n', content)
+        return (new_content, True)
+    return (content, False)
+
+
+def convert_link_macros(content: str, base_path: str = '') -> Tuple[str, int]:
+    """
+    Convert <@links.*> macros to AsciiDoc xref cross-references.
+
+    Converts patterns like:
+    - <@links.server id="hostname"/> -> xref:server/hostname.adoc[]
+    - <@links.ha id="intro" anchor="section"/> -> xref:high-availability/intro.adoc#section[]
+    - <@links.securingapps id="client-registration"/> -> xref:securing-apps/client-registration.adoc[]
+
+    Args:
+        content: The file content
+        base_path: Optional base path prefix for xref links
+
+    Returns:
+        Tuple of (modified content, count of macros converted)
+    """
+    count = 0
+
+    def replace_link(match):
+        nonlocal count
+        count += 1
+
+        link_type = match.group(1)  # e.g., 'server', 'ha', 'gettingstarted', 'securingapps'
+        link_id = match.group(2)    # e.g., 'hostname', 'introduction'
+        anchor = match.group(4) if match.group(4) else ''  # Optional anchor
+
+        # Map link type to directory path
+        dir_path = LINK_TYPE_PATHS.get(link_type, link_type)
+
+        # Build the file path
+        file_path = f"{link_id}.adoc"
+
+        # Build the xref
+        if base_path:
+            xref_path = f"{base_path}/{dir_path}/{file_path}"
+        else:
+            xref_path = f"{dir_path}/{file_path}"
+
+        if anchor:
+            xref_path += f"#{anchor}"
+
+        # Return xref with empty link text (will use document title)
+        return f"xref:{xref_path}[]"
+
+    # Pattern to match link macros:
+    # <@links.TYPE id="ID"/> or <@links.TYPE id="ID" anchor="ANCHOR"/>
+    # Also handles extra whitespace variations
+    link_pattern = r'<@links\.(\w+)\s+id="([^"]+)"(\s+anchor="([^"]+)")?\s*/>'
+
+    new_content = re.sub(link_pattern, replace_link, content)
+
+    return (new_content, count)
+
+
+def convert_kc_macros(content: str) -> Tuple[str, int]:
+    """
+    Convert <@kc.*> command macros to AsciiDoc code blocks.
+
+    Converts patterns like:
+    - <@kc.start parameters="--hostname x"/> -> [source,bash]\n----\nbin/kc.sh start --hostname x\n----
+    - <@kc.build parameters="--db postgres"/> -> [source,bash]\n----\nbin/kc.sh build --db postgres\n----
+    - <@kc.export parameters="--dir <dir>"/> -> [source,bash]\n----\nbin/kc.sh export --dir <dir>\n----
+    - <@kc.import parameters="--file <file>"/> -> [source,bash]\n----\nbin/kc.sh import --file <file>\n----
+
+    Args:
+        content: The file content
+
+    Returns:
+        Tuple of (modified content, count of macros converted)
+    """
+    count = 0
+
+    def replace_kc_macro(match):
+        nonlocal count
+        count += 1
+
+        command = match.group(1)      # e.g., 'start', 'build', 'admin', 'export', 'import'
+        parameters = match.group(2)   # e.g., '--hostname my.keycloak.org'
+
+        # Get the base command from the map, or use generic kc.sh
+        if command in KC_COMMAND_MAP:
+            base_cmd = KC_COMMAND_MAP[command]
+        else:
+            # Generic kc command
+            base_cmd = f"bin/kc.sh {command}"
+
+        # Build the full command line
+        if parameters:
+            cmd_line = f"{base_cmd} {parameters}".strip()
+        else:
+            cmd_line = base_cmd
+
+        # Return as a code block
+        return f"[source,bash]\n----\n{cmd_line}\n----"
+
+    # Pattern to match kc macros: <@kc.COMMAND parameters="PARAMS"/>
+    kc_pattern = r'<@kc\.(\w+)\s+parameters="([^"]*)"\s*/>'
+
+    new_content = re.sub(kc_pattern, replace_kc_macro, content)
+
+    return (new_content, count)
+
+
+def handle_profile_blocks(content: str, keep_community: bool = True) -> Tuple[str, int]:
+    """
+    Handle <@profile.*> conditional blocks.
+
+    These blocks wrap content that should only appear in specific editions
+    (community vs product). By default, we keep community content and remove
+    product-specific content.
+
+    Args:
+        content: The file content
+        keep_community: If True, keep community content; if False, keep product content
+
+    Returns:
+        Tuple of (modified content, count of blocks handled)
+    """
+    count = 0
+
+    # First, handle ifCommunity blocks
+    community_pattern = r'<@profile\.ifCommunity>\s*\n?(.*?)</@profile\.ifCommunity>\s*\n?'
+
+    def handle_community(match):
+        nonlocal count
+        count += 1
+        if keep_community:
+            # Keep the content, remove the tags
+            return match.group(1)
+        else:
+            # Remove the entire block
+            return ''
+
+    content = re.sub(community_pattern, handle_community, content, flags=re.DOTALL)
+
+    # Handle ifProduct blocks
+    product_pattern = r'<@profile\.ifProduct>\s*\n?(.*?)</@profile\.ifProduct>\s*\n?'
+
+    def handle_product(match):
+        nonlocal count
+        count += 1
+        if not keep_community:
+            # Keep the content, remove the tags
+            return match.group(1)
+        else:
+            # Remove the entire block
+            return ''
+
+    content = re.sub(product_pattern, handle_product, content, flags=re.DOTALL)
+
+    return (content, count)
+
+
+def handle_noparse_blocks(content: str) -> Tuple[str, int]:
+    """
+    Handle <#noparse> blocks by removing the tags but keeping the content.
+
+    These blocks are used to escape FreeMarker syntax in code examples.
+    The content inside should be preserved as-is.
+
+    Args:
+        content: The file content
+
+    Returns:
+        Tuple of (modified content, count of blocks handled)
+    """
+    count = 0
+
+    # Pattern for noparse blocks: <#noparse>...</#noparse>
+    noparse_pattern = r'<#noparse>\s*\n?(.*?)</#noparse>\s*\n?'
+
+    def handle_noparse(match):
+        nonlocal count
+        count += 1
+        # Keep the content, remove the tags
+        return match.group(1)
+
+    content = re.sub(noparse_pattern, handle_noparse, content, flags=re.DOTALL)
+
+    return (content, count)
+
+
+def remove_opts_macros(content: str) -> Tuple[str, int]:
+    """
+    Remove <@opts.*> option macros.
+
+    These macros generate option documentation at build time and have no
+    meaningful conversion to static AsciiDoc. They are replaced with a
+    placeholder comment.
+
+    Args:
+        content: The file content
+
+    Returns:
+        Tuple of (modified content, count of macros removed)
+    """
+    count = 0
+
+    # Pattern for self-closing opts macros: <@opts.expectedValues option="..."/>
+    self_closing_pattern = r'<@opts\.\w+[^/>]*\/>'
+
+    def replace_self_closing(match):
+        nonlocal count
+        count += 1
+        return '// Configuration options are documented in the all-config guide'
+
+    content = re.sub(self_closing_pattern, replace_self_closing, content)
+
+    # Pattern for block opts macros: <@opts.list ...>...</@opts.list>
+    block_pattern = r'<@opts\.\w+[^>]*>.*?</@opts\.\w+>'
+
+    def replace_block(match):
+        nonlocal count
+        count += 1
+        return '// Configuration options are documented in the all-config guide'
+
+    content = re.sub(block_pattern, replace_block, content, flags=re.DOTALL)
+
+    return (content, count)
+
+
+def remove_features_macros(content: str) -> Tuple[str, int]:
+    """
+    Remove <@features.table> macros.
+
+    These macros generate feature tables at build time and cannot be
+    converted to static content.
+
+    Args:
+        content: The file content
+
+    Returns:
+        Tuple of (modified content, count of macros removed)
+    """
+    count = 0
+
+    # Pattern for features.table macros: <@features.table ctx.features.supported/>
+    features_pattern = r'<@features\.table[^/>]*\/>'
+
+    def replace_features(match):
+        nonlocal count
+        count += 1
+        return '// Feature table is generated at build time - see the features guide'
+
+    content = re.sub(features_pattern, replace_features, content)
+
+    return (content, count)
+
+
+def mark_unconvertible_directives(content: str) -> Tuple[str, int]:
+    """
+    Mark FreeMarker directives that cannot be reliably converted.
+
+    These include:
+    - <#list> loops
+    - <#if>/<#else> conditionals
+    - <#assign> variables
+
+    Args:
+        content: The file content
+
+    Returns:
+        Tuple of (modified content, count of directives marked)
+    """
+    count = 0
+
+    # Pattern for list blocks: <#list ...>...</#list>
+    list_pattern = r'(<#list\s+[^>]+>)(.*?)(</#list>)'
+
+    def mark_list(match):
+        nonlocal count
+        count += 1
+        opening = match.group(1)
+        inner = match.group(2)
+        closing = match.group(3)
+        return f"// TODO: Manual conversion required - FreeMarker list loop\n// {opening}\n{inner}// {closing}"
+
+    content = re.sub(list_pattern, mark_list, content, flags=re.DOTALL)
+
+    # Pattern for if/else blocks: <#if ...>...</#if>
+    if_pattern = r'(<#if\s+[^>]+>)(.*?)(</#if>)'
+
+    def mark_if(match):
+        nonlocal count
+        count += 1
+        opening = match.group(1)
+        inner = match.group(2)
+        closing = match.group(3)
+        return f"// TODO: Manual conversion required - FreeMarker conditional\n// {opening}\n{inner}// {closing}"
+
+    content = re.sub(if_pattern, mark_if, content, flags=re.DOTALL)
+
+    # Pattern for standalone else: <#else>
+    else_pattern = r'<#else>'
+
+    def mark_else(match):
+        nonlocal count
+        count += 1
+        return '// <#else>'
+
+    content = re.sub(else_pattern, mark_else, content)
+
+    # Pattern for assign: <#assign ...>
+    assign_pattern = r'<#assign\s+[^>]+>'
+
+    def mark_assign(match):
+        nonlocal count
+        count += 1
+        return f"// TODO: Manual conversion required - {match.group(0)}"
+
+    content = re.sub(assign_pattern, mark_assign, content)
+
+    return (content, count)
+
+
+def remove_remaining_macros(content: str) -> Tuple[str, int]:
+    """
+    Remove any remaining FreeMarker macros that weren't handled by specific converters.
+
+    Args:
+        content: The file content
+
+    Returns:
+        Tuple of (modified content, count of macros removed)
+    """
+    count = 0
+
+    # Self-closing macros: <@something .../>
+    self_closing = r'<@\w+\.[^/>]+/>'
+    self_closing_count = len(re.findall(self_closing, content))
+    if self_closing_count > 0:
+        content = re.sub(self_closing, '// TODO: Unconverted FreeMarker macro', content)
+        count += self_closing_count
+
+    # Block macros: <@something>...</@something>
+    block_pattern = r'<@\w+[^>]*>.*?</@\w+[^>]*>'
+    block_count = len(re.findall(block_pattern, content, re.DOTALL))
+    if block_count > 0:
+        content = re.sub(block_pattern, '// TODO: Unconverted FreeMarker macro', content, flags=re.DOTALL)
+        count += block_count
+
+    return (content, count)
+
+
+def process_file(
+    file_path: Path,
+    dry_run: bool = False,
+    verbose: bool = False,
+    convert_all: bool = True,
+    keep_community: bool = True,
+    base_path: str = ''
+) -> ConversionResult:
+    """
+    Process a single AsciiDoc file to convert FreeMarker markup.
+
+    Args:
+        file_path: Path to the file to process
+        dry_run: If True, show what would be changed without modifying
+        verbose: If True, show detailed output
+        convert_all: If True, convert all FreeMarker macros (not just structure)
+        keep_community: If True, keep community content in profile blocks
+        base_path: Optional base path prefix for xref links
+
+    Returns:
+        ConversionResult with details of changes made
+    """
+    messages = []
+    stats = ConversionStats()
+
+    if verbose:
+        messages.append(f"Processing: {file_path}")
+
+    try:
+        with open(file_path, 'r', encoding='utf-8') as f:
+            original_content = f.read()
+    except (IOError, UnicodeDecodeError) as e:
+        raise IOError(f"Error reading {file_path}: {e}")
+
+    content = original_content
+
+    # Step 1: Remove FreeMarker imports
+    content, count = remove_freemarker_imports(content)
+    stats.imports_removed = count
+    if count > 0 and verbose:
+        messages.append(f"  Removed {count} FreeMarker import(s)")
+
+    # Step 2: Convert guide block (both tmpl.guide and template.guide)
+    content, converted = convert_guide_block(content)
+    if converted:
+        stats.guide_blocks_converted = 1
+        if verbose:
+            messages.append("  Converted guide block to AsciiDoc title/summary")
+
+    # Step 3: Remove closing tag
+    content, removed = remove_closing_guide_tag(content)
+    if removed:
+        stats.closing_tags_removed = 1
+        if verbose:
+            messages.append("  Removed closing guide tag")
+
+    # Step 4: Convert inline macros if requested
+    if convert_all:
+        # Handle noparse blocks first (preserve content)
+        content, count = handle_noparse_blocks(content)
+        stats.noparse_blocks_handled = count
+        if count > 0 and verbose:
+            messages.append(f"  Processed {count} <#noparse> block(s)")
+
+        # Convert link macros to xrefs
+        content, count = convert_link_macros(content, base_path)
+        stats.link_macros_converted = count
+        if count > 0 and verbose:
+            messages.append(f"  Converted {count} <@links.*> macro(s) to xref")
+
+        # Convert kc command macros to code blocks
+        content, count = convert_kc_macros(content)
+        stats.kc_macros_converted = count
+        if count > 0 and verbose:
+            messages.append(f"  Converted {count} <@kc.*> macro(s) to code blocks")
+
+        # Handle profile conditional blocks
+        content, count = handle_profile_blocks(content, keep_community)
+        stats.profile_blocks_handled = count
+        if count > 0 and verbose:
+            messages.append(f"  Processed {count} <@profile.*> block(s)")
+
+        # Remove opts macros
+        content, count = remove_opts_macros(content)
+        stats.opts_macros_removed = count
+        if count > 0 and verbose:
+            messages.append(f"  Removed {count} <@opts.*> macro(s)")
+
+        # Remove features macros
+        content, count = remove_features_macros(content)
+        stats.features_macros_removed = count
+        if count > 0 and verbose:
+            messages.append(f"  Removed {count} <@features.*> macro(s)")
+
+        # Mark unconvertible directives
+        content, count = mark_unconvertible_directives(content)
+        stats.directives_marked = count
+        if count > 0 and verbose:
+            messages.append(f"  Marked {count} FreeMarker directive(s) for manual review")
+
+        # Remove any remaining macros
+        content, count = remove_remaining_macros(content)
+        stats.other_macros_removed = count
+        if count > 0 and verbose:
+            messages.append(f"  Marked {count} other macro(s) for review")
+
+    # Determine if changes were made
+    changes_made = content != original_content
+
+    # Write changes if not dry run
+    if changes_made and not dry_run:
+        try:
+            with open(file_path, 'w', encoding='utf-8') as f:
+                f.write(content)
+        except IOError as e:
+            raise IOError(f"Error writing {file_path}: {e}")
+
+    if not changes_made and verbose:
+        messages.append("  No FreeMarker markup found")
+
+    return ConversionResult(
+        file_path=file_path,
+        changes_made=changes_made,
+        stats=stats,
+        messages=messages
+    )
+
+
+def find_adoc_files(path: Path) -> List[Path]:
+    """
+    Find all .adoc files in the given path.
+
+    Args:
+        path: File or directory to search
+
+    Returns:
+        List of Path objects for .adoc files
+    """
+    adoc_files = []
+
+    if path.is_file():
+        if path.suffix == '.adoc':
+            adoc_files.append(path)
+    elif path.is_dir():
+        # Use os.walk to avoid following symlinks
+        import os
+        for root, dirs, files in os.walk(path, followlinks=False):
+            # Skip hidden directories
+            dirs[:] = [d for d in dirs if not d.startswith('.')]
+            for file in files:
+                if file.endswith('.adoc'):
+                    adoc_files.append(Path(root) / file)
+
+    return sorted(adoc_files)
+
+
+def has_freemarker_content(file_path: Path) -> bool:
+    """
+    Check if a file contains FreeMarker markup.
+
+    Args:
+        file_path: Path to the file to check
+
+    Returns:
+        True if file contains FreeMarker markup
+    """
+    try:
+        with open(file_path, 'r', encoding='utf-8') as f:
+            content = f.read()
+            return bool(
+                re.search(r'<#import', content) or
+                re.search(r'<#\w+', content) or  # Any FreeMarker directive
+                re.search(r'<@\w+\.', content)   # Any FreeMarker macro
+            )
+    except (IOError, UnicodeDecodeError):
+        return False

{rolfedh_doc_utils-0.1.38 → rolfedh_doc_utils-0.1.39}/doc_utils/version.py

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

{rolfedh_doc_utils-0.1.38 → rolfedh_doc_utils-0.1.39}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "rolfedh-doc-utils"
-version = "0.1.38"
+version = "0.1.39"
 description = "CLI tools for AsciiDoc documentation projects"
 readme = "README.md"
 requires-python = ">=3.8"
@@ -29,10 +29,11 @@ convert-callouts-interactive = "convert_callouts_interactive:main"
 check-source-directives = "check_source_directives:main"
 convert-tables-to-deflists = "convert_tables_to_deflists:main"
 check-published-links = "check_published_links:main"
+convert-freemarker-to-asciidoc = "convert_freemarker_to_asciidoc:main"
 
 [tool.setuptools.packages.find]
 where = ["."]
 include = ["doc_utils*", "callout_lib*"]
 
 [tool.setuptools]
-py-modules = ["doc_utils_cli", "find_unused_attributes", "check_scannability", "archive_unused_files", "archive_unused_images", "format_asciidoc_spacing", "replace_link_attributes", "extract_link_attributes", "validate_links", "convert_callouts_to_deflist", "convert_callouts_interactive", "check_source_directives", "convert_tables_to_deflists", "check_published_links"]
+py-modules = ["doc_utils_cli", "find_unused_attributes", "check_scannability", "archive_unused_files", "archive_unused_images", "format_asciidoc_spacing", "replace_link_attributes", "extract_link_attributes", "validate_links", "convert_callouts_to_deflist", "convert_callouts_interactive", "check_source_directives", "convert_tables_to_deflists", "check_published_links", "convert_freemarker_to_asciidoc"]

{rolfedh_doc_utils-0.1.38 → rolfedh_doc_utils-0.1.39}/rolfedh_doc_utils.egg-info/PKG-INFO

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

{rolfedh_doc_utils-0.1.38 → rolfedh_doc_utils-0.1.39}/rolfedh_doc_utils.egg-info/SOURCES.txt

@@ -7,6 +7,7 @@ check_scannability.py
 check_source_directives.py
 convert_callouts_interactive.py
 convert_callouts_to_deflist.py
+convert_freemarker_to_asciidoc.py
 convert_tables_to_deflists.py
 doc_utils_cli.py
 extract_link_attributes.py
@@ -23,6 +24,7 @@ callout_lib/converter_deflist.py
 callout_lib/detector.py
 callout_lib/table_parser.py
 doc_utils/__init__.py
+doc_utils/convert_freemarker_to_asciidoc.py
 doc_utils/extract_link_attributes.py
 doc_utils/file_utils.py
 doc_utils/format_asciidoc_spacing.py

{rolfedh_doc_utils-0.1.38 → rolfedh_doc_utils-0.1.39}/rolfedh_doc_utils.egg-info/entry_points.txt

@@ -6,6 +6,7 @@ check-scannability = check_scannability:main
 check-source-directives = check_source_directives:main
 convert-callouts-interactive = convert_callouts_interactive:main
 convert-callouts-to-deflist = convert_callouts_to_deflist:main
+convert-freemarker-to-asciidoc = convert_freemarker_to_asciidoc:main
 convert-tables-to-deflists = convert_tables_to_deflists:main
 doc-utils = doc_utils_cli:main
 extract-link-attributes = extract_link_attributes:main

{rolfedh_doc_utils-0.1.38 → rolfedh_doc_utils-0.1.39}/rolfedh_doc_utils.egg-info/top_level.txt

@@ -6,6 +6,7 @@ check_scannability
 check_source_directives
 convert_callouts_interactive
 convert_callouts_to_deflist
+convert_freemarker_to_asciidoc
 convert_tables_to_deflists
 doc_utils
 doc_utils_cli