As you probably noticed in latest foreman installer, there are a lot of
options to set. I'd like to introduce a mechanism to separate less used params
so users won't be bothered by them in main menus. They'd be still able to set
them using more nested menu. If it was be possible I'd like to limit also –
help output accordingly.
I'd like to split params into group based on RDOC documentation in puppet
modules. Since puppet parsing part will be extracted and will be reusable
elsewhere I'd like to bring the discussion about the documentation format to a
broader audience.
My proposal is to use RDOC blocks (I did some tests and it seems to work) so
the format would look like this http://pastebin.com/QB2ciMkf
We would parse all headers level 3 which containing keyword "parameters" (case
insensitive). If there's nothing else, we assume it's "basic". If there's some
prefix we add a new params group by this name and assign a param to this group.
If no group was found when we hit first parameter we'd assign it to "basic". In
linked example we'd have 3 groups - "basic", "advanced", "extra".
Interactive installer would generate menu dynamically, basic on first level of
nesting, all other groups on second (you could get there menu of basic group).
What do you think (related to format and parsing)? Is RDOC block level
requirement too strict? Any other idea how to indicate param group? Do you find
it useful to have volatile number of groups and group names?
> Hi all
>
> As you probably noticed in latest foreman installer, there are a lot of
> options to set. I'd like to introduce a mechanism to separate less used
> params
> so users won't be bothered by them in main menus. They'd be still able to
> set
> them using more nested menu. If it was be possible I'd like to limit also
> –
> help output accordingly.
>
> I'd like to split params into group based on RDOC documentation in puppet
> modules. Since puppet parsing part will be extracted and will be reusable
> elsewhere I'd like to bring the discussion about the documentation format
> to a
> broader audience.
>
> My proposal is to use RDOC blocks (I did some tests and it seems to work)
> so
> the format would look like this http://pastebin.com/QB2ciMkf
>
> We would parse all headers level 3 which containing keyword "parameters"
> (case
> insensitive). If there's nothing else, we assume it's "basic". If there's
> some
> prefix we add a new params group by this name and assign a param to this
> group.
> If no group was found when we hit first parameter we'd assign it to
> "basic". In
> linked example we'd have 3 groups - "basic", "advanced", "extra".
>
> Interactive installer would generate menu dynamically, basic on first
> level of
> nesting, all other groups on second (you could get there menu of basic
> group).
>
> What do you think (related to format and parsing)? Is RDOC block level
> requirement too strict? Any other idea how to indicate param group? Do you
> find
> it useful to have volatile number of groups and group names?
>
> Thanks for any feedback
>
>
Would we be able to introduce some sort of context? e.g, assuming you
selected db type MySQL, you only see certain other options (e.g. cant see
the pg / sqlite adapter type)
This might be a much wider discussion, as it applies to foreman as well,
but i do see it related.
Ohad
···
On Mon, Oct 14, 2013 at 10:56 AM, Marek Hulan wrote:
>
> > Hi all
> >
> > As you probably noticed in latest foreman installer, there are a lot of
> > options to set. I'd like to introduce a mechanism to separate less used
> > params
> > so users won't be bothered by them in main menus. They'd be still able to
> > set
> > them using more nested menu. If it was be possible I'd like to limit also
> > –
> > help output accordingly.
> >
> > I'd like to split params into group based on RDOC documentation in puppet
> > modules. Since puppet parsing part will be extracted and will be reusable
> > elsewhere I'd like to bring the discussion about the documentation format
> > to a
> > broader audience.
> >
> > My proposal is to use RDOC blocks (I did some tests and it seems to work)
> > so
> > the format would look like this http://pastebin.com/QB2ciMkf
> >
> > We would parse all headers level 3 which containing keyword "parameters"
> > (case
> > insensitive). If there's nothing else, we assume it's "basic". If there's
> > some
> > prefix we add a new params group by this name and assign a param to this
> > group.
> > If no group was found when we hit first parameter we'd assign it to
> > "basic". In
> > linked example we'd have 3 groups - "basic", "advanced", "extra".
> >
> > Interactive installer would generate menu dynamically, basic on first
> > level of
> > nesting, all other groups on second (you could get there menu of basic
> > group).
> >
> > What do you think (related to format and parsing)? Is RDOC block level
> > requirement too strict? Any other idea how to indicate param group? Do you
> > find
> > it useful to have volatile number of groups and group names?
> >
> > Thanks for any feedback
> >
> >
> Would we be able to introduce some sort of context? e.g, assuming you
> selected db type MySQL, you only see certain other options (e.g. cant see
> the pg / sqlite adapter type)
>
> This might be a much wider discussion, as it applies to foreman as well,
> but i do see it related.
It would be really great to be able to address these two things together.
– Ivan
···
----- Original Message -----
> On Mon, Oct 14, 2013 at 10:56 AM, Marek Hulan wrote:
> > Would we be able to introduce some sort of context? e.g, assuming you
> > selected db type MySQL, you only see certain other options (e.g. cant see
> > the pg / sqlite adapter type)
> >
> > This might be a much wider discussion, as it applies to foreman as well,
> > but i do see it related.
>
> It would be really great to be able to address these two things together.
>
Ok so after short discussion with Ivan we got some idea of how it could work.
We'd not limit grouping block by level so "Advanced parameters:" block could
be any level. Only blocks containing word "parameters" would be used for
grouping.
We would also enable specifying display conditions. Condition would be
evaluated in order to display/hide a parameter. You could set condition to a
whole block like this
==== MySQL: $db_type == 'mysql'
$mysql_user:: User of MySQL
or you could set a condition at a parameter itself
=== Advanced parameters:
#$mysql_user:: User of MySQL
display: $db_type == 'mysql'
If you specify condition at block and parameter at the same time they will be
joined using &&. The same will apply on nested blocks.
We wouldn't introduce new DSL. The language of expression would be Ruby.
Before evaluation $variables would be substituted by real values. We don't
want to use Puppet DSL since this could be later used in Foreman and we don't
want to put Puppet dependency to Foreman again. Also with Ruby users could
write more complicated expressions if needed.
The syntax can make documentation less readable but note that it's something
completely optional.
> > > Would we be able to introduce some sort of context? e.g, assuming you
> > > selected db type MySQL, you only see certain other options (e.g. cant
> see
> > > the pg / sqlite adapter type)
> > >
> > > This might be a much wider discussion, as it applies to foreman as
> well,
> > > but i do see it related.
> >
> > It would be really great to be able to address these two things together.
> >
>
> Ok so after short discussion with Ivan we got some idea of how it could
> work.
> We'd not limit grouping block by level so "Advanced parameters:" block
> could
> be any level. Only blocks containing word "parameters" would be used for
> grouping.
>
Sounds promising - I do think we have too many parameters in the default
output
today, and handling it within the RDoc sounds excellent.
> We would also enable specifying display conditions. Condition would be
> evaluated in order to display/hide a parameter. You could set condition to
> a
> whole block like this
>
> # ==== MySQL: $db_type == 'mysql'
> # $mysql_user:: User of MySQL
>
> or you could set a condition at a parameter itself
>
> # === Advanced parameters:
> #$mysql_user:: User of MySQL
> # display: $db_type == 'mysql'
>
How does that work on the cmdline, using --help? Nothing will be set yet,
so how do we decide what to display?
We may use default values but it doesn't really make sense. For --help I think
we should display all options anyway. We could either group options to
basic/advanced or add another option like --advanced-help. But you should see
for example what you could set if a db type was set to mysql.
···
On Tuesday 15 of October 2013 11:01:23 Greg Sutcliffe wrote:
> On 15 October 2013 09:37, Marek Hulan wrote:
> > > > Would we be able to introduce some sort of context? e.g, assuming you
> > > > selected db type MySQL, you only see certain other options (e.g. cant
> >
> > see
> >
> > > > the pg / sqlite adapter type)
> > > >
> > > > This might be a much wider discussion, as it applies to foreman as
> >
> > well,
> >
> > > > but i do see it related.
> > >
> > > It would be really great to be able to address these two things
> > > together.
> >
> > Ok so after short discussion with Ivan we got some idea of how it could
> > work.
> > We'd not limit grouping block by level so "Advanced parameters:" block
> > could
> > be any level. Only blocks containing word "parameters" would be used for
> > grouping.
>
> Sounds promising - I do think we have too many parameters in the default
> output
> today, and handling it within the RDoc sounds excellent.
>
> > We would also enable specifying display conditions. Condition would be
> > evaluated in order to display/hide a parameter. You could set condition to
> > a
> > whole block like this
> >
> > # ==== MySQL: $db_type == 'mysql'
> > # $mysql_user:: User of MySQL
> >
> > or you could set a condition at a parameter itself
> >
> > # === Advanced parameters:
> > #$mysql_user:: User of MySQL
> > # display: $db_type == 'mysql'
>
> How does that work on the cmdline, using --help? Nothing will be set yet,
> so how do we decide what to display?
That makes sense. +1 for a separate option for displaying advanced
configuration switches (see the output of "dpkg" with no arguments for a
[very old] precedent :P).
Greg
···
On 15 October 2013 12:53, Marek Hulan wrote:
We may use default values but it doesn’t really make sense. For --help I
think
we should display all options anyway. We could either group options to
basic/advanced or add another option like --advanced-help. But you should
see
for example what you could set if a db type was set to mysql.
>
>>
>> We may use default values but it doesn't really make sense. For --help I
think
>> we should display all options anyway. We could either group options to
>> basic/advanced or add another option like --advanced-help. But you
should see
>> for example what you could set if a db type was set to mysql.
+1 for --help and --advanced-help
The current situation is a really overwhelming output.
> That makes sense. +1 for a separate option for displaying advanced
configuration switches (see the output of "dpkg" with no arguments for a
[very old] precedent :P).
>
> Greg
>
> –
> You received this message because you are subscribed to the Google Groups
"foreman-dev" group.
> To unsubscribe from this group and stop receiving emails from it, send an
email to foreman-dev+unsubscribe@googlegroups.com.
···
On 15 October 2013 12:57, Greg Sutcliffe wrote:
> On 15 October 2013 12:53, Marek Hulan wrote:
> For more options, visit https://groups.google.com/groups/opt_out.
