GRASS GIS 7 Programmer's Manual  7.9.dev(2021)-e5379bbd7
parser_html.c
Go to the documentation of this file.
1 /*!
2  \file lib/gis/parser_html.c
3 
4  \brief GIS Library - Argument parsing functions (HTML output)
5 
6  (C) 2001-2009, 2011-2020 by the GRASS Development Team
7 
8  This program is free software under the GNU General Public License
9  (>=v2). Read the file COPYING that comes with GRASS for details.
10 
11  \author Original author CERL
12 */
13 
14 #include <stdio.h>
15 #include <string.h>
16 
17 #include <grass/gis.h>
18 #include <grass/glocale.h>
19 
20 #include "parser_local_proto.h"
21 
22 static void print_escaped_for_html(FILE *, const char *);
23 static void print_escaped_for_html_options(FILE *, const char *);
24 static void print_escaped_for_html_keywords(FILE * , const char *);
25 
26 /*!
27  \brief Print module usage description in HTML format.
28 */
29 void G__usage_html(void)
30 {
31  struct Option *opt;
32  struct Flag *flag;
33  const char *type;
34  int new_prompt = 0;
35 
36  new_prompt = G__uses_new_gisprompt();
37 
38  if (!st->pgm_name) /* v.dave && r.michael */
39  st->pgm_name = G_program_name();
40  if (!st->pgm_name)
41  st->pgm_name = "??";
42 
43  fprintf(stdout,
44  "<!DOCTYPE HTML PUBLIC \"-//W3C//DTD HTML 4.01 Transitional//EN\">\n");
45  fprintf(stdout, "<html>\n<head>\n");
46  fprintf(stdout,
47  " <meta http-equiv=\"Content-Type\" content=\"text/html; charset=iso-8859-1\">\n");
48  fprintf(stdout, " <title>%s - GRASS GIS manual</title>\n", st->pgm_name);
49  fprintf(stdout, " <meta name=\"description\" content=\"%s", st->pgm_name);
50  if (st->module_info.description)
51  fprintf(stdout, ": %s\">", st->module_info.description);
52  else
53  fprintf(stderr,"<%s.html> is missing the description", st->pgm_name);
54  fprintf(stdout, "\n");
55  if (st->module_info.keywords) {
56  fprintf(stdout, " <meta name=\"keywords\" content=\"");
57  G__print_keywords(stdout, NULL);
58  fprintf(stdout, "\">");
59  fprintf(stdout, "\n");
60  }
61  fprintf(stdout,
62  " <link rel=\"stylesheet\" href=\"grassdocs.css\" type=\"text/css\">\n");
63  fprintf(stdout, "</head>\n");
64  fprintf(stdout, "<body bgcolor=\"white\">\n");
65  fprintf(stdout, "<div id=\"container\">\n\n");
66  fprintf(stdout,
67  "<a href=\"index.html\"><img src=\"grass_logo.png\" alt=\"GRASS logo\"></a>\n");
68  fprintf(stdout, "<hr class=\"header\">\n\n");
69  fprintf(stdout, "<h2>%s</h2>\n", _("NAME"));
70  fprintf(stdout, "<em><b>%s</b></em> ", st->pgm_name);
71 
72  if (st->module_info.label || st->module_info.description)
73  fprintf(stdout, " - ");
74 
75  if (st->module_info.label)
76  fprintf(stdout, "%s<BR>\n", st->module_info.label);
77 
78  if (st->module_info.description)
79  fprintf(stdout, "%s\n", st->module_info.description);
80 
81 
82  fprintf(stdout, "<h2>%s</h2>\n", _("KEYWORDS"));
83  if (st->module_info.keywords) {
84  G__print_keywords(stdout, print_escaped_for_html_keywords);
85  fprintf(stdout, "\n");
86  }
87  fprintf(stdout, "<h2>%s</h2>\n", _("SYNOPSIS"));
88  fprintf(stdout, "<div id=\"name\"><b>%s</b><br></div>\n", st->pgm_name);
89  fprintf(stdout, "<b>%s --help</b><br>\n", st->pgm_name);
90 
91  fprintf(stdout, "<div id=\"synopsis\"><b>%s</b>", st->pgm_name);
92 
93  /* print short version first */
94  if (st->n_flags) {
95  flag = &st->first_flag;
96  fprintf(stdout, " [-<b>");
97  while (flag != NULL) {
98  fprintf(stdout, "%c", flag->key);
99  flag = flag->next_flag;
100  }
101  fprintf(stdout, "</b>] ");
102  }
103  else
104  fprintf(stdout, " ");
105 
106  if (st->n_opts) {
107  opt = &st->first_option;
108 
109  while (opt != NULL) {
110  if (opt->key_desc != NULL)
111  type = opt->key_desc;
112  else
113  switch (opt->type) {
114  case TYPE_INTEGER:
115  type = "integer";
116  break;
117  case TYPE_DOUBLE:
118  type = "float";
119  break;
120  case TYPE_STRING:
121  type = "string";
122  break;
123  default:
124  type = "string";
125  break;
126  }
127  if (!opt->required)
128  fprintf(stdout, " [");
129  fprintf(stdout, "<b>%s</b>=<em>%s</em>", opt->key, type);
130  if (opt->multiple) {
131  fprintf(stdout, "[,<i>%s</i>,...]", type);
132  }
133  if (!opt->required)
134  fprintf(stdout, "] ");
135 
136  opt = opt->next_opt;
137  fprintf(stdout, " ");
138  }
139  }
140  if (new_prompt)
141  fprintf(stdout, " [--<b>overwrite</b>] ");
142 
143  fprintf(stdout, " [--<b>help</b>] ");
144  fprintf(stdout, " [--<b>verbose</b>] ");
145  fprintf(stdout, " [--<b>quiet</b>] ");
146  fprintf(stdout, " [--<b>ui</b>] ");
147 
148  fprintf(stdout, "\n</div>\n");
149 
150  /* now long version */
151  fprintf(stdout, "\n");
152  fprintf(stdout, "<div id=\"flags\">\n");
153  fprintf(stdout, "<h3>%s:</h3>\n", _("Flags"));
154  fprintf(stdout, "<dl>\n");
155  if (st->n_flags) {
156  flag = &st->first_flag;
157  while (st->n_flags && flag != NULL) {
158  fprintf(stdout, "<dt><b>-%c</b></dt>\n", flag->key);
159 
160  if (flag->label) {
161  fprintf(stdout, "<dd>");
162  fprintf(stdout, "%s", flag->label);
163  fprintf(stdout, "</dd>\n");
164  }
165 
166  if (flag->description) {
167  fprintf(stdout, "<dd>");
168  fprintf(stdout, "%s", flag->description);
169  fprintf(stdout, "</dd>\n");
170  }
171 
172  flag = flag->next_flag;
173  fprintf(stdout, "\n");
174  }
175  }
176  if (new_prompt) {
177  fprintf(stdout, "<dt><b>--overwrite</b></dt>\n");
178  fprintf(stdout, "<dd>%s</dd>\n",
179  _("Allow output files to overwrite existing files"));
180  }
181  /* these flags are always available */
182  fprintf(stdout, "<dt><b>--help</b></dt>\n");
183  fprintf(stdout, "<dd>%s</dd>\n", _("Print usage summary"));
184 
185  fprintf(stdout, "<dt><b>--verbose</b></dt>\n");
186  fprintf(stdout, "<dd>%s</dd>\n", _("Verbose module output"));
187 
188  fprintf(stdout, "<dt><b>--quiet</b></dt>\n");
189  fprintf(stdout, "<dd>%s</dd>\n", _("Quiet module output"));
190 
191  fprintf(stdout, "<dt><b>--ui</b></dt>\n");
192  fprintf(stdout, "<dd>%s</dd>\n", _("Force launching GUI dialog"));
193 
194  fprintf(stdout, "</dl>\n");
195  fprintf(stdout, "</div>\n");
196 
197  fprintf(stdout, "\n");
198  fprintf(stdout, "<div id=\"parameters\">\n");
199  if (st->n_opts) {
200  opt = &st->first_option;
201  fprintf(stdout, "<h3>%s:</h3>\n", _("Parameters"));
202  fprintf(stdout, "<dl>\n");
203 
204  while (opt != NULL) {
205  /* TODO: make this a enumeration type? */
206  if (opt->key_desc != NULL)
207  type = opt->key_desc;
208  else
209  switch (opt->type) {
210  case TYPE_INTEGER:
211  type = "integer";
212  break;
213  case TYPE_DOUBLE:
214  type = "float";
215  break;
216  case TYPE_STRING:
217  type = "string";
218  break;
219  default:
220  type = "string";
221  break;
222  }
223  fprintf(stdout, "<dt><b>%s</b>=<em>%s", opt->key, type);
224  if (opt->multiple) {
225  fprintf(stdout, "[,<i>%s</i>,...]", type);
226  }
227  fprintf(stdout, "</em>");
228  if (opt->required) {
229  fprintf(stdout, "&nbsp;<b>[required]</b>");
230  }
231  fprintf(stdout, "</dt>\n");
232 
233  if (opt->label) {
234  fprintf(stdout, "<dd>");
235  print_escaped_for_html(stdout, opt->label);
236  fprintf(stdout, "</dd>\n");
237  }
238  if (opt->description) {
239  fprintf(stdout, "<dd>");
240  print_escaped_for_html(stdout, opt->description);
241  fprintf(stdout, "</dd>\n");
242  }
243 
244  if (opt->options) {
245  fprintf(stdout, "<dd>%s: <em>", _("Options"));
246  print_escaped_for_html_options(stdout, opt->options);
247  fprintf(stdout, "</em></dd>\n");
248  }
249 
250  if (opt->def) {
251  fprintf(stdout, "<dd>%s: <em>", _("Default"));
252  print_escaped_for_html(stdout, opt->def);
253  fprintf(stdout, "</em></dd>\n");
254  }
255 
256  if (opt->descs) {
257  int i = 0;
258 
259  while (opt->opts[i]) {
260  if (opt->descs[i]) {
261  fprintf(stdout, "<dd><b>");
262  if (opt->gisprompt) {
263  char *thumbnails = NULL;
264 
265  if (strcmp(opt->gisprompt,
266  "old,colortable,colortable") == 0)
267  thumbnails = "colortables";
268  else if (strcmp(opt->gisprompt,
269  "old,barscale,barscale") == 0)
270  thumbnails = "barscales";
271  else if (strcmp(opt->gisprompt,
272  "old,northarrow,northarrow") == 0)
273  thumbnails = "northarrows";
274 
275  if (thumbnails)
276  fprintf(stdout, "<img height=\"12\" "
277  "style=\"max-width: 80;\" "
278  "src=\"%s/%s.png\" alt=\"%s\"> ",
279  thumbnails, opt->opts[i], opt->opts[i]);
280  }
281  print_escaped_for_html(stdout, opt->opts[i]);
282  fprintf(stdout, "</b>: ");
283  print_escaped_for_html(stdout, opt->descs[i]);
284  fprintf(stdout, "</dd>\n");
285  }
286  i++;
287  }
288  }
289 
290  opt = opt->next_opt;
291  fprintf(stdout, "\n");
292  }
293  fprintf(stdout, "</dl>\n");
294  }
295  fprintf(stdout, "</div>\n");
296 
297  fprintf(stdout, "</body>\n</html>\n");
298 }
299 
300 
301 /*!
302  * \brief Format text for HTML output
303  */
304 #define do_escape(c,escaped) case c: fputs(escaped,f);break
305 void print_escaped_for_html(FILE * f, const char *str)
306 {
307  const char *s;
308 
309  for (s = str; *s; s++) {
310  switch (*s) {
311  do_escape('&', "&amp;");
312  do_escape('<', "&lt;");
313  do_escape('>', "&gt;");
314  do_escape('\n', "<br>");
315  do_escape('\t', "&nbsp;&nbsp;&nbsp;&nbsp;");
316  default:
317  fputc(*s, f);
318  }
319  }
320 }
321 
322 void print_escaped_for_html_options(FILE * f, const char *str)
323 {
324  const char *s;
325 
326  for (s = str; *s; s++) {
327  switch (*s) {
328  do_escape('&', "&amp;");
329  do_escape('<', "&lt;");
330  do_escape('>', "&gt;");
331  do_escape('\n', "<br>");
332  do_escape('\t', "&nbsp;&nbsp;&nbsp;&nbsp;");
333  do_escape(',', ", ");
334  default:
335  fputc(*s, f);
336  }
337  }
338 }
339 
340 void print_escaped_for_html_keywords(FILE * f, const char * str)
341 {
342  /* generate HTML links */
343 
344  /* HTML link only for second keyword */
345  if (st->n_keys > 1 &&
346  strcmp(st->module_info.keywords[1], str) == 0) {
347 
348  const char *s;
349 
350  /* TODO: fprintf(f, _("topic: ")); */
351  fprintf(f, "<a href=\"topic_");
352  for (s = str; *s; s++) {
353  switch (*s) {
354  do_escape(' ', "_");
355  default:
356  fputc(*s, f);
357  }
358  }
359  fprintf(f, ".html\">%s</a>", str);
360  }
361  else { /* first and other than second keyword */
362  if (st->n_keys > 0 &&
363  strcmp(st->module_info.keywords[0], str) == 0) {
364  /* command family */
365  const char *s;
366 
367  fprintf(f, "<a href=\"");
368  for (s = str; *s; s++) {
369  switch (*s) {
370  do_escape(' ', "_");
371  default:
372  fputc(*s, f);
373  }
374  }
375  fprintf(f, ".html\">%s</a>", str);
376  } else {
377  /* keyword index */
378  if (st->n_keys > 0 &&
379  strcmp(st->module_info.keywords[2], str) == 0) {
380 
381  /* TODO: fprintf(f, _("keywords: ")); */
382  fprintf(f, "<a href=\"keywords.html#%s\">%s</a>", str, str);
383  } else {
384  fprintf(f, "<a href=\"keywords.html#%s\">%s</a>", str, str);
385  }
386  }
387  }
388 }
389 #undef do_escape
G__uses_new_gisprompt
int G__uses_new_gisprompt(void)
Definition: parser.c:874
Option::opts
const char ** opts
Definition: gis.h:538
G_program_name
const char * G_program_name(void)
Return module name.
Definition: progrm_nme.c:28
G__usage_html
void G__usage_html(void)
Print module usage description in HTML format.
Definition: parser_html.c:29
TYPE_DOUBLE
#define TYPE_DOUBLE
Definition: gis.h:161
TYPE_STRING
#define TYPE_STRING
Definition: gis.h:162
NULL
#define NULL
Definition: ccmath.h:32
Option::def
const char * def
Definition: gis.h:545
Option::description
const char * description
Definition: gis.h:541
TYPE_INTEGER
#define TYPE_INTEGER
Definition: gis.h:160
Option::type
int type
Definition: gis.h:534
st
struct state * st
Definition: parser.c:104
Option::multiple
int multiple
Definition: gis.h:536
Flag
Structure that stores flag info.
Definition: gis.h:560
Flag::key
char key
Definition: gis.h:562
Option::required
int required
Definition: gis.h:535
Flag::next_flag
struct Flag * next_flag
Definition: gis.h:569
Flag::label
const char * label
Definition: gis.h:566
Option::label
const char * label
Definition: gis.h:540
Option::descs
const char ** descs
Definition: gis.h:543
Option
Structure that stores option information.
Definition: gis.h:531
_
#define _(str)
Definition: glocale.h:10
Flag::description
const char * description
Definition: gis.h:567
Option::key
const char * key
Definition: gis.h:533
Option::gisprompt
const char * gisprompt
Definition: gis.h:548
G__print_keywords
void G__print_keywords(FILE *fd, void(*format)(FILE *, const char *))
Print list of keywords (internal use only)
Definition: parser.c:910
Option::options
const char * options
Definition: gis.h:537
Option::key_desc
const char * key_desc
Definition: gis.h:539
do_escape
#define do_escape(c, escaped)
Format text for HTML output.
Definition: parser_html.c:304
Option::next_opt
struct Option * next_opt
Definition: gis.h:547