ksh-community / docs

KornShell ready reference and documentation
Creative Commons Zero v1.0 Universal
2 stars 3 forks source link

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

Open dwierenga opened 4 years ago

dwierenga commented 4 years ago

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):

jghub commented 4 years ago

@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.
Screenshot 2020-05-05 at 16 17 24

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 commented 4 years ago

@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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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

marcastel commented 4 years ago

@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 commented 4 years ago

@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.