examples.h File Reference

EXAMPLES section generator for man pages. More...

Go to the source code of this file.

Functions
char *	manpage_content_generate_examples (const options_config_t *config)
	Generate EXAMPLES section content.
void	manpage_content_free_examples (char *content)
	Free generated examples content.

Detailed Description

EXAMPLES section generator for man pages.

Generates the EXAMPLES section from example descriptors showing common usage patterns.

Definition in file examples.h.

Function Documentation

manpage_content_free_examples()

void manpage_content_free_examples

(

char *

content

)

Free generated examples content.

Parameters

[in]

content

Content to free (can be NULL)

Definition at line 147 of file examples.c.

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

References SAFE_FREE.

Referenced by options_config_generate_manpage_merged(), and options_config_generate_manpage_template().

manpage_content_generate_examples()

char * manpage_content_generate_examples

(

const options_config_t *

config

)

Generate EXAMPLES section content.

Creates EXAMPLES section from example descriptors with proper code block and description formatting.

Parameters

[in]

config

Options configuration with example descriptors

Returns

Newly allocated content string (caller must free)

Definition at line 79 of file examples.c.

                                                                        {
  if (!config) {
    char *buffer = SAFE_MALLOC(1, char *);
    buffer[0] = '\0';
    return buffer;
  }
 
  if (config->num_examples == 0) {
    // Generate fallback content when no examples are defined
    size_t buffer_capacity = 256;
    char *buffer = SAFE_MALLOC(buffer_capacity, char *);
    size_t offset = 0;
    offset += safe_snprintf(buffer + offset, buffer_capacity - offset, ".PP\nNo examples available for this mode.\n");
    log_debug("Generated EXAMPLES section (fallback - no examples found)");
    return buffer;
  }
 
  // Allocate growing buffer for examples section
  size_t buffer_capacity = 8192;
  char *buffer = SAFE_MALLOC(buffer_capacity, char *);
  size_t offset = 0;
 
  for (size_t i = 0; i < config->num_examples; i++) {
    const example_descriptor_t *example = &config->examples[i];
 
    // Get all mode names from bitmask (examples can apply to multiple modes)
    // For man pages, we only show each example once, randomly selecting one mode
    size_t num_modes = 0;
    const char **mode_names = get_all_mode_names_from_bitmask(example->mode_bitmask, &num_modes);
 
    // 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");
 
    // Add mode name if applicable (randomly select one mode for multi-mode examples)
    if (num_modes > 0) {
      size_t selected_mode = randombytes_uniform((uint32_t)num_modes);
      if (mode_names[selected_mode]) {
        offset += safe_snprintf(buffer + offset, buffer_capacity - offset, " %s", mode_names[selected_mode]);
      }
    }
 
    if (example->args) {
      offset += safe_snprintf(buffer + offset, buffer_capacity - offset, " %s", example->args);
    }
    offset += safe_snprintf(buffer + offset, buffer_capacity - offset, "\n");
 
    if (example->description) {
      offset +=
          safe_snprintf(buffer + offset, buffer_capacity - offset, "%s\n", escape_groff_special(example->description));
    }
 
    // Free mode names array
    if (mode_names) {
      SAFE_FREE(mode_names);
    }
  }
 
  offset += safe_snprintf(buffer + offset, buffer_capacity - offset, "\n");
 
  return buffer;
}

References example_descriptor_t::args, example_descriptor_t::description, escape_groff_special(), options_config_t::examples, log_debug, example_descriptor_t::mode_bitmask, options_config_t::num_examples, SAFE_FREE, SAFE_MALLOC, SAFE_REALLOC, and safe_snprintf().

Referenced by options_config_generate_manpage_merged(), and options_config_generate_manpage_template().