1Config::Model::CookbookU:s:eCrreCaotnetMroiCdboeunltfFeirdgo:mP:DeMorocld(e3Dl)o:c:uCmoeonktbaotoiko:n:CreateModelFromDoc(3)
2
3
4

NAME

6       Config::Model::Cookbook::CreateModelFromDoc - Create a configuration
7       model from application documentation
8

VERSION

10       version 2.152
11

Introduction

13       This page shows step by step how was created "Popcon"'s model from
14       "Popcon" documentation provided as comments in "Popcon"'s sample
15       configuration file.
16

"Popcon" configuration file

18       A quick looks in "/etc" directory shows that "Popcon"'s configuration
19       is stored in "/etc/popularity-contest.conf</t":
20
21        # Config file for Debian's popularity-contest package.
22        #
23        # To change this file, use:
24        #        dpkg-reconfigure popularity-contest
25        #
26        # You can also edit it by hand, if you so choose.
27        #
28        # See /usr/share/popularity-contest/default.conf for more info
29        # on the options.
30
31        MY_HOSTID="172921501FFFFFAAAA6897etc"
32        PARTICIPATE="yes"
33        USEHTTP="yes"
34        DAY="5"
35
36       The important part is the mention of "default.conf" which contains all
37       the required information to create "Popcon"'s configuration model.
38

"Popcon" documentation

40       Let's start from "default.conf" file. Since this file is loaded by
41       "popcon" before loading "/etc/popularity-contest.conf</t", all values
42       there can be used as application default values (aka upstream_default):
43
44        # Default config file for Debian's popularity-contest package.
45        #
46        # Local overrides are in /etc/popularity-contest.conf
47
48        # PARTICIPATE can be one of "yes" or "no".
49        # If you don't want to participate in the contest, say "no"
50        # and we won't send messages.
51        #
52        # If this option is missing, the default is "no".
53        #
54        PARTICIPATE="no"
55
56        # MAILTO specifies the address to e-mail statistics to each week.
57        #
58        MAILTO="survey@popcon.debian.org"
59
60        # MAILFROM is the forged sender email address you want to use in
61        # email submitted to the popularity-contest.  If this is commented
62        # out, no From: or Sender: lines will be added to the outgoing mail,
63        # and it will be your MTA's job to add them.  This is usually what
64        # you want.
65        #
66        # If your MTA is misconfigured or impossible to configure correctly,
67        # and it always generates invalid From: and/or Sender: lines, you
68        # can force different results by setting MAILFROM here.  This can
69        # cause problems with spam bouncers, so most people should leave it
70        # commented out.
71        #
72        #MAILFROM="root@example.org"
73
74        # SUBMITURLS is a space separated list of where to submit
75        # popularity-contest reports using http.
76        SUBMITURLS="http://popcon.debian.org/cgi-bin/popcon.cgi"
77
78        # USEHTTP enables http reporting.   Set this to 'yes' to enable it.
79        USEHTTP="yes"
80
81        # HTTP_PROXY allows one to specify an HTTP proxy server, the syntax is
82        # HTTP_PROXY="http://proxy:port". This overrides the environment
83        # variable http_proxy.
84
85        # MY_HOSTID is a secret number that the popularity-contest receiver
86        # uses to keep track of your submissions.  Whenever you send in a
87        # new entry, it overwrites the last one that had the same HOSTID.
88        #
89        # This key was generated automatically so you should normally just
90        # leave it alone.
91        #
92        #MY_HOSTID="_ID_"
93
94       This file contains everything we need:
95
96       •   Parameter names
97
98       •   Documentation
99
100       •   Default values
101
102       Now, we will use our favorite editor to edit this file and add YAML
103       tags that can be understood by "cme meta edit"
104

Creating the YAML skeleton

106       "cme meta edit" is able to load a model described in YAML. To do this
107       the above file needs to be translated in YAML. That's not as
108       complicated as it may sound.
109
110       First, a YAML file must begin with ---. Then the class must be
111       declared:
112
113        ---
114        class:
115          PopCon:
116
117       Note that, like with Python language, the indentation is important to
118       define the structure of the file. Here, the "PopCon" class is followed
119       by a ':' as it defines a new hierarchical level to describes the
120       configuration elements of this class:
121
122            element:
123
124       Now we can deal with the configuration parameters. Let's detail the
125       "PARTICIPATE" element. Here's the spec in from "default.conf":
126
127        # PARTICIPATE can be one of "yes" or "no".
128        # If you don't want to participate in the contest, say "no"
129        # and we won't send messages.
130        #
131        # If this option is missing, the default is "no".
132        #
133        PARTICIPATE="no"
134
135       In the YAML file, the comments are moved in the "description" field and
136       the value in the file is used as upstream default:
137
138             PARTICIPATE:
139               upstream_default: no
140               description: >
141                If you don't want to participate in the contest,
142                say "no" and we won't send messages.
143
144       Likewise for the remaining parameters:
145
146             MAILTO:
147               description: >
148                specifies the address to e-mail statistics to each week.
149               default: 'survey@popcon.debian.org'
150             MAILFROM:
151               description: >-
152                MAILFROM is the forged sender email address you want to use
153                in email submitted to the popularity-contest.  If this is
154                commented out, no From: or Sender: lines will be added to the
155                outgoing mail, and it will be your MTA's job to add them.  This
156                is usually what you want.
157
158
159                If your MTA is misconfigured or
160                impossible to configure correctly, and it always generates
161                invalid From: and/or Sender: lines, you can force different
162                results by setting MAILFROM here.  This can cause problems with
163                spam bouncers, so most people should leave it commented out.
164
165       In the description above, the "chimping" marker '-' after '>' is used
166       to keep paragraph formatting in the help.
167
168             SUBMITURLS:
169               description: >
170                Space separated list of where to submit popularity-contest
171                reports using http.
172               default: >
173                http://popcon.debian.org/cgi-bin/popcon.cgi
174
175             USEHTTP:
176               description: >
177                enables http reporting.   Set this to 'yes' to enable it.
178               default: "yes"
179
180             HTTP_PROXY:
181               description: >
182                allows one to specify an HTTP proxy server, the syntax is
183                "http://proxy:port". This overrides the environment variable
184                http_proxy.
185
186             MY_HOSTID:
187               description: >-
188                secret number that the popularity-contest receiver uses to
189                keep track of your submissions.  Whenever you send in a new
190                entry, it overwrites the last one that had the same HOSTID.
191
192                This key was generated automatically so you should normally
193                just leave it alone.
194

Loading the YAML skeleton

196       Now that the YAML file was created, you can turn it into a model and
197       load it in the model editor GUI with the following command:
198
199        cme meta edit popcon -load-yaml popcon.yml -force
200
201       Note that the model is incomplete: some mandatory parameters are
202       missing from the YAML file so the -force option must be used. These
203       missing parameters are also flagged with a red cross in the GUI.
204

Completing missing model parts

206       To complete the model, the easiest way is to run the wizard to complete
207       the missing values. In the GUI, you can use the menu "File -> wizard"
208       to launch the wizard.  Then click on the 'OK' button in the new window.
209
210       The wizard will first stop on the parameter list (not because there's
211       an error, but because the parameter list is flagged as important)
212
213       There, you can re-order the parameters by selecting one and clicking on
214       one of the blue arrows to move it up or down. Once you're satisfied,
215       click on Next.
216
217       The widget will now stop on the first missing information. Just select
218       the correct type ('leaf' here), click 'store' and 'Next'.
219
220       You can repeat these steps until the wizard exits.
221

Specifying read and write backend

223       Once the model is complete, it's time to specify how to read and write
224       the file. In "Popcon" class specification:
225
226       •   right-click on read_config
227
228       •   click on push new node to create a new read specification
229
230       •   right-click on the created item (shown at index "0")
231
232       You will get a window showing you the parameters to fill to specify the
233       read backend.
234
235       Now fill the blank on the right side. The backend to use is "ShellVar"
236       since popularity-contest.conf is made of shell variables.
237
238       Since the write specification is identical, there's no need to specify
239       it. Config::Model will do the right thing.
240

Testing the model

242       You can test the model by clicking on menu "Test -> Model". You will be
243       shown the "Popcon" configuration editor GUI. The same that your users
244       will get.
245
246       If everything is fine, you can quit the model editor (menu File->quit)
247

The resulting model

249       The model you have just created is stored in
250       "lib/Config/Model/models/Popcon.pl".
251
252       You can test directly this model with :
253
254         cme edit -dev -try Popcon
255

Feedback welcome

257       Feel free to send comments and suggestion about this page to the
258       author.
259

AUTHORS

261       Dominique Dumont <ddumont at cpan.org>
262

AUTHOR

264       Dominique Dumont
265
267       This software is Copyright (c) 2005-2022 by Dominique Dumont.
268
269       This is free software, licensed under:
270
271         The GNU Lesser General Public License, Version 2.1, February 1999
272
273
274
275perl v5.36.0                    Co2n0f2i3g-:0:1M-o2d0el::Cookbook::CreateModelFromDoc(3)
Impressum