Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Already on GitHub? Sign in to your account

Console banners are all shown consecutively #3731

Closed
bakura10 opened this Issue Feb 8, 2013 · 11 comments

Comments

Projects
None yet
4 participants
Contributor

bakura10 commented Feb 8, 2013

If several modules have commands for the Console component, I expect that we have:

Module 1 console banner
Module 1 console usage
Module 2 console banner
Module 2 console usage

However the following happens:

Module 1 console banner
Module 2 console banner
Module 1 console usage
Module 2 console usage

Screenshot: http://cl.ly/image/0r1Q3T0W0F06

Furthermore, I think that for homogeneity purpose, getConsoleBanner should be rename getConsoleDescription, and wrap this around "-", so that it looks better when we have several modules that use console.

Seconded. I guess extending the ZF2 console router/view component would solve this though ;)

Member

Thinkscape commented Mar 16, 2013

Here's another way to look at it:
Module 1 - Business Logic Module v2
Module 2 - SuperDuper Cacher
(the order is assigned through modules array, so it's up to you)

Banners:

$ ./zf
Welcome to Business Logic v 2.0.0
Powered by SuperDuper Cacher beta 2

Usage:

Business logic:
php index.php do some business logic          performs some business logic
php index.php do some other business logic  does something else

Super Cacher Specific:
php index.php clear cache  - clears cache
php index.php warm cache  - warms cache

You can add ------------------ lines by returning '-----------------' in getConsoleBanner. The method is named after what it does - it is a banner, not description!.

If you want to add description, do something like this:

public function getConsoleUsage(Console $console){
return array(
    '----------------------------------------------------------------------------------------------',
    '     #### MY SUPER MODULE ####  ',
    ' This modules handles various things',
    '----------------------------------------------------------------------------------------------',

    'do some business logic' => 'performs some business logic',
    'do some other business logic' => 'does something else'
);
}

You can even probe for console width to make those lines fit:

public function getConsoleUsage(Console $console){
    return array(
        str_repeat($console->getWidth(), '-'), // line from edge to edge
    );
}
Owner

weierophinney commented Mar 16, 2013

@Thinkscape - Perhaps you could add these examples to the docs? :-)

On Saturday, March 16, 2013, Artur Bodera wrote:

