merger.h File Reference

Man page content merging and orchestration. More...

Go to the source code of this file.

Functions
char *	manpage_merger_merge_options (const options_config_t *config, const parsed_section_t *existing_section)
	Merge auto-generated options into section content.
char *	manpage_merger_merge_environment (const options_config_t *config, const parsed_section_t *existing_section)
	Merge environment variables from auto-generated and manual sources.
char *	manpage_merger_merge_positional (const options_config_t *config, const parsed_section_t *existing_section)
	Merge positional arguments and examples.
asciichat_error_t	manpage_merger_generate_usage (const options_config_t *config, char **out_content, size_t *out_len)
	Get auto-generated usage content.
asciichat_error_t	manpage_merger_generate_synopsis (const char *mode_name, char **out_content, size_t *out_len)
	Get auto-generated synopsis content.
void	manpage_merger_free_content (char *content)
	Free merged section content.

Detailed Description

Man page content merging and orchestration.

This module orchestrates the complete man page generation pipeline:

1. Load resources (template and content files)
2. Parse existing sections to preserve manual content
3. Generate or merge new sections
4. Write final output with proper formatting

Handles three section types:

• AUTO: Fully auto-generated, regenerated each time
• MANUAL: User-maintained, never modified by generator
• MERGE: Intelligent merge of auto-generated and manual content

Definition in file merger.h.

Function Documentation

manpage_merger_free_content()

void manpage_merger_free_content

(

char *

content

)

Free merged section content.

Frees memory allocated by merger functions. Safe to call with NULL.

Parameters

[in]

content

Content to free (can be NULL)

Definition at line 182 of file merger.c.

                                                {
  if (content) {
    SAFE_FREE(content);
  }
}

References SAFE_FREE.

Referenced by options_config_generate_manpage_template().

manpage_merger_generate_synopsis()

asciichat_error_t manpage_merger_generate_synopsis	(	const char *	mode_name,
		char **	out_content,
		size_t *	out_len )

Get auto-generated synopsis content.

Generates the SYNOPSIS section for the specified mode.

Parameters

[in]	mode_name	Mode name or NULL for binary-level
[out]	out_content	Pointer to store generated content
[out]	out_len	Pointer to store content length

Returns

ASCIICHAT_OK on success, error code on failure

Note

Caller must free out_content using SAFE_FREE

Definition at line 140 of file merger.c.

                                                                                                               {
  if (!out_content || !out_len) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid output parameters");
  }
 
  // Allocate buffer for synopsis
  size_t buffer_size = MANPAGE_INITIAL_BUFFER_SIZE;
  char *buffer = SAFE_MALLOC(buffer_size, char *);
  size_t offset = 0;
 
  // Note: Section header is already in template, don't duplicate it
 
  if (mode_name) {
    // Mode-specific synopsis
    offset += safe_snprintf(buffer + offset, buffer_size - offset,
                            ".B ascii-chat\n"
                            ".I %s\n"
                            "[\\fIoptions\\fR]\n",
                            mode_name);
  } else {
    // Binary-level synopsis - show main modes
    offset += safe_snprintf(buffer + offset, buffer_size - offset,
                            ".B ascii-chat\n"
                            "[\\fIoptions\\fR]\n"
                            "\n"
                            ".B ascii-chat\n"
                            "[\\fIoptions\\fR] \\fI<session-string>\\fR\n"
                            "\n"
                            ".B ascii-chat\n"
                            "[\\fIoptions\\fR] [\\fBserver\\fR | \\fBclient\\fR | \\fBmirror\\fR | "
                            "\\fBdiscovery-service\\fR] [\\fImode-options\\fR]\n");
  }
 
  offset += safe_snprintf(buffer + offset, buffer_size - offset, "\n");
 
  *out_content = buffer;
  *out_len = offset;
 
  log_debug("Generated synopsis section (%zu bytes)", *out_len);
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, buffer_size, ERROR_INVALID_PARAM, log_debug, MANPAGE_INITIAL_BUFFER_SIZE, SAFE_MALLOC, safe_snprintf(), and SET_ERRNO.

Referenced by options_config_generate_manpage_template().

manpage_merger_generate_usage()

asciichat_error_t manpage_merger_generate_usage	(	const options_config_t *	config,
		char **	out_content,
		size_t *	out_len )

Get auto-generated usage content.

Generates the USAGE section from options config usage descriptors.

Parameters

[in]	config	Options config (can be NULL to generate all modes)
[out]	out_content	Pointer to store generated content
[out]	out_len	Pointer to store content length

Returns

ASCIICHAT_OK on success, error code on failure

Note

Caller must free out_content using SAFE_FREE

