[ClusterLabs] Documentation driven predictability of pacemaker commands (Was: Pacemaker 2.0.3-rc3 now available)

[Jan Pokorný]

On 14/11/19 10:16 -0600, Ken Gaillot wrote:
> On Thu, 2019-11-14 at 14:54 +0100, Jan Pokorný wrote:
>> On 13/11/19 17:30 -0600, Ken Gaillot wrote:
>>> This fixes some more minor regressions in crm_mon introduced in
>>> rc1.  Additionally, after feedback from this list, the new output
>>> format options were shortened. The help is now:
>>> 
>>> Output Options:
>>>   --output-as=FORMAT       Specify output format as one of: console (default), html, text, xml
>>>   --output-to=DEST         Specify file name for output (or "-" for stdout)
>>>   --html-cgi               Add CGI headers (requires --output- as=html)
>>>   --html-stylesheet=URI    Link to an external stylesheet (requires --output-as=html)
>>>   --html-title=TITLE       Specify a page title (requires --output-as=html)
>>>   --text-fancy             Use more highly formatted output
>>> (requires --output-as=text)
>> 
>> Wearing the random user's shoes, this leaves more questions behind
>> than it answers:
>> 
>> * what's the difference between "console" and "text", is any of these
>>   considered more stable in time than the other?
> 
> Console is crm_mon's interactive curses interface

With said possible explanation in terms of equivalence, I rather meant
whether the textual representation shall be assumed the same as with
"text" from get go, implying, amongst others, --text-fancy being
supported etc. (and if not, why not when ncurses just assumes full,
interim control over the terminal screen, as a recyclable canvas to
output to rather than outputting just one-way only raw lines with
"text"; granted, it can moreover respond interactively to key
presses, but for passive observation only).

I.e. the documentation shall state explicitly something like:

> "console" output is stream-lined alternative to "watch crm_mon -1"
> (hence reusing "text" output format) that makes do without excessive
> polling and allows the output to be refined interactively, with
> respective output manipulations mapped to these key presses:
> [keyboard control explaination]

Since I already touched that, on the other hand, it's not clear why,
for instance, "non-console" outputs could not ask for a password
interactively (given the interactive use is detected, see below).

Keeping user's hat on, there's more behavioral aspects that'd be
good to be able to learn about ahead of time:

- that default mode doesn't adapt to whether there's indeed a terminal
  at the output, as opposed to today's habitual and de facto assumed
  conditionalizing per isatty(3), so one cannot just naively pipe
  "endless" crm_mon output to a file/further pipe-line without full
  output qualification (it may be understood like that from the current
  help, although experience built with other SW will suggest it just
  doesn't state full reality for brevity) -- conversely, it could
  be modified to behave per this expectation

- what can we expect from the output using a demonstrative example
  right in the man page (see, e.g., how "systemctl status" output
  is documented)

- on top of previous, what exactly do we gain from appending
  --text-fancy?  sadly, I observed ho difference in a basic
  use case

>>   - do I understand it correctly that the password, when needed for
>>     remote CIB access, will only be prompted for "console"?
>> 
>> * will --text-fancy work work with --output-as-console?
>>   the wording seems to suggest it won't
>> 
>> Doubtless explorability seems to be put on the backburner in
>> favour of straightforward wiring front-end to convoluted logic in
>> the command's back-end rather than going backwards, from
>> simple-to-understand behaviours down to the logic itself.
>> 
>> E.g., it may be easier to follow when there is a documented
>> equivalence of "--output-as=console" and "--output-as=text
>> --text-password-prompt-allowed", assuming a new text-output
>> specific switch that is not enabled by default otherwise.

-- 
Jan (Poki)
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 819 bytes
Desc: not available
URL: <https://lists.clusterlabs.org/pipermail/users/attachments/20191115/53745873/attachment.sig>