Provided by: libconfig-model-perl_2.152-1_all bug

NAME

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

VERSION

       version 2.152

Introduction

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

"Popcon" configuration file

       A quick looks in "/etc" directory shows that "Popcon"'s configuration is stored in
       "/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 "default.conf" which contains all the required
       information to create "Popcon"'s configuration model.

"Popcon" documentation

       Let's start from "default.conf" file. Since this file is loaded by "popcon" before loading
       "/etc/popularity-contest.conf</t", all values there can be used as application default
       values (aka 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:

       •   Parameter names

       •   Documentation

       •   Default values

       Now, we will use our favorite editor to edit this file and add YAML tags that can be
       understood by "cme meta edit"

Creating the YAML skeleton

       "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 ---. 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 "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 "PARTICIPATE" element.
       Here's the spec in from "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 "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 "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.

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 -force option must be used. These missing parameters are also flagged with a
       red cross in the GUI.

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 "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 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 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.

Specifying read and write backend

       Once the model is complete, it's time to specify how to read and write the file. In
       "Popcon" class specification:

       •   right-click on read_config

       •   click on push new node to create a new read specification

       •   right-click on the created item (shown at index "0")

       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 "ShellVar" since
       popularity-contest.conf is made of shell variables.

       Since the write specification is identical, there's no need to specify it. Config::Model
       will do the right thing.

Testing the model

       You can test the model by clicking on menu "Test -> Model". You will be shown the "Popcon"
       configuration editor GUI. The same that your users will get.

       If everything is fine, you can quit the model editor (menu File->quit)

The resulting model

       The model you have just created is stored in "lib/Config/Model/models/Popcon.pl".

       You can test directly this model with :

         cme edit -dev -try Popcon

Feedback welcome

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

AUTHORS

       Dominique Dumont <ddumont at cpan.org>

AUTHOR

       Dominique Dumont

COPYRIGHT AND LICENSE

       This software is Copyright (c) 2005-2022 by Dominique Dumont.

       This is free software, licensed under:

         The GNU Lesser General Public License, Version 2.1, February 1999

perl v5.34.0                                2022-Config::Model::Cookbook::CreateModelFromDoc(3pm)