Definition at line 82 of file merger.c.

                                                                                                                     {
  if (!out_content || !out_len) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid output parameters");
  }
 
  if (!config || config->num_usage_lines == 0) {
    *out_content = SAFE_MALLOC(1, char *);
    (*out_content)[0] = '\0';
    *out_len = 0;
    return ASCIICHAT_OK;
  }
 
  // Allocate growing buffer for usage section
  size_t buffer_capacity = 4096;
  char *buffer = SAFE_MALLOC(buffer_capacity, char *);
  size_t offset = 0;
 
  for (size_t i = 0; i < config->num_usage_lines; i++) {
    const usage_descriptor_t *usage = &config->usage_lines[i];
 
    // Ensure buffer is large enough
    if (offset + 512 >= buffer_capacity) {
      buffer_capacity *= 2;
      buffer = SAFE_REALLOC(buffer, buffer_capacity, char *);
    }
 
    offset += safe_snprintf(buffer + offset, buffer_capacity - offset, ".TP\n");
    offset += safe_snprintf(buffer + offset, buffer_capacity - offset, ".B ascii-chat");
    if (usage->mode) {
      offset += safe_snprintf(buffer + offset, buffer_capacity - offset, " %s", usage->mode);
    }
    if (usage->positional) {
      offset += safe_snprintf(buffer + offset, buffer_capacity - offset, " %s", usage->positional);
    }
    if (usage->show_options) {
      // Use mode-specific options suffix for mode commands, regular options for binary-level
      if (usage->mode && strcmp(usage->mode, "<mode>") != 0) {
        offset += safe_snprintf(buffer + offset, buffer_capacity - offset, " [mode-options...]");
      } else {
        offset += safe_snprintf(buffer + offset, buffer_capacity - offset, " [options...]");
      }
    }
    offset += safe_snprintf(buffer + offset, buffer_capacity - offset, "\n");
 
    if (usage->description) {
      offset += safe_snprintf(buffer + offset, buffer_capacity - offset, "%s\n", usage->description);
    }
  }
 
  offset += safe_snprintf(buffer + offset, buffer_capacity - offset, "\n");
 
  *out_content = buffer;
  *out_len = offset;
 
  log_debug("Generated usage section (%zu bytes)", offset);
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, buffer_capacity(), ERROR_INVALID_PARAM, log_debug, options_config_t::num_usage_lines, SAFE_MALLOC, SAFE_REALLOC, safe_snprintf(), SET_ERRNO, usage(), and options_config_t::usage_lines.

Referenced by options_config_generate_manpage_template().

manpage_merger_merge_environment()

char * manpage_merger_merge_environment	(	const options_config_t *	config,
		const parsed_section_t *	existing_section )

Merge environment variables from auto-generated and manual sources.

Takes environment variables from the options config and intelligently merges them with existing manual environment documentation (if any).

Handles deduplication and sorting of environment variable names while preserving manual descriptions where they exist.

Parameters

[in]	config	Options config with auto-generated environment variables
[in]	existing_section	Existing section with manual documentation (can be NULL)

Returns

Newly allocated merged content (caller must free)

Note

Caller must free the returned string

Definition at line 44 of file merger.c.

                                                                                                                 {
  (void)existing_section; // Unused for now
 
  if (!config) {
    return NULL;
  }
 
  // For now, return empty content. In a full implementation, this would:
  // 1. Extract environment variables from config options
  // 2. Parse existing section for manual env var documentation
  // 3. Merge and deduplicate
  // 4. Return sorted, merged content
 
  log_debug("Merging environment section (currently unimplemented - returns empty)");
  char *content = SAFE_MALLOC(1, char *);
  content[0] = '\0';
  return content;
}

References log_debug, and SAFE_MALLOC.

manpage_merger_merge_options()

char * manpage_merger_merge_options	(	const options_config_t *	config,
		const parsed_section_t *	existing_section )

Merge auto-generated options into section content.

Takes auto-generated options content from config and intelligently merges it with existing manual options (if any). Removes duplicates by option name while preserving manual descriptions.

Currently returns the auto-generated content as-is. In a full implementation, this would parse both auto and manual option lists and merge them.

Parameters

[in]	config	Options config with auto-generated options
[in]	existing_section	Existing section with manual options (can be NULL)

Returns

Newly allocated merged content (caller must free)

Note

Caller must free the returned string

Definition at line 25 of file merger.c.

                                                                                                             {
  (void)existing_section; // Unused for now
 
  if (!config) {
    return NULL;
  }
 
  // For now, return empty content. In a full implementation, this would:
  // 1. Generate options from config
  // 2. Parse existing section for manual options
  // 3. Merge them by option name
  // 4. Return merged content
 
  log_debug("Merging options section (currently unimplemented - returns empty)");
  char *content = SAFE_MALLOC(1, char *);
  content[0] = '\0';
  return content;
}

References log_debug, and SAFE_MALLOC.

manpage_merger_merge_positional()

char * manpage_merger_merge_positional	(	const options_config_t *	config,
		const parsed_section_t *	existing_section )

Merge positional arguments and examples.

Takes auto-generated positional arguments and examples and merges with existing manual content.

Parameters

[in]	config	Options config with auto-generated positional args
[in]	existing_section	Existing section (can be NULL)

Returns

Newly allocated merged content (caller must free)

Note

Caller must free the returned string

Definition at line 63 of file merger.c.

                                                                                                                {
  (void)existing_section; // Unused for now
 
  if (!config) {
    return NULL;
  }
 
  // For now, return empty content. In a full implementation, this would:
  // 1. Generate positional arguments from config
  // 2. Parse existing section for manual content
  // 3. Merge intelligently
  // 4. Return merged content
 
  log_debug("Merging positional section (currently unimplemented - returns empty)");
  char *content = SAFE_MALLOC(1, char *);
  content[0] = '\0';
  return content;
}

References log_debug, and SAFE_MALLOC.