Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Config::Model::CookbooUserrContributed:PerleDo:Cookbook::CreateModelFromDoc(3)

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

VERSION
       version 2.105

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:

       o   Parameter names

       o   Documentation

       o   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:

       o   right-click on read_config

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

       o   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 at

	config-model-users at lists dot	sourceforge dot	net.

AUTHORS
       Dominique Dumont	<ddumont at cpan.org>

AUTHOR
       Dominique Dumont

COPYRIGHT AND LICENSE
       This software is	Copyright (c) 2005-2017	by Dominique Dumont.

       This is free software, licensed under:

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

perl v5.24.1			Config::Model::Cookbook::CreateModelFromDoc(3)

NAME | VERSION | Introduction | "Popcon" configuration file | "Popcon" documentation | Creating the YAML skeleton | Loading the YAML skeleton | Completing missing model parts | Specifying read and write backend | Testing the model | The resulting model | Feedback welcome | AUTHORS | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Config::Model::Cookbook::CreateModelFromDoc&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help