positional.h File Reference

POSITIONAL ARGUMENTS section generator for man pages. More...

Go to the source code of this file.

Functions
char *	manpage_content_generate_positional (const options_config_t *config)
	Generate POSITIONAL ARGUMENTS section content.
void	manpage_content_free_positional (char *content)
	Free generated positional content.

Detailed Description

POSITIONAL ARGUMENTS section generator for man pages.

Generates the POSITIONAL ARGUMENTS section from positional argument descriptors showing what arguments a program accepts.

Definition in file positional.h.

Function Documentation

manpage_content_free_positional()

void manpage_content_free_positional

(

char *

content

)

Free generated positional content.

Parameters

[in]

content

Content to free (can be NULL)

Definition at line 74 of file positional.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_positional()

char * manpage_content_generate_positional

(

const options_config_t *

config

)

Generate POSITIONAL ARGUMENTS section content.

Creates POSITIONAL ARGUMENTS section from positional argument descriptors with proper groff formatting and examples.

Parameters

[in]

config

Options configuration with positional descriptors

Returns

Newly allocated content string (caller must free)

Definition at line 15 of file positional.c.

                                                                          {
  if (!config) {
    char *buffer = SAFE_MALLOC(1, char *);
    buffer[0] = '\0';
    return buffer;
  }
 
  if (config->num_positional_args == 0) {
    // Generate fallback content when no positional arguments 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 positional arguments for this mode.\n");
    log_debug("Generated POSITIONAL ARGUMENTS section (fallback - no args found)");
    return buffer;
  }
 
  // Allocate growing buffer for positional 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_positional_args; i++) {
    const positional_arg_descriptor_t *pos_arg = &config->positional_args[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 %s\n", pos_arg->name);
 
    if (pos_arg->help_text) {
      offset +=
          safe_snprintf(buffer + offset, buffer_capacity - offset, "%s\n", escape_groff_special(pos_arg->help_text));
    }
 
    // Add examples if present
    if (pos_arg->num_examples > 0) {
      offset += safe_snprintf(buffer + offset, buffer_capacity - offset, ".RS\n");
      offset += safe_snprintf(buffer + offset, buffer_capacity - offset, ".B Examples:\n");
      offset += safe_snprintf(buffer + offset, buffer_capacity - offset, ".RS\n");
      offset += safe_snprintf(buffer + offset, buffer_capacity - offset, ".nf\n");
      for (size_t j = 0; j < pos_arg->num_examples; j++) {
        offset += safe_snprintf(buffer + offset, buffer_capacity - offset, "%s\n",
                                escape_groff_special(pos_arg->examples[j]));
      }
      offset += safe_snprintf(buffer + offset, buffer_capacity - offset, ".fi\n");
      offset += safe_snprintf(buffer + offset, buffer_capacity - offset, ".RE\n");
      offset += safe_snprintf(buffer + offset, buffer_capacity - offset, ".RE\n");
    }
  }
 
  log_debug("Generated POSITIONAL ARGUMENTS section (%zu bytes)", offset);
  return buffer;
}

References escape_groff_special(), positional_arg_descriptor_t::examples, positional_arg_descriptor_t::help_text, log_debug, positional_arg_descriptor_t::name, positional_arg_descriptor_t::num_examples, options_config_t::num_positional_args, options_config_t::positional_args, SAFE_MALLOC, SAFE_REALLOC, and safe_snprintf().

Referenced by options_config_generate_manpage_merged(), and options_config_generate_manpage_template().