Document how to do standard user configuration (keybindings, prompt, etc)

[dwierenga]

There's a general scarcity of information of how to do user configuration of KSH around the web (and many of the "answers" amount to "just use bash").

Compiling a standard library of examples of how to do the basic things that most users want from their shell would be a huge win. Some things this would include (in no particular order):

• Fixing common problems like tab-complete, arrow keys, delete/backspace
• What the standard keybindings are and how to list your current keybindings (especially the differences between vi and emacs modes)
• How to do keybindings in each edit mode, especially advanced configurations, like the ^B / ^F keybinds in vi insert mode as noted by @jghub
• How to customize the prompt
• Examples of sane naming of initialization files, usage of environment variables like FPATH, etc.

[jghub]

@dwierenga:
you asked after the keybinding stuff in combination with vi mode. I understand, the issue you've opened has a wider scope but just to answer that specific point, here are my keybindings (the way to do it is 100% lifted from the bolsky/korn book so if you get hold of a copy you'll find it explained there :)):

# extend vi mode via some additional emacs-like cursor movements which
# also work while in input mode. the `keybind' function is that
# from the KornShell book (but one variable is renamed...).
#
set -o vi
function keybind # key [action]
{
    typeset action=$(print -f "%q" "$2")
    case $# in
    2)      Keytable[$1]=' .sh.edchar=${.sh.edmode}'"$action"
            ;;

    1)      unset Keytable[$1]
            ;;
    *)      print -u2 "Usage: $0 key [action]"
            return 2 # usage errors return 2 by default
            ;;
    esac
}

# here are the keybindings for navigation in the current line and the
# command history (plus clear screen).
# actions essentially a la `readline'. note that the
# behaviour of ^F, ^B differs slightly in input and command mode.
#
bindkeys () {
   # we unset `Keytable' first so that it is possible to switch the
   # editor in a running shell, followed by a manual call to `bindkeys'.
   # note that `bindkeys' is intentionally defined in the "old" style.
   unset Keytable
   typeset -A Keytable
   typeset options=$(set +o)
   if [[ ${options##*--emacs} != "$options" ]]; then 
      # clear the screen and restore current line content:
      keybind  $'�clear
�'
   else
      keybind � 0i          # go to beginning of line
      keybind � ha          # go one char left
      ##keybind � llxa         # delete char under the cursor (no good yet)
      keybind � \$a         # go to end of line
      keybind � la          # go one char right
      keybind  $'yyddiclear
\Epa'
      keybind � j           # history down
      keybind � k           # history up
      keybind � /           # start reverse history search
      keybind � '$d0xa'     # delete line
   fi
}
trap 'eval "${Keytable[${.sh.edchar}]}"' KEYBD
bindkeys
#
# for reference: the KEYBD trap is executed after each single input
# character. on entry, `.sh.edchar' contains the respective input character,
# on exit, `.sh.echar' is the input sequence substituted for the original
# character. `.sh.edmode' contains ESC if we are currently in vi input mode.
# the `keybind' function fills an associative array `Keytable' whose indices
# are the input characters for which bindings are to be defined. the
# values are the strings redefining `.sh.edhcar' (including automatic switch
# to vi command mode, so this has not to be done in the `keybind'
# call) which is finallye eval'ed when the trap springs.

the copy+paste from my .kshrc into this post naturally does not keep the control-chars correctly displayd, so I also added a screenshot of the bindings: all ^F etc are of course the real control char codes (what you can enter like ^VF to insert ASCII 006 etc.)

no guarantees of course, but works for me :)

[marcastel]

@jghub Thanks for sharing :-)

As we will often be confronted with various personalisations, how should we organise this ?

Many feedbacks will be probably be one-liners or similar, others will be elaborated, as above. On the long term this should probably be a site on its own, but in the meantime we can collect things here.

I suggest the following setup, please feel free to comment:

1. We maintain a howto (or faq, ...) top-level directory in this ksh-community/docs repository.
2. Within that directory we have a subdirectory per submitter; in this case we would have howto/jghub
3. Within each contributors private directory, we index contributions in a YAML file which enumerates, describes, and tags the provided contributions. All such files being then consolidated through a batch process (and possibly a GitHub action) to generate a global FAQ.md for all contributions of all contributors.

We keep the YAML file simple so that contributions are easy and hence encourage the community to share. Using this logic and structure, contributions can be made via pull requests^(a).

howto:

 - title: long live KornShell
   abstract: |
       It's only in the late 2010s with Bash 4 that Bash can finally (kind of)
       lineup with KornShell capabilities
   tags: bash
   code: ksh --version

 - title: my keybindings
   abstract: My vi bindings
   tags: kshrc keybind
   url: https://github.com/ksh-community/docs/issues/3#issuecomment-624088448

 - title: my revisited keybindings
   tags: kshrc keybind
   file: kshrc-keybind.ksh

Though still probably rough around the edges, this is a no brainer and can be setup darn fast.

^(a) An alternate approach -- which I know some members dont like, but which could provide more flexibility, would be to use sub-repositories. The advantage for the contirbutor being that he has his own repository which he maintains and manages as he likes; we only pull it in when we build our FAQ.

[hyenias]

I recommend creating a separate repo called "scripts" for source code that would inherit a more applicable source code license like Apache 2.0 or MIT instead of this docs repo's CC0-1.0 license. Think future "Oh My KSH!" or something similar aka a library of ksh scripts/source code.

I feel that this docs repo is to provide understanding of the KornShell and our implementation of it. Explanations and elaborations of referenced scripts could occur.

In my opinion, as far as displaying the contents of the docs repo, what has been done is fine--just using interconnected markups (*.md). Perhaps an easier additive approach would be to enable this repo's wiki pages instead of all the automation and human time cycle requirements listed above (not a "no brainer" to me). When the content grows beyond a certain point, perhaps all the markups get revamped into a nice website via GitHub Pages associated with the repo.

[jelmd]

Strong nope wrt. dir/submitter. IMHO, the doc team is responsible for collecting, eval, categorize and putting such stuff into the right documents, i.e. where users can find it easily.

[jelmd]

Wrt. wiki: doc repo pages can be edit via github web GUI directly as well and if github markdown is used, there is not really a need to create another construction site/maintain a wiki (at least not for this topic ;-)).

