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