/usr/share/perl5/Config/Model/Cookbook/CreateModelFromDoc.pod is in libconfig-model-perl 2.097-2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 | # PODNAME: Config::Model::Cookbook::CreateModelFromDoc
# ABSTRACT: Create a configuration model from application documentation
__END__
=pod
=encoding UTF-8
=head1 NAME
Config::Model::Cookbook::CreateModelFromDoc - Create a configuration model from application documentation
=head1 VERSION
version 2.097
=head1 Introduction
This page shows step by step how was created C<Popcon>'s model from
C<Popcon> documentation provided as comments in C<Popcon>'s sample
configuration file.
=head1 C<Popcon> configuration file
A quick looks in C</etc> directory shows that C<Popcon>'s configuration
is stored in C</etc/popularity-contest.conf</t>:
# Config file for Debian's popularity-contest package.
#
# To change this file, use:
# dpkg-reconfigure popularity-contest
#
# You can also edit it by hand, if you so choose.
#
# See /usr/share/popularity-contest/default.conf for more info
# on the options.
MY_HOSTID="172921501FFFFFAAAA6897etc"
PARTICIPATE="yes"
USEHTTP="yes"
DAY="5"
The important part is the mention of C<default.conf> which contains
all the required information to create C<Popcon>'s configuration model.
=head1 C<Popcon> documentation
Let's start from C<default.conf> file. Since this file is loaded
by C<popcon> I<before> loading C</etc/popularity-contest.conf</t>,
all values there can be used as application default values (aka
I<upstream_default>):
# Default config file for Debian's popularity-contest package.
#
# Local overrides are in /etc/popularity-contest.conf
# PARTICIPATE can be one of "yes" or "no".
# If you don't want to participate in the contest, say "no"
# and we won't send messages.
#
# If this option is missing, the default is "no".
#
PARTICIPATE="no"
# MAILTO specifies the address to e-mail statistics to each week.
#
MAILTO="survey@popcon.debian.org"
# MAILFROM is the forged sender email address you want to use in
# email submitted to the popularity-contest. If this is commented
# out, no From: or Sender: lines will be added to the outgoing mail,
# and it will be your MTA's job to add them. This is usually what
# you want.
#
# If your MTA is misconfigured or impossible to configure correctly,
# and it always generates invalid From: and/or Sender: lines, you
# can force different results by setting MAILFROM here. This can
# cause problems with spam bouncers, so most people should leave it
# commented out.
#
#MAILFROM="root@example.org"
# SUBMITURLS is a space separated list of where to submit
# popularity-contest reports using http.
SUBMITURLS="http://popcon.debian.org/cgi-bin/popcon.cgi"
# USEHTTP enables http reporting. Set this to 'yes' to enable it.
USEHTTP="yes"
# HTTP_PROXY allows one to specify an HTTP proxy server, the syntax is
# HTTP_PROXY="http://proxy:port". This overrides the environment
# variable http_proxy.
# MY_HOSTID is a secret number that the popularity-contest receiver
# uses to keep track of your submissions. Whenever you send in a
# new entry, it overwrites the last one that had the same HOSTID.
#
# This key was generated automatically so you should normally just
# leave it alone.
#
#MY_HOSTID="_ID_"
This file contains everything we need:
=over
=item *
Parameter names
=item *
Documentation
=item *
Default values
=back
Now, we will use our favorite editor to edit this file and add YAML
tags that can be understood by C<cme meta edit>
=head1 Creating the YAML skeleton
C<cme meta edit> is able to load a model described in
YAML. To do this the above file needs to be translated in YAML. That's
not as complicated as it may sound.
First, a YAML file must begin with B<--->. Then the class must be declared:
---
class:
PopCon:
Note that, like with Python language, the indentation is important to
define the structure of the file. Here, the C<PopCon> class is followed by
a ':' as it defines a new hierarchical level to describes the
configuration elements of this class:
element:
Now we can deal with the configuration parameters. Let's detail the
C<PARTICIPATE> element. Here's the spec in from C<default.conf>:
# PARTICIPATE can be one of "yes" or "no".
# If you don't want to participate in the contest, say "no"
# and we won't send messages.
#
# If this option is missing, the default is "no".
#
PARTICIPATE="no"
In the YAML file, the comments are moved in the C<description> field and
the value in the file is used as upstream default:
PARTICIPATE:
upstream_default: no
description: >
If you don't want to participate in the contest,
say "no" and we won't send messages.
Likewise for the remaining parameters:
MAILTO:
description: >
specifies the address to e-mail statistics to each week.
default: 'survey@popcon.debian.org'
MAILFROM:
description: >-
MAILFROM is the forged sender email address you want to use
in email submitted to the popularity-contest. If this is
commented out, no From: or Sender: lines will be added to the
outgoing mail, and it will be your MTA's job to add them. This
is usually what you want.
If your MTA is misconfigured or
impossible to configure correctly, and it always generates
invalid From: and/or Sender: lines, you can force different
results by setting MAILFROM here. This can cause problems with
spam bouncers, so most people should leave it commented out.
In the description above, the C<chimping> marker '-' after '>' is used to
keep paragraph formatting in the help.
SUBMITURLS:
description: >
Space separated list of where to submit popularity-contest
reports using http.
default: >
http://popcon.debian.org/cgi-bin/popcon.cgi
USEHTTP:
description: >
enables http reporting. Set this to 'yes' to enable it.
default: "yes"
HTTP_PROXY:
description: >
allows one to specify an HTTP proxy server, the syntax is
"http://proxy:port". This overrides the environment variable
http_proxy.
MY_HOSTID:
description: >-
secret number that the popularity-contest receiver uses to
keep track of your submissions. Whenever you send in a new
entry, it overwrites the last one that had the same HOSTID.
This key was generated automatically so you should normally
just leave it alone.
=head1 Loading the YAML skeleton
Now that the YAML file was created, you can turn it into a model and
load it in the model editor GUI with the following command:
cme meta edit popcon -load-yaml popcon.yml -force
Note that the model is incomplete: some mandatory parameters are
missing from the YAML file so the I<-force> option must be used. These
missing parameters are also flagged with a red cross in the GUI.
=head1 Completing missing model parts
To complete the model, the easiest way is to run the wizard to
complete the missing values. In the GUI, you can use the menu
C<< File -> wizard >> to launch the wizard.
Then click on the 'OK' button in
the new window.
The wizard will first stop on the parameter list (not because there's
an error, but because the parameter list is flagged as I<important>)
There, you can re-order the parameters by selecting one and clicking
on one of the blue arrows to move it up or down. Once you're
satisfied, click on I<Next>.
The widget will now stop on the first missing information. Just select
the correct type ('leaf' here), click 'store' and 'Next'.
You can repeat these steps until the wizard exits.
=head1 Specifying read and write backend
Once the model is complete, it's time to specify how to read and write the file. In
C<Popcon> class specification:
=over
=item *
right-click on I<read_config>
=item *
click on I<push new node> to create a new read specification
=item *
right-click on the created item (shown at index "I<0>")
=back
You will get a window showing you the parameters to fill to specify
the read backend.
Now fill the blank on the right side. The backend to use is
C<ShellVar> since I<popularity-contest.conf> is made of shell
variables.
Since the write specification is identical, there's no need to specify
it. L<Config::Model> will do the right thing.
=head1 Testing the model
You can test the model by clicking on menu C<< Test -> Model >>. You
will be shown the C<Popcon> configuration editor GUI. The same that your
users will get.
If everything is fine, you can quit the model editor (menu File->quit)
=head1 The resulting model
The model you have just created is stored in C<lib/Config/Model/models/Popcon.pl>.
You can test directly this model with :
cme edit -dev -try Popcon
=head1 Feedback welcome
Feel free to send comments and suggestion about this page at
config-model-users at lists dot sourceforge dot net.
=head1 AUTHORS
Dominique Dumont <ddumont at cpan.org>
=head1 AUTHOR
Dominique Dumont
=head1 COPYRIGHT AND LICENSE
This software is Copyright (c) 2005-2016 by Dominique Dumont.
This is free software, licensed under:
The GNU Lesser General Public License, Version 2.1, February 1999
=cut
|