[melbit-dannyw]

And I think this also could just go into the ksh programming manual when we get that up and running.

[marcastel]

@jelmd Strong nope to GitHub pages. By experience very difficult to maintain when big and more than one person in charge of updating. Further GFM is prehistoric Markdown.

The value of information is not its presence somewhere, but the ability to access it easily. While Google-generations may only believe in NoSQL data lakes, I firmly believe that indexed and structured information is the fastest path to relevant search results. Contributed content portions of information need to be structured, organised, classified to be easily accessible.

Contrib directories have been in practice in Open Source projects since the very first days of Richard Stallman's initiative. They are the natural way of including third party contributions to an Open Source project. Be it documentation or code.

The contents and structure of a contrib directory are managed by the package maintainers, not by the third parties. Meaning that you control what, when, and how things are included. Further you enforce a documentation scheme. Markdown for instance, is probably not the best input format: we want to focus on formal know_how snippets. Markdown is probably the output format. YAML is probably a better input candidate to enforce structure.

@hyenias you pull in the licensing issue, which has to be addressed. By convention contribs are give aways, so fall under the licensing terms of the parent package. In the Git world, sub-repositories is a way of maintaining third party licenses should they not want to adopt your licensing scheme. Sub-repositories are a pain to manage.

Important to remember here we are talking of documentation. Not development projects. Consequently submitted information is mostly code snippets of a couple of lines. We may be confronted, as in some KornShell books, with educational chapters that provide a full scripted example (e.g. for those who remember the famous KornShell address book), or, as was the case that triggered this issue, individuals submitting part or all of their .profile or .kshrc files to demonstrate some KornShell feature.

A fair question is: does the ksh-community want to collect and share this information. IMO this is yes. Should it be no, then this can easily be housed elsewhere.

[hyenias]

@marcastel: From my viewpoint, I only have a limited amount of time to spend on ksh efforts. This is my choice. As such, I wish to keep things simple as they can be. I do not possess your experience. I am learning along the way. I have plenty on my plate to work on for a while.