Revert -docs back to table format and add -longdocs

41 views
Skip to first unread message

BladeOfLight16

unread,
Jun 14, 2013, 6:16:15 PM6/14/13
to psake-dev
Hello, all. I posted this as an issue on github, but I now I'm not
sure that was the right place for it (especially since I'm offering to
work on it). It's https://github.com/psake/psake/issues/66 if you want
to go look.

The -docs parameter is designed to be a handy reference list of the
available tasks. I work on a team of usually 2 to 5 people, and
usually several team members know very little about the build scripts.
Sometimes they ask me what commands to use, and I often tell them to
use -docs to check because I don't always remember off-hand myself.
Now, my scripts often have 10 or more tasks. This is easy to reach
since they deal with configuration, compilation, database deployment,
unit/integration tests, packaging, and even deployment to dev sites.
Imagine me telling a UI developer to look at -docs and this is what he
gets: (You can just scroll past the output without reading.)

Name : Task0
Alias :
Description :
Depends On :
Default :

Name : Task1
Alias :
Description :
Depends On :
Default :

Name : Task2
Alias :
Description :
Depends On :
Default :

Name : Task3
Alias :
Description :
Depends On :
Default :

Name : Task4
Alias :
Description :
Depends On :
Default :

Name : Task5
Alias :
Description :
Depends On :
Default :

Name : Task6
Alias :
Description :
Depends On :
Default :

Name : Task7
Alias :
Description :
Depends On :
Default :

Name : Task8
Alias :
Description :
Depends On :
Default :

Name : Task9
Alias :
Description :
Depends On :
Default :

I hope this simple example is enough to prove that the current
implementation of -docs makes it utterly useless as a quick reference.
That's only 10 tasks. Only the smallest of build scripts are going to
have less than 5.

For this reason, I would like to propose two changes:

1. Change -docs back to its original behavior of printing a compact
table.
2. Add a -longdocs parameter that prints out a long list like above.
This would be allowed to appear with or without the -docs parameter.

I considered leaving -docs with its current functionality and adding
something to give a table, but I decided to propose this instead
because a second -docs-like parameter is more likely to be discovered
by power users, which the long list is aimed at. I think it makes more
sense for -docs to be the common users' implementation and for a
second parameter to be geared towards power users.

I'm willing to work on this myself, but I'd like to get the
requirements straight first. How does this proposal sound? Are there
better ways of doing this?
Reply all
Reply to author
Forward
0 new messages