cfengine  3.15.4
About: CFEngine is a configuration management system for configuring and maintaining Unix-like computers (using an own high level policy language). Community version.
  Fossies Dox: cfengine-3.15.4.tar.gz  ("unofficial" and yet experimental doxygen-generated source code documentation)  

man.c
Go to the documentation of this file.
1 /*
2  Copyright 2020 Northern.tech AS
3 
4  This file is part of CFEngine 3 - written and maintained by Northern.tech AS.
5 
6  This program is free software; you can redistribute it and/or modify it
7  under the terms of the GNU General Public License as published by the
8  Free Software Foundation; version 3.
9 
10  This program is distributed in the hope that it will be useful,
11  but WITHOUT ANY WARRANTY; without even the implied warranty of
12  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13  GNU General Public License for more details.
14 
15  You should have received a copy of the GNU General Public License
16  along with this program; if not, write to the Free Software
17  Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
18 
19  To the extent this program is licensed as part of the Enterprise
20  versions of CFEngine, the applicable Commercial Open Source License
21  (COSL) may apply to this file if you as a licensee so wish it. See
22  included file COSL.txt.
23 */
24 
25 #include <man.h>
26 
27 #include <string_lib.h>
28 
29 #include <time.h>
30 
31 static void WriteCopyright(Writer *out)
32 {
33  static const char *const copyright =
34  ".\\\"Copyright 2020 Northern.tech AS\n"
35  ".\\\"\n"
36  ".\\\"This file is part of CFEngine 3 - written and maintained by Northern.tech AS.\n"
37  ".\\\"\n"
38  ".\\\"This program is free software; you can redistribute it and/or modify it\n"
39  ".\\\"under the terms of the GNU General Public License as published by the\n"
40  ".\\\"Free Software Foundation; version 3.\n"
41  ".\\\"\n"
42  ".\\\"This program is distributed in the hope that it will be useful,\n"
43  ".\\\"but WITHOUT ANY WARRANTY; without even the implied warranty of\n"
44  ".\\\"MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\n"
45  ".\\\"GNU General Public License for more details.\n"
46  ".\\\"\n"
47  ".\\\"You should have received a copy of the GNU General Public License\n"
48  ".\\\"along with this program; if not, write to the Free Software\n"
49  ".\\\"Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA\n"
50  ".\\\"\n"
51  ".\\\"To the extent this program is licensed as part of the Enterprise\n"
52  ".\\\"versions of CFEngine, the applicable Commercial Open Source License\n"
53  ".\\\"(COSL) may apply to this file if you as a licensee so wish it. See\n"
54  ".\\\"included file COSL.txt.\n";
55 
56  WriterWrite(out, copyright);
57 }
58 
59 static void WriteHeader(Writer *out, const char *program, time_t last_modified)
60 {
61  char program_upper[256] = { 0 };
62  snprintf(program_upper, 255, "%s", program);
63  ToUpperStrInplace(program_upper);
64 
65  char date_modified[20] = { 0 };
66  {
67  struct tm t;
68  gmtime_r(&last_modified, &t);
69  strftime(date_modified, 19, "%Y-%m-%d", &t);
70  }
71 
72  WriterWriteF(out, ".TH %s 8 \"%s\" \"CFEngine\" \"System Administration\"\n", program_upper, date_modified);
73 }
74 
75 static void WriteAvailability(Writer *out, const char *program)
76 {
77  static const char *const availability =
78  ".SH AVAILABILITY\n"
79  "%s is part of CFEngine.\n"
80  ".br\n"
81  "Binary packages may be downloaded from http://cfengine.com/downloads/.\n"
82  ".br\n"
83  "The source code is available at http://github.com/cfengine/\n";
84 
85  WriterWriteF(out, availability, program);
86 }
87 
88 static void WriteAuthor(Writer *out)
89 {
90  static const char *const author =
91  ".SH AUTHOR\n"
92  "Mark Burgess and Northern.tech AS\n";
93 
94  WriterWrite(out, author);
95 }
96 
97 static void WriteName(Writer *out, const char *program, const char *short_description)
98 {
99  static const char *const author =
100  ".SH NAME\n"
101  "%s \\- %s\n";
102 
103  WriterWriteF(out, author, program, short_description);
104 }
105 
106 static void WriteSynopsis(Writer *out, const char *program,
107  bool command, bool command_first,
108  bool accepts_file_argument)
109 {
110  WriterWrite(out, ".SH SYNOPSIS\n");
111  WriterWriteF(out, ".B %s\n", program);
112  if (command && command_first)
113  {
114  WriterWrite(out, ".RI COMMAND\n");
115  }
116  WriterWrite(out, ".RI [ OPTION ]...\n");
117  if (command && !command_first)
118  {
119  WriterWrite(out, ".RI COMMAND\n");
120  }
121  if (accepts_file_argument)
122  {
123  WriterWrite(out, ".RI [ FILE ]\n");
124  }
125  else
126  {
127  WriterWrite(out, "\n");
128  }
129 }
130 
131 static void WriteDescription(Writer *out, const char *description)
132 {
133  WriterWriteF(out, ".SH DESCRIPTION\n%s\n", description);
134 }
135 
136 static void WriteCommands(Writer *out, const Description *commands)
137 {
138  assert(commands != NULL);
139  WriterWrite(out, ".SH COMMANDS\n");
140 
141  for (int i = 0; commands[i].name != NULL; i++)
142  {
143  WriterWriteF(out, ".IP \"%s\"\n", commands[i].name);
144  WriterWriteF(out, "%s.\n", commands[i].description);
145  WriterWrite(out, ".br\n");
146  WriterWriteF(out, "Usage: %s\n", commands[i].usage);
147  }
148 }
149 
150 static void WriteOptions(Writer *out, const struct option options[],
151  const char *const option_hints[])
152 {
153  WriterWrite(out, ".SH OPTIONS\n");
154 
155  for (int i = 0; options[i].name != NULL; i++)
156  {
157  if (options[i].has_arg)
158  {
159  WriterWriteF(out, ".IP \"--%s, -%c value\"\n%s\n", options[i].name, (char) options[i].val, option_hints[i]);
160  }
161  else
162  {
163  WriterWriteF(out, ".IP \"--%s, -%c\"\n%s\n", options[i].name, (char) options[i].val, option_hints[i]);
164  }
165  }
166 }
167 
168 static void WriteSeeAlso(Writer *out)
169 {
170  static const char *const see_also =
171  ".SH \"SEE ALSO\"\n"
172  ".BR cf-promises (8),\n"
173  ".BR cf-agent (8),\n"
174  ".BR cf-serverd (8),\n"
175  ".BR cf-execd (8),\n"
176  ".BR cf-monitord (8),\n"
177  ".BR cf-runagent (8),\n"
178  ".BR cf-key (8)\n";
179 
180  WriterWrite(out, see_also);
181 }
182 
183 static void WriteBugs(Writer *out)
184 {
185  static const char *const bugs =
186  ".SH BUGS\n"
187  "Please see the public bug-tracker at http://bug.cfengine.com/.\n"
188  ".br\n"
189  "GitHub pull-requests may be submitted to http://github.com/cfengine/core/.\n";
190 
191  WriterWrite(out, bugs);
192 }
193 
194 static void WriteCFEngine(Writer *out)
195 {
196  static const char *const cfengine =
197  ".SH CFENGINE\n"
198  "CFEngine provides automated configuration management of large-scale computer systems. A system administrator "
199  "describes the desired state of a system using CFEngine policy code. The program \\fBcf-agent\\fR reads policy code "
200  "and attempts to bring the current system state to the desired state described. Policy code is downloaded by "
201  "\\fBcf-agent\\fR from a \\fBcf-serverd\\fR daemon. The daemon \\fBcf-execd\\fR is responsible for running "
202  "\\fBcf-agent\\fR periodically.\n"
203  ".br\n"
204  "Documentation for CFEngine is available at http://cfengine.com/documentation/.\n";
205 
206  WriterWrite(out, cfengine);
207 }
208 
209 static void WritePromiseTheory(Writer *out)
210 {
211  static const char *const promise_theory =
212  ".SH PROMISE THEORY\n"
213  "CFEngine is built on principles from promise theory, proposed by Mark Burgess in 2004. "
214  "Promise theory is a model of voluntary cooperation between individual, autonomous "
215  "actors or agents who publish their intentions to one another in the form of promises. "
216  "A promise is a declaration of intent whose purpose is to increase the recipient's certainty "
217  "about a claim of past, present or future behaviour. For a promise to increase certainty, "
218  "the recipient needs to trust the promiser, but trust can also be built on the verification "
219  "that previous promises have been kept, thus trust plays a symbiotic relationship with promises. \n"
220  ".br\n"
221  "For an introduction to promise theory, please see http://arxiv.org/abs/0810.3294/\n";
222 
223  WriterWrite(out, promise_theory);
224 }
225 
226 void ManPageWrite(Writer *out, const char *program, time_t last_modified,
227  const char *short_description, const char *long_description,
228  const struct option options[], const char *const option_hints[],
229  const Description *commands, bool command_first,
230  bool accepts_file_argument)
231 {
232  time_t overridetime;
233  char *source_date_epoch = getenv("SOURCE_DATE_EPOCH");
234  if (source_date_epoch != NULL &&
235  (overridetime = (time_t)strtoll(source_date_epoch, NULL, 10)) > 0)
236  {
237  last_modified = overridetime;
238  }
239  WriteCopyright(out);
240  WriteHeader(out, program, last_modified);
241  WriteName(out, program, short_description);
242  WriteSynopsis(out, program, (commands != NULL), command_first, accepts_file_argument);
243  WriteDescription(out, long_description);
244  if (commands != NULL)
245  {
246  WriteCommands(out, commands);
247  }
248  WriteOptions(out, options, option_hints);
249  WriteCFEngine(out);
250  WritePromiseTheory(out);
251  WriteAvailability(out, program);
252  WriteBugs(out);
253  WriteSeeAlso(out);
254  WriteAuthor(out);
255 }
void usage()
Definition: cf-upgrade.c:40
#define NULL
Definition: getopt1.c:56
char * getenv(char *name)
struct tm * gmtime_r(const time_t *timep, struct tm *result)
static void WriteCommands(Writer *out, const Description *commands)
Definition: man.c:136
static void WriteName(Writer *out, const char *program, const char *short_description)
Definition: man.c:97
static void WriteCopyright(Writer *out)
Definition: man.c:31
static void WriteHeader(Writer *out, const char *program, time_t last_modified)
Definition: man.c:59
static void WriteSeeAlso(Writer *out)
Definition: man.c:168
void ManPageWrite(Writer *out, const char *program, time_t last_modified, const char *short_description, const char *long_description, const struct option options[], const char *const option_hints[], const Description *commands, bool command_first, bool accepts_file_argument)
Definition: man.c:226
static void WriteOptions(Writer *out, const struct option options[], const char *const option_hints[])
Definition: man.c:150
static void WriteCFEngine(Writer *out)
Definition: man.c:194
static void WriteSynopsis(Writer *out, const char *program, bool command, bool command_first, bool accepts_file_argument)
Definition: man.c:106
static void WritePromiseTheory(Writer *out)
Definition: man.c:209
static void WriteBugs(Writer *out)
Definition: man.c:183
static void WriteAvailability(Writer *out, const char *program)
Definition: man.c:75
static void WriteDescription(Writer *out, const char *description)
Definition: man.c:131
static void WriteAuthor(Writer *out)
Definition: man.c:88
void ToUpperStrInplace(char *str)
Definition: string_lib.c:152
const char * name
Definition: writer.h:69
Definition: writer.c:45
Definition: getopt.h:83
char * name
Definition: getopt.h:87
size_t WriterWrite(Writer *writer, const char *str)
Definition: writer.c:193
size_t WriterWriteF(Writer *writer, const char *fmt,...)
Definition: writer.c:144