Using FindHTMLHelp for CHM File Generation in CMake

Purpose

• This compiler is essential for creating compiled HTML Help (CHM) files, a legacy documentation format used in older Windows applications.
• The FindHTMLHelp module is a built-in CMake module that assists in locating the Microsoft HTML Help Compiler (HHC.exe) on Windows systems.

Functionality

• If found, the module defines the following variables:
  • HTML_HELP_COMPILER: The full path to the HHC compiler executable (e.g., C:/Program Files (x86)/HTML Help Workshop/hhc.exe).
  • HTML_HELP_INCLUDE_PATH: The directory containing the htmlhelp.h header file (required for including the necessary API).
  • HTML_HELP_LIBRARY: The full path to the HTML Help library (e.g., C:/Program Files (x86)/HTML Help Workshop/hhc.lib).
• When you use find_package(FindHTMLHelp REQUIRED), CMake searches for the HHC compiler and related files (header and library) in standard locations.

Usage

1. find_package(FindHTMLHelp REQUIRED)
   

2. Check for Success
   

   if(NOT HTML_HELP_COMPILER)
       message(STATUS "HTML Help Compiler not found. CHM file generation disabled.")
   endif()
   

3. Use the Variables (if found)
   

   if(HTML_HELP_COMPILER)
       # Use HTML_HELP_COMPILER, HTML_HELP_INCLUDE_PATH, and HTML_HELP_LIBRARY
       # for building your CHM file
   endif()
   

Important Considerations

• If you must use CHM files, be aware that generating them might require additional tools or libraries.
• For modern documentation needs, consider alternative formats like Markdown, Sphinx-generated HTML, or online documentation platforms.
• FindHTMLHelp is primarily relevant for Windows development targeting older applications.

Alternative Approaches

• If targeting modern Windows applications, consider adopting newer documentation formats that provide better user experience and maintainability.
• For cross-platform documentation, explore tools like Sphinx or Doxygen that produce web-friendly HTML or other formats.

---

# Try finding the HTML Help Compiler (relevant primarily for Windows and CHM files)
find_package(FindHTMLHelp REQUIRED)

if(NOT HTML_HELP_COMPILER)
    message(STATUS "HTML Help Compiler not found. CHM file generation disabled.")
else()
    # Use the variables for building your CHM file
    message(STATUS "Found HTML Help Compiler at: ${HTML_HELP_COMPILER}")

    # Example: Assuming you have a project-specific script to generate CHM content (hhc.cmd)
    add_custom_command(
        OUTPUT "${PROJECT_BINARY_DIR}/myproject.chm"
        COMMAND "${CMAKE_COMMAND}" ARGV "-E" "execute_process" COMMAND "${HTML_HELP_COMPILER}"
                ARGS "... path/to/hhc.cmd" "${PROJECT_BINARY_DIR}/myproject.chm"
        WORKING_DIRECTORY "${PROJECT_SOURCE_DIR}"
        DEPENDS "${PROJECT_SOURCE_DIR}/hhc.cmd"
    )

    # Add the CHM file to your project's artifacts (optional)
    add_artifact("${PROJECT_BINARY_DIR}/myproject.chm")
endif()

# Alternative documentation considerations (for modern use cases):

# 1. Use Markdown and build tools like MkDocs for web-friendly documentation
# (Replace with your actual build command if using MkDocs)
# add_custom_command(OUTPUT "${PROJECT_BINARY_DIR}/docs"
#     COMMAND ... # MkDocs build command
#     WORKING_DIRECTORY "${PROJECT_SOURCE_DIR}/docs"
# )

# 2. Consider Sphinx for more complex documentation generation
# (Integration with CMake would depend on specific Sphinx setup)

# Choose the approach that best suits your project's requirements and target audience.

This example first attempts to locate the FindHTMLHelp module. If found, it uses the provided variables to build a sample CHM file using a hypothetical script (hhc.cmd) assumed to exist in your project.

Error Handling

• If the compiler is not found, a message is displayed, and CHM file generation is disabled.

• Comments demonstrate potential alternative documentation methods:
  • Using Markdown and a build tool like MkDocs for web-friendly documentation.
  • Employing Sphinx for more complex documentation generation (integration with CMake would vary depending on your Sphinx setup).

---

Cross-Platform Documentation

1. • Sphinx is a powerful Python-based toolset for creating comprehensive documentation, often used for complex software projects.
   • It generates a wide range of output formats, including HTML, PDF, and man pages.
   • Integration with CMake requires additional configuration and potentially custom modules, but offers a feature-rich solution.

Online Documentation Platforms

• These platforms offer features like versioning, search, and collaboration capabilities.
• Consider hosting your documentation online using platforms like Read the Docs, GitHub Pages, or GitLab Pages.

Choosing the Right Approach

• Online availability
  Hosting your documentation online provides better accessibility and collaboration options.
• Complex projects
  Sphinx offers more features and flexibility, ideal for extensive documentation with code samples, tutorials, etc.
• Simple projects
  Markdown with MkDocs or Hugo is a good choice for its ease of use and cross-platform compatibility.

Additional Considerations

• API documentation
  For API documentation, consider tools like Swagger (REST APIs) or OpenAPI Specification.
• Automatic documentation generation
  Tools like Doxygen (C++) or Breathe (C++ with Sphinx) can automatically generate documentation from code comments.