parser_md.c

Go to the documentation of this file.

/*!
   \file lib/gis/parser_md.c
 
   \brief GIS Library - Argument parsing functions (Markdown output)
 
   SPDX-FileCopyrightText: 2012-2025 GRASS Development Team
   SPDX-License-Identifier: GPL-2.0-or-later
 
   \author Martin Landa
   \author Vaclav Petras
 */
#include <stdio.h>
#include <string.h>
 
#include <grass/gis.h>
#include <grass/glocale.h>
 
#include "parser_local_proto.h"
 
/*!
   \brief Print a string as the content of a double-quoted YAML scalar.
 
   Escapes the characters that are special inside a double-quoted YAML
   scalar (backslash and double quote). Quoting the value lets it contain
   YAML-significant sequences such as ": " without breaking the parser.
 
   \param str string to print (escaped) to stdout
 */
static void print_yaml_escaped(const char *str)
{
    for (const char *p = str; *p; p++) {
        if (*p == '\\' || *p == '"')
            fprintf(stdout, "\\");
        fprintf(stdout, "%c", *p);
    }
}
 
/*!
   \brief Print module usage description in Markdown format.
 */
void G__usage_markdown(void)
{
    if (!st->pgm_name)
        st->pgm_name = G_program_name();
    if (!st->pgm_name)
        st->pgm_name = "??";
 
    /* print metadata used by man/build*.py */
    fprintf(stdout, "---\n");
    fprintf(stdout, "name: %s\n", st->pgm_name);
    fprintf(stdout, "description: \"");
    if (st->module_info.label)
        print_yaml_escaped(st->module_info.label);
    if (st->module_info.label && st->module_info.description)
        fprintf(stdout, " ");
    if (st->module_info.description)
        print_yaml_escaped(st->module_info.description);
    fprintf(stdout, "\"\n");
    fprintf(stdout, "keywords: [ ");
    G__print_keywords(stdout, NULL, FALSE);
    fprintf(stdout, " ]");
    fprintf(stdout, "\n---\n\n");
 
    /* main header */
    fprintf(stdout, "# %s\n\n", st->pgm_name);
 
    /* header */
    if (st->module_info.label)
        fprintf(stdout, "%s\n", st->module_info.label);
 
    if (st->module_info.description) {
        if (st->module_info.label)
            fprintf(stdout, "\n");
        fprintf(stdout, "%s\n", st->module_info.description);
    }
 
    const char *tab_indent = "    ";
 
    /* short version */
    fprintf(stdout, "\n=== \"Command line\"\n\n");
    G__md_print_cli_short_version(stdout, tab_indent);
    fprintf(stdout, "\n=== \"Python (grass.tools)\"\n\n");
    G__md_print_python_short_version(stdout, tab_indent, true);
    fprintf(stdout, "\n=== \"Python (grass.script)\"\n\n");
    G__md_print_python_short_version(stdout, tab_indent, false);
 
    fprintf(stdout, "\n## %s\n", _("Parameters"));
 
    /* long version */
    fprintf(stdout, "\n=== \"Command line\"\n\n");
    G__md_print_cli_long_version(stdout, tab_indent);
    fprintf(stdout, "\n=== \"Python (grass.tools)\"\n\n");
    G__md_print_python_long_version(stdout, tab_indent, true);
    fprintf(stdout, "\n=== \"Python (grass.script)\"\n\n");
    G__md_print_python_long_version(stdout, tab_indent, false);
}