xml2man.c

Includes:

<inttypes.h>
<unistd.h>
<stdlib.h>
<stdio.h>
<string.h>
<dirent.h>
<libxml/parser.h>
<libxml/tree.h>
"strcompat.h"

Introduction

Converts HeaderDoc-generated XML output into a form suitable for use with xml2man.

Functions

checkcurword: Returns 1 if a token might potentially be misinterpreted as a macro. Used to control quoting.
dodtguts: Writes the guts of a term-and-definition, flag, or argument.
formattext: Emits a block of text, quoting tokens within it as needed.
getflagargs: Reads the argument list for a flag (from the XML tree) and creates data structures accordingly.
lasttextnode: Returns the last sibling of the current node, but only if it is a text node.
main: Main.
malloccat: A strcat variant that returns an allocated string.
nodematching: Returns the first node at the current level that matches the specified tag name.
nodesmatching: Returns an array of nodes at the current level that match the specified tag name.
parseUsage: Calls parseUsageSub.
parseUsageSub: Extracts the usage section from the XML tree and builds up data structures.
printUsageOptionList: Prints a list of options (A | B | C) for the USAGE section of a manual page.
propstring: Searches a list of XML properties and returns a string containing the text of the first property that matches the specified name.
propval: Returns the numerical value (integer) of an XML property.
safe_asprintf: Compatibility shim for Linux
strip_dotmxml: Strips the trailing .mxml from a filename.
striplines: Strips leading whitespace and replaces all line breaks with spaces.
textmatching: Returns the first text content of the first node at the current level that matches the specified tag name.
write_funcargs: Writes function arguments to the output file.
writeData: Writes a normal section to the output file.
writeData_sub: Writes a normal section to the output file.
writeOptionsSub: Writes the OPTIONS section of a manual page.
writeOptionsSubWithObject: Writes an individual option entry in the OPTIONS section of a manual page.
writeUsage: Writes the USAGE section of a manual page.
writeUsageSub: Writes an individual command usage inside the USAGE section of a manual page.
xml2man: The main body of the translator code.
xs: Returns a static buffer (not thread safe) containing the specified number of "X" characters.

checkcurword

Returns 1 if a token might potentially be misinterpreted as a macro. Used to control quoting.

int checkcurword(
    char *word,
    int textcontainer)

dodtguts

Writes the guts of a term-and-definition, flag, or argument.

void dodtguts(
    FILE *fp,
    xmlNode *parent,
    char *initial_add)

Discussion

In this context, we can't change lines to send a new command, so only certain things are allowed, and all commands are handled inline.

formattext

Emits a block of text, quoting tokens within it as needed.

char *formattext(
    char *text,
    int textcontainer)

getflagargs

Reads the argument list for a flag (from the XML tree) and creates data structures accordingly.

usage_t getflagargs(
    xmlNode *node)

lasttextnode

Returns the last sibling of the current node, but only if it is a text node.

xmlNode *lasttextnode(
    xmlNode *node)

main

Main.

int main(
    int argc,
    char *argv[])

malloccat

A strcat variant that returns an allocated string.

char *malloccat(
    const char *string1,
    const char *string2)

nodematching

Returns the first node at the current level that matches the specified tag name.

xmlNode *nodematching(
    char *name,
    xmlNode *cur)

nodesmatching

Returns an array of nodes at the current level that match the specified tag name.

xmlNode **nodesmatching(
    char *name,
    xmlNode *cur)

parseUsage

Calls parseUsageSub.

void parseUsage(
    xmlNode *node,
    int pos)

parseUsageSub

Extracts the usage section from the XML tree and builds up data structures.

void parseUsageSub(
    xmlNode *node,
    int pos,
    int drop_first_text)

printUsageOptionList

Prints a list of options (A | B | C) for the USAGE section of a manual page.

void printUsageOptionList(
    usage_t cur,
    FILE *fp,
    char *starting,
    char *separator)

propstring

Searches a list of XML properties and returns a string containing the text of the first property that matches the specified name.

char *propstring(
    char *name,
    struct _xmlAttr *prop)

propval

Returns the numerical value (integer) of an XML property.

int propval(
    char *name,
    struct _xmlAttr *prop)

safe_asprintf

Compatibility shim for Linux

int safe_asprintf(
    char **ret,
    const char *format,
    ...)

Discussion

Unlike the BSD implementation of asprintf, the Linux implementation does not guarantee that the variable pointed to by ret is set to NULL in the event of an error.

Because it is poor programming practice to accept a pointer from a system routine without checking to see if the routine returned NULL, this results in a rather messy pair of checks in order to get the desired behavior (one check for the return value, then another for the pointer).

This function works around that flaw in the Linux implementation by simply checking the return value, then setting the variable pointed to by ret to NULL in the event of an error.

strip_dotmxml

Strips the trailing .mxml from a filename.

void strip_dotmxml(
    char *filename)

striplines

Strips leading whitespace and replaces all line breaks with spaces.

char *striplines(
    char *line)

textmatching

Returns the first text content of the first node at the current level that matches the specified tag name.

char *textmatching(
    char *name,
    xmlNode *node,
    int missing_ok,
    char *debugstr)

write_funcargs

Writes function arguments to the output file.

void write_funcargs(
    FILE *fp,
    usage_t cur)

writeData

Writes a normal section to the output file.

void writeData(
    FILE *fp,
    xmlNode *node)

Discussion

Calls writeData_sub to do all the real work.

writeData_sub

Writes a normal section to the output file.

void writeData_sub(
    FILE *fp,
    xmlNode *node,
    int state,
    int textcontainer,
    int next,
    int seendt)

writeOptionsSub

Writes the OPTIONS section of a manual page.

void writeOptionsSub(
    FILE *fp,
    xmlNode *description,
    int lwc)

writeOptionsSubWithObject

Writes an individual option entry in the OPTIONS section of a manual page.

int writeOptionsSubWithObject(
    FILE *fp,
    usage_t obj,
    int pos,
    int topfirst,
    int lwc,
    int noheading)

writeUsage

Writes the USAGE section of a manual page.

void writeUsage(
    FILE *fp,
    xmlNode *description)

writeUsageSub

Writes an individual command usage inside the USAGE section of a manual page.

int writeUsageSub(
    FILE *fp,
    int showname,
    usage_t myusagehead,
    char *name_or_empty,
    char *optional_separator)

xml2man

The main body of the translator code.

void xml2man(
    xmlNode *root,
    char *output_filename,
    int append_section_number)

Discussion

Takes an XML tree, an output filename, and a flag to indicate whether the section number should be appended to that filename, then translatest that into the -mdoc macro set.

xs

Returns a static buffer (not thread safe) containing the specified number of "X" characters.

char *xs(
    int count)

Enumerated Types

states: State values that represent where we are in the document.
stripstate: The current state in the striplines function.

states

State values that represent where we are in the document.

enum states { 
    kGeneral = 0, 
    kNames = 1, 
    kRetval = 2, 
    kMan = 3, 
};

Constants

kGeneral: The normal state.
kNames: Inside the NAME section.
kRetval: Inside the RETURN VALUES section.
kMan: Inside a .Xr cross reference.

stripstate

The current state in the striplines function.

enum stripstate { 
    kSOL = 1, 
    kText = 2 
};

Constants

kSOL: Short for "start of line", this is the initial state and the state after a newline but before any non-whitespace.
kText: This is the state after text has appeared on a line.

Last Updated: Saturday, August 06, 2016