.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Config::Model::Cookbook::CreateModelFromDoc 3pm"
.TH Config::Model::Cookbook::CreateModelFromDoc 3pm "2021-01-20" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Config::Model::Cookbook::CreateModelFromDoc \- Create a configuration model from application documentation
.SH "VERSION"
.IX Header "VERSION"
version 2.141
.SH "Introduction"
.IX Header "Introduction"
This page shows step by step how was created \f(CW\*(C`Popcon\*(C'\fR's model from
\&\f(CW\*(C`Popcon\*(C'\fR documentation provided as comments in \f(CW\*(C`Popcon\*(C'\fR's sample
configuration file.
.ie n .SH """Popcon"" configuration file"
.el .SH "\f(CWPopcon\fP configuration file"
.IX Header "Popcon configuration file"
A quick looks in \f(CW\*(C`/etc\*(C'\fR directory shows that \f(CW\*(C`Popcon\*(C'\fR's configuration
is stored in \f(CW\*(C`/etc/popularity\-contest.conf</t\*(C'\fR:
.PP
.Vb 9
\& # Config file for Debian\*(Aqs 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"
.Ve
.PP
The important part is the mention of \f(CW\*(C`default.conf\*(C'\fR which contains
all the required information to create \f(CW\*(C`Popcon\*(C'\fR's configuration model.
.ie n .SH """Popcon"" documentation"
.el .SH "\f(CWPopcon\fP documentation"
.IX Header "Popcon documentation"
Let's start from \f(CW\*(C`default.conf\*(C'\fR file. Since this file is loaded
by \f(CW\*(C`popcon\*(C'\fR \fIbefore\fR loading \f(CW\*(C`/etc/popularity\-contest.conf</t\*(C'\fR,
all values there can be used as application default values (aka
\&\fIupstream_default\fR):
.PP
.Vb 3
\& # Default config file for Debian\*(Aqs popularity\-contest package.
\& #
\& # Local overrides are in /etc/popularity\-contest.conf
\& 
\& # PARTICIPATE can be one of "yes" or "no".
\& # If you don\*(Aqt want to participate in the contest, say "no"
\& # and we won\*(Aqt 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\*(Aqs 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 \*(Aqyes\*(Aq 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_"
.Ve
.PP
This file contains everything we need:
.IP "\(bu" 4
Parameter names
.IP "\(bu" 4
Documentation
.IP "\(bu" 4
Default values
.PP
Now, we will use our favorite editor to edit this file and add \s-1YAML\s0
tags that can be understood by \f(CW\*(C`cme meta edit\*(C'\fR
.SH "Creating the YAML skeleton"
.IX Header "Creating the YAML skeleton"
\&\f(CW\*(C`cme meta edit\*(C'\fR is able to load a model described in
\&\s-1YAML.\s0 To do this the above file needs to be translated in \s-1YAML.\s0 That's
not as complicated as it may sound.
.PP
First, a \s-1YAML\s0 file must begin with \fB\-\-\-\fR. Then the class must be declared:
.PP
.Vb 3
\& \-\-\-
\& class:
\&   PopCon:
.Ve
.PP
Note that, like with Python language, the indentation is important to
define the structure of the file. Here, the \f(CW\*(C`PopCon\*(C'\fR class is followed by
a ':' as it defines a new hierarchical level to describes the
configuration elements of this class:
.PP
.Vb 1
\&     element:
.Ve
.PP
Now we can deal with the configuration parameters. Let's detail the
\&\f(CW\*(C`PARTICIPATE\*(C'\fR element. Here's the spec in from \f(CW\*(C`default.conf\*(C'\fR:
.PP
.Vb 7
\& # PARTICIPATE can be one of "yes" or "no".
\& # If you don\*(Aqt want to participate in the contest, say "no"
\& # and we won\*(Aqt send messages.
\& #
\& # If this option is missing, the default is "no".
\& #
\& PARTICIPATE="no"
.Ve
.PP
In the \s-1YAML\s0 file, the comments are moved in the \f(CW\*(C`description\*(C'\fR field and
the value in the file is used as upstream default:
.PP
.Vb 5
\&      PARTICIPATE:
\&        upstream_default: no
\&        description: >
\&         If you don\*(Aqt want to participate in the contest, 
\&         say "no" and we won\*(Aqt send messages.
.Ve
.PP
Likewise for the remaining parameters:
.PP
.Vb 11
\&      MAILTO:
\&        description: >
\&         specifies the address to e\-mail statistics to each week.
\&        default: \*(Aqsurvey@popcon.debian.org\*(Aq
\&      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\*(Aqs 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.
.Ve
.PP
In the description above, the \f(CW\*(C`chimping\*(C'\fR marker '\-' after '>' is used to
keep paragraph formatting in the help.
.PP
.Vb 6
\&      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 \*(Aqyes\*(Aq 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.
.Ve
.SH "Loading the YAML skeleton"
.IX Header "Loading the YAML skeleton"
Now that the \s-1YAML\s0 file was created, you can turn it into a model and
load it in the model editor \s-1GUI\s0 with the following command:
.PP
.Vb 1
\& cme meta edit popcon \-load\-yaml popcon.yml \-force
.Ve
.PP
Note that the model is incomplete: some mandatory parameters are
missing from the \s-1YAML\s0 file so the \fI\-force\fR option must be used. These
missing parameters are also flagged with a red cross in the \s-1GUI.\s0
.SH "Completing missing model parts"
.IX Header "Completing missing model parts"
To complete the model, the easiest way is to run the wizard to
complete the missing values. In the \s-1GUI,\s0 you can use the menu
\&\f(CW\*(C`File \-> wizard\*(C'\fR to launch the wizard. 
Then click on the '\s-1OK\s0' button in
the new window.
.PP
The wizard will first stop on the parameter list (not because there's
an error, but because the parameter list is flagged as \fIimportant\fR)
.PP
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 \fINext\fR.
.PP
The widget will now stop on the first missing information. Just select
the correct type ('leaf' here), click 'store' and 'Next'.
.PP
You can repeat these steps until the wizard exits.
.SH "Specifying read and write backend"
.IX Header "Specifying read and write backend"
Once the model is complete, it's time to specify how to read and write the file. In
\&\f(CW\*(C`Popcon\*(C'\fR class specification:
.IP "\(bu" 4
right-click on \fIread_config\fR
.IP "\(bu" 4
click on \fIpush new node\fR to create a new read specification
.IP "\(bu" 4
right-click on the created item (shown at index "\fI0\fR")
.PP
You will get a window showing you the parameters to fill to specify
the read backend.
.PP
Now fill the blank on the right side. The backend to use is
\&\f(CW\*(C`ShellVar\*(C'\fR since \fIpopularity\-contest.conf\fR is made of shell
variables.
.PP
Since the write specification is identical, there's no need to specify
it. Config::Model will do the right thing.
.SH "Testing the model"
.IX Header "Testing the model"
You can test the model by clicking on menu \f(CW\*(C`Test \-> Model\*(C'\fR. You
will be shown the \f(CW\*(C`Popcon\*(C'\fR configuration editor \s-1GUI.\s0 The same that your
users will get.
.PP
If everything is fine, you can quit the model editor (menu File\->quit)
.SH "The resulting model"
.IX Header "The resulting model"
The model you have just created is stored in \f(CW\*(C`lib/Config/Model/models/Popcon.pl\*(C'\fR.
.PP
You can test directly this model with :
.PP
.Vb 1
\&  cme edit \-dev \-try Popcon
.Ve
.SH "Feedback welcome"
.IX Header "Feedback welcome"
Feel free to send comments and suggestion about this page to the author.
.SH "AUTHORS"
.IX Header "AUTHORS"
Dominique Dumont <ddumont at cpan.org>
.SH "AUTHOR"
.IX Header "AUTHOR"
Dominique Dumont
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is Copyright (c) 2005\-2021 by Dominique Dumont.
.PP
This is free software, licensed under:
.PP
.Vb 1
\&  The GNU Lesser General Public License, Version 2.1, February 1999
.Ve