Help on function options

Fatipati

4/10/23, 3:24 PM

I am writing documentation for a bash function that I am writing. It supports a colour option which can be one of --vlt --blu --grn --ylw --orn --pur --red --wht. I have used the following description but am unsure whether it would be sufficiently understandable, and would like improvements this descriptive help.

 --COLR
   Colour Option
 
   --COLR  Brief   |  --COLR  Brief
   ----------------+----------------
   --vlt   Violet  |  --orn   Orange
   --blu   Blue    |  --pur   Purple
   --grn   Green   |  --red   Red
   --ylw   Yellow  |  --wht   White

0 + 0

bash

functions

manpage

Artur Meinild

4/10/23, 4:03 PM

I believe this would be heavily based on individual opinion, and thus off-topic here. I would suggest you do a user survey with those who should read the documentation and get their opinion instead. Cheers!

Fatipati

4/10/23, 4:25 PM

Are there any command line programs that do this sort of option table list?

terdon

4/10/23, 5:36 PM

I'm sure there will be. Each program author is free to do whatever they like in their options. But since this isn't really a question about Ubuntu I agree with Artur that it isn't off topic. Personally, I would just have a `--color` option that takes values (e.g. `--color blue`) and then provide a list of acceptable values in the help message.

Score:0

Ubuntu

karel

4/12/23, 2:32 AM

The bash function documentation would be easier to understand if you replaced the ambiguous word "Brief" with the more descriptive phrase "Color name". If is a manual that is invoked from the terminal by the man command, you could also improve the readability by formatting the first line as bold text as is frequently done in manual pages.

--COLR
  Color Option

  --COLR  Color name  |  --COLR  Color name
  --------------------+--------------------
  --vlt   Violet      |  --orn   Orange
  --blu   Blue        |  --pur   Purple
  --grn   Green       |  --red   Red
  --ylw   Yellow      |  --wht   White

0 + 0

Elon Musk

I sit in a Tesla and translated this thread with Ai:

EN: Help on function options

TH: ความช่วยเหลือเกี่ยวกับตัวเลือกฟังก์ชัน

RO: Ajutor pentru opțiunile funcției

RU: Справка по параметрам функций

VI: Trợ giúp về các tùy chọn chức năng

Post an answer

Most people don’t grasp that asking a lot of questions unlocks learning and improves interpersonal bonding. In Alison’s studies, for example, though people could accurately recall how many questions had been asked in their conversations, they didn’t intuit the link between questions and liking. Across four studies, in which participants were engaged in conversations themselves or read transcripts of others’ conversations, people tended not to realize that question asking would influence—or had influenced—the level of amity between the conversationalists.