formatter.h File Reference

Groff/troff formatting utilities for man page generation. More...

Go to the source code of this file.

Functions
const char *	manpage_fmt_escape_groff (const char *str)
	Escape special characters for groff output.
void	manpage_fmt_write_section (FILE *f, const char *section_name)
	Write a section header directive.
void	manpage_fmt_write_blank_line (FILE *f)
	Write a blank line (for spacing between sections).
void	manpage_fmt_write_bold (FILE *f, const char *text)
	Write text in bold format.
void	manpage_fmt_write_italic (FILE *f, const char *text)
	Write text in italic format.
void	manpage_fmt_write_tagged_paragraph (FILE *f)
	Write a tagged paragraph header.
void	manpage_fmt_write_text (FILE *f, const char *text)
	Write plain text line (without directive).
void	manpage_fmt_write_title (FILE *f, const char *program_name, const char *mode_name, const char *brief_description)
	Write groff title/header (.TH directive).

Detailed Description

Groff/troff formatting utilities for man page generation.

This module provides utilities for generating properly formatted groff/troff output for man pages. Handles:

• Section headers (.SH directive)
• Text formatting (bold .B, italic .I, constant .C)
• Paragraph and item formatting (.TP for tagged paragraphs)
• Special character escaping
• Section markers (AUTO/MANUAL/MERGE)

All functions write directly to FILE* for efficient streaming output.

Definition in file formatter.h.

Function Documentation

manpage_fmt_escape_groff()

const char * manpage_fmt_escape_groff

(

const char *

str

)

Escape special characters for groff output.

Escapes characters that have special meaning in groff format. Currently returns the string as-is since most man page content doesn't contain problematic characters. Can be extended for more robust escaping if needed.

Parameters

[in]

str

String to escape (can be NULL)

Returns

Escaped string (never NULL, returns "" for NULL input)

Note

This is a simple implementation. For production use with arbitrary content, consider a more robust escaping strategy.

Definition at line 25 of file formatter.c.

                                                      {
  // For simplicity, we'll just return the string as-is
  // In a more robust implementation, we'd escape special characters
  // But for man page content, most strings don't have problematic characters
  return str ? str : "";
}

Referenced by manpage_fmt_write_title().

manpage_fmt_write_blank_line()

void manpage_fmt_write_blank_line

(

FILE *

f

)

Write a blank line (for spacing between sections).

Parameters

[in]

f

Output file handle (cannot be NULL)

Definition at line 39 of file formatter.c.

                                           {
  if (!f) {
    return;
  }
  fprintf(f, "\n");
}

Referenced by options_config_generate_manpage_template().

manpage_fmt_write_bold()

void manpage_fmt_write_bold	(	FILE *	f,
		const char *	text )

Write text in bold format.

Writes text with bold formatting directive. Example: manpage_fmt_write_bold(f, "ascii-chat") writes ".B ascii-chat\n"

Parameters

[in]	f	Output file handle (cannot be NULL)
[in]	text	Text to write in bold (cannot be NULL)

Definition at line 46 of file formatter.c.

                                                       {
  if (!f || !text) {
    return;
  }
  fprintf(f, ".B %s\n", text);
}

manpage_fmt_write_italic()

void manpage_fmt_write_italic	(	FILE *	f,
		const char *	text )

Write text in italic format.

Writes text with italic formatting directive. Example: manpage_fmt_write_italic(f, "options") writes ".I options\n"

Parameters

[in]	f	Output file handle (cannot be NULL)
[in]	text	Text to write in italic (cannot be NULL)

Definition at line 53 of file formatter.c.

                                                         {
  if (!f || !text) {
    return;
  }
  fprintf(f, ".I %s\n", text);
}

manpage_fmt_write_section()

void manpage_fmt_write_section	(	FILE *	f,
		const char *	section_name )

Write a section header directive.

Writes ".SH SECTION_NAME" directive to output. Example: manpage_fmt_write_section(f, "OPTIONS") writes ".SH OPTIONS\n"

Parameters

[in]	f	Output file handle (cannot be NULL)
[in]	section_name	Section name to write (cannot be NULL)

Definition at line 32 of file formatter.c.

                                                                  {
  if (!f || !section_name) {
    return;
  }
  fprintf(f, ".SH %s\n", section_name);
}

Referenced by options_config_generate_manpage_template().

manpage_fmt_write_tagged_paragraph()

void manpage_fmt_write_tagged_paragraph

(

FILE *

f

)

Write a tagged paragraph header.

Writes ".TP" directive to start a tagged paragraph (for option descriptions). Should be followed by manpage_fmt_write_bold() for the tag and then regular text for the description.

Parameters

[in]

f

Output file handle (cannot be NULL)

Definition at line 60 of file formatter.c.

                                                 {
  if (!f) {
    return;
  }
  fprintf(f, ".TP\n");
}

manpage_fmt_write_text()

void manpage_fmt_write_text	(	FILE *	f,
		const char *	text )

Write plain text line (without directive).

Writes text directly without any formatting directive. Useful for description text and content lines.

Parameters

[in]	f	Output file handle (cannot be NULL)
[in]	text	Text to write (can be NULL, in which case only newline written)

Definition at line 67 of file formatter.c.

                                                       {
  if (!f) {
    return;
  }
 
  if (text) {
    fprintf(f, "%s\n", text);
  } else {
    fprintf(f, "\n");
  }
}

manpage_fmt_write_title()

void manpage_fmt_write_title	(	FILE *	f,
		const char *	program_name,
		const char *	mode_name,
		const char *	brief_description )

Write groff title/header (.TH directive).

Writes the full title header for a man page with current date. Format: .TH NAME SECTION DATE SOURCE MANUAL

Parameters

[in]	f	Output file handle (cannot be NULL)
[in]	program_name	Program name (e.g., "ascii-chat") (cannot be NULL)
[in]	mode_name	Mode name or NULL (e.g., "server", "client", or NULL for binary-level)
[in]	brief_description	One-line description (cannot be NULL)

Definition at line 79 of file formatter.c.

                                                                                                                      {
  if (!f || !program_name || !brief_description) {
    return;
  }
 
  time_t now = time(NULL);
  struct tm tm_buf;
  platform_localtime(&now, &tm_buf);
  char date_str[OPTIONS_MANPAGE_FORMATTER_DATE_BUFFER_SIZE];
  strftime(date_str, sizeof(date_str), "%B %Y", &tm_buf);
 
  // Build full program name (e.g., "ascii-chat-server" or just "ascii-chat")
  char full_name[OPTIONS_MANPAGE_FORMATTER_FULL_NAME_BUFFER_SIZE];
  if (mode_name) {
    safe_snprintf(full_name, sizeof(full_name), "%s-%s", program_name, mode_name);
  } else {
    safe_snprintf(full_name, sizeof(full_name), "%s", program_name);
  }
 
  // .TH NAME SECTION DATE SOURCE MANUAL
  // Section 1 = user commands, 5 = file formats
  fprintf(f, ".TH %s 1 \"%s\" \"%s\" \"User Commands\"\n", full_name, date_str, program_name);
  fprintf(f, ".SH NAME\n");
  fprintf(f, ".B %s\n", full_name);
  fprintf(f, "\\- %s\n", manpage_fmt_escape_groff(brief_description));
  fprintf(f, "\n");
}

References manpage_fmt_escape_groff(), OPTIONS_MANPAGE_FORMATTER_DATE_BUFFER_SIZE, OPTIONS_MANPAGE_FORMATTER_FULL_NAME_BUFFER_SIZE, platform_localtime(), and safe_snprintf().

Referenced by options_config_generate_manpage_template().