Best practices for command line applications?

[tastytea]

There is a paper called Accessibility of Command Line Interfaces. The conclusions I took from it are:

• Add an option to output tabular data as HTML tables or comma separated values (CSV).
• Add an option to output long output as HTML, with headings and other semantic elements where appropriate.
• Describe how the output is structured so that users have the ability to use utilities like grep to only get what they need.
• When a command runs for a long time without outputting anything, output status messages. But no progress bars or spinners.
• Don't use ASCII-art.
• Ensure that an HTML version of all documentation is available. man pages do not work.

Questions

• Are the conclusions correct?
• How often should status messages appear?
• Can I erase the last status message to print the new one at the same place or is it better to just print a new line?
• When I make a pull request, should I put it in “Application Accessibility” or in its own file?

[devinprater]

Replies inline: Devin Prater ***@***.*** Https://devinprater.flounder.online

On Jul 1, 2021, at 6:23 PM, tastytea ***@***.***> wrote: There is a paper called Accessibility of Command Line Interfaces <https://dl.acm.org/doi/fullHtml/10.1145/3411764.3445544>. The conclusions I took from it are: Add an option to output tabular data as HTML tables or comma separated values (CSV).

I’d say CSV. Screen readers would just read the tags and all of HTML. Unless the output is sent to a file. But then the user would have to open that in a browser, which means switching contexts.

Add an option to output long output as HTML, with headings and other semantic elements where appropriate.

Yeah, that could be useful if sent to a file.

Describe how the output is structured so that users have the ability to use utilities like grep to only get what they need.

Yes, definitely. Or provide a way for the user to use templates in a configuration file to structure output how they want.

When a command runs for a long time without outputting anything, output status messages. But no progress bars or spinners.

Yes, but no Unicode characters. Also, things like Python’s Pip wheel is confusing to listen to, “bar underline line slash …”

Don't use ASCII-art.

Definitely. Box-drawing characters are so annoying in TUI apps.

Ensure that an HTML version of all documentation is available. man pages do not work.

Why would Man pages not work? I can scroll them and all just fine. But it is a good idea to have HTML docs, as I can then read them on other platforms, or convert them to other formats for reading on stuff like braille devices (although I could just use BRLTTY on the CLI if BRLTTY supports my braille display).

Questions Are the conclusions correct?

Pretty much, but see my comments above.

How often should status messages appear?

I’d say have that configurable, but maybe every 30 seconds would be good enough.

Can I erase the last status message to print the new one at the same place or is it better to just print a new line?

It’s better to print a new line.

When I make a pull request, should I put it in “Application Accessibility” or in its own file?

Maybe put it in Application Accessibility, and just have it under its own heading (level 1), with GUI Accessibility in another heading. Thanks so much for the work!

…

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#3>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ADUMTTVUVFZBRWBYXAIGTNDTVT2I3ANCNFSM47VUIPQA>.

[tastytea]

Add an option to output tabular data as HTML tables or comma separated values (CSV).

I’d say CSV. Screen readers would just read the tags and all of HTML. Unless the output is sent to a file. But then the user would have to open that in a browser, which means switching contexts.

The paper says that exports to an HTML or CSV file are a popular demand. However, they only interviewed 6 developers, so it's probably not very representative.

Ensure that an HTML version of all documentation is available. man pages do not work.

Why would Man pages not work? I can scroll them and all just fine. But it is a good idea to have HTML docs, as I can then read them on other platforms, or convert them to other formats for reading on stuff like braille devices (although I could just use BRLTTY on the CLI if BRLTTY supports my braille display).

The paper claims that “The output of --help or man is long unstructured text and screen reader users do not use them for documentation.”

[devinprater]

We do use them for help. I mean, I'd rather do that in Emacs where I have a buffer of text to review, but it can definitely be done. HTML docs are helpful, though.

…

Sent from my iPhone

On Jul 2, 2021, at 7:55 AM, tastytea ***@***.***> wrote:  Add an option to output tabular data as HTML tables or comma separated values (CSV). I’d say CSV. Screen readers would just read the tags and all of HTML. Unless the output is sent to a file. But then the user would have to open that in a browser, which means switching contexts. The paper says that exports to an HTML or CSV file are a popular demand. However, they only interviewed 6 developers, so it's probably not very representative. Ensure that an HTML version of all documentation is available. man pages do not work. Why would Man pages not work? I can scroll them and all just fine. But it is a good idea to have HTML docs, as I can then read them on other platforms, or convert them to other formats for reading on stuff like braille devices (although I could just use BRLTTY on the CLI if BRLTTY supports my braille display). The paper claims that “The output of --help or man is long unstructured text and screen reader users do not use them for documentation.” — You are receiving this because you commented. Reply to this email directly, view it on GitHub, or unsubscribe.