Here's another way to look at it:
Module 1 - Business Logic Module v2
Module 2 - SuperDuper Cacher
(the order is assigned through modules array, so it's up to you)

Banners:

$ ./zf
Welcome to Business Logic v 2.0.0
Powered by SuperDuper Cacher beta 2

Usage:

Business logic:
php index.php do some business logic performs some business logic
php index.php do some other business logic does something else

Super Cacher Specific:
php index.php clear cache - clears cache
php index.php warm cache - warms cache

You can add ------------------ lines by returning '-----------------' in
getConsoleBanner. The method is named after what it does - it is a
banner, not description!.

If you want to add description, do something like this:

public function getConsoleUsage(Console $console){return array(
'----------------------------------------------------------------------------------------------',
' #### MY SUPER MODULE #### ',
' This modules handles various things',
'----------------------------------------------------------------------------------------------',

'do some business logic' => 'performs some business logic',
'do some other business logic' => 'does something else');}

You can even probe for console width to make those lines fit:

public function getConsoleUsage(Console $console){
return array(
str_repeat($console->getWidth(), '-'), // line from edge to edge
);}


Reply to this email directly or view it on GitHubhttps://github.com/zendframework/zf2/issues/3731#issuecomment-15005474
.

Matthew Weier O'Phinney
matthew@weierophinney.net
http://mwop.net/

Contributor

bakura10 commented Mar 17, 2013

Mmmhhh... Does not make sense to me @Thinkscape. What's the banner used for then ? Of course you could add the banner in the usage like you did, but then the getConsoleBanner is useless. To my understanding, the banner should be... the banner for the module.

Member

Thinkscape commented Mar 17, 2013

A banner in cli app is something that shows at the top when run without arguments.
It's usually app's name. Because an app can consist of multiple modules, then all those "banners" are concatenated and displayed (i.e. 3 business apps that differ in the selection of modules from some shared pool):

Here's another example of theoretical app that uses BusinessAcmeModule, DoctrineModule and AwsManagerModule:

$ ./runapp
Business Application 2.0 - Copyright Acme Inc. Approved by Joe
Doctrine Module 0.7.4 with Doctrine ORM 2.4
AWS Manager 1.0b with AWS API 4.2

Usage:
   php index.php some business action [--params]
   php index.php some doctrine action [--params]
   php index.php some aws action [--params]

Notice that banners from different modules are brief, usually contain
module version and probably capabilities. These are not meant to be hints,
descriptions or help messages.

That's where getConsoleUsage() comes in. If you have 20+ parameters,
parameter groups, alternating flags, multiple invocation styles etc. - you
put it there. There is no limit on the numer or length of those, although
it's a good practice to keep it brief, too.

Nobody likes when a CLI app spews 6 full screens of parameters and misc
descriptions.

tl;dr

  1. Banner is a one-liner that names the application/module.
  2. Usage is a brief listing of available commands and their parameters.
  3. For other purposes, just implement help [topic] action and you are
    free to output multi-page man pages for your app.
Contributor

bakura10 commented Mar 17, 2013

I see... We should really have some standardized (or encouraged) way to do this in the doc. This is going messy as soon as you have three or more modules that have commands. Especially when using ZFTool that goes with a lot of commands.

For instance, I've changed two modules using a single line banner:

http://cl.ly/image/402H1x1k0w0Z

It's not clear that we have two modules, SlmQueueDoctrine v 0.2.0 and SlmQueueSqs v 0.2.3.

But then ? I have added "Usage" to separate each module. Some modules like ZFTool already are separated into different parts, and it makes it quite confusing to immediately see all the commands of a specific modules.

With the name inserted in getConsoleUsage, I now have this:

http://cl.ly/image/3q1a3X472n1y

This is a bit clearer as it really allows to visually separate each module. BUT it is up to the developer to add this. Some will, some won't. Some will insert 40 dashes, some other 80, some other $console->getWidth().

I think this should be done automatically be the component. We could assume that, for each module taht provides usage, the component automatically prepend the usage by something like:

str_repeat('-', $console->getWidth(),
moduleName(),
str_repeat('-', $console->getWidth(),

What do you think? Maybe we could even colorize this part (the module name).

Contributor

bakura10 commented Mar 17, 2013

What do you think about this: http://cl.ly/image/1h3W1M3D3b0P I think it makes it clear and everything pop out visually.

So basically:

  • We render what is returned by getConsoleBanner in blue, and we encourage people to only indicate : Module name + version. One line, simple.
  • We prepend dashes, module name and dashes by what is returned from getConsoleUsage. And we ask people only enter commands documentation in this section.

It may seems a bit opiniated, but I really think we need something like this and "force" people to organise commands a given way to keep everything clear and homogenous !

Member

Thinkscape commented Mar 18, 2013

It does pop out, there are lines and colours. I do not feel we should force this looks upon applications though. We cannot force the way people use getConsoleUsage() and getConsoleBanner() either. What we could do is guide them.

Contributor

bakura10 commented Mar 18, 2013

No, by default it does not pop out because all the commands are shown one after the another if people don't include module name in getConsoleUsage() (which is what happens currently for most modules).

Member

Thinkscape commented Mar 18, 2013

Your code suggests otherwise - it array_unshifts to array, or creates an array with those lines in case of a string - which means those lines will always be there.

This is not needed in case of a single modules exposing those - i.e. Application module.

Styling might be also an issue here. Red on black, which most consoles would use, hurts my eyes. Those lines are ugly. I rarely see console commands/tools that have such complex usage info (or ascii lines across the whole screen). Some consoles do not support or accept color output at all.

Please take a look at other *nix tools or OSS tools with console commands for inspiration on this. Right now (given red appears to me pink; or red on something else than black) it looks kinda clear but ugly and "verbose" in comparison to other console commands.

Owner

weierophinney commented Mar 28, 2013

Closing, as #4061 has been merged.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment