poke, hyperlinks, modeline, etc

[Jose E. Marchesi]

Hi Bruno, Darshit, all.

The poke terminal hyperlinks (the two flavors we support, 'i' and 'e'
commands) are proving to be very nice.

Recently I changed the hserver implemementation to be a hybrid of C and
Poke (see pk-hserver.c and pk-hserver.pk) and therefore Poke programs
can now print poke hyperlink themselves in a very easy way.

For example, a Poke program (which could be a poke command) can do:

  hserver_print_hl ('e', "click here", "2 + 2");

As an example, right now I am documenting the maps/mapfiles
functionality in poke, which adds a lot of .map commands and
subcommands.  A typical workflow looks like this:

  (poke) .file foo
  (poke) .map load elf
  [elf](poke) .map show elf
  Offset   Entry
  0x0UL#B  $elf::file
  [elf](poke) $elf::file.get_sections_by_name (".text")
  [Elf64_Shdr {
    sh_name=0x93U#B,
    sh_type=0x1U,
    sh_flags=#<ALLOC,EXECINSTR>,
    sh_addr=0x530UL#B,
    sh_offset=0x530UL#B,
    sh_size=0x1b2UL#B,
    sh_link=0x0U,
    sh_info=0x0U,
    sh_addralign=0x10UL,
    sh_entsize=0x0UL#b
  }]
  [elf](poke) .map load dwarf
  [dwarf,elf](poke) .map show dwarf
  Offset   Entry
  0x1085UL#B  $dwarf::info
  [dwarf,elf](poke) .info maps
  IOS   Name    Source
  #0    dwarf   /home/jemarch/gnu/hacks/poke/maps/dwarf.map
  #0    elf     /home/jemarch/gnu/hacks/poke/maps/elf.map

The [...] part at the left of the (poke) prompt is a sort of a
"modeline", which at the moment lists the loaded maps.

Managing map contents involves a full set of more subcommands.  For
example, to create a new map and add an entry to it:

  (poke) .map create mymap
  [mymap](poke) var anarray = int[3] @ 0#B
  [mymap](poke) .map entry add mymap, anarray
  [mymap](poke) .map show mymap
  Offset   Entry
  0x0UL#B  $mymap::anarray
  [mymap](poke) .map entry remove mymap, anarray
  [mymap](poke) .map show mymap
  Offset   Entry
  [mymap](poke) 

As you can see, there is a lot of .map commands involved there.
Commands that the user needs to write.  So I am seeing a lot of
opportunities for hyperlinks here:

- Clicking on map names in the modeline [elf,dwarf,whatever] could
  execute the hyperlink 'i' '.map show NAME'.

- The output of `.map show NAME' can include "buttons" to remove the
  listed entries:

  [mymap](poke) .map show mymap
  Offset   Entry           Actions
  0x0UL#B  $mymap::anarray [remove,frob,...]
  0x2UL#B  $mymap::lala    [remove,frob,...]

  Where `remove' and `frob' are hyperlinks that would result in some
  action in the given map entry.

- Many many more things...

Also, we can allow the users to customize their own modeline by writing
a Poke function that prints it.  This function could include any
hyperlink they deemed useful for them, like "buttons" for commands they
use often:

  [dothis,dothat](poke) _

If the modeline is too big it can be printed above the prompt, and it
could also be smart and only be printed every N lines or when it goes
out of scope of the screen (like pagers do).

This is what we envisioned when you introduced the terminal hyperlinks
to us in one of the rabbit herd weekends, is really a new paradigm in
interacting with command-line interfaces, and we now have everything we
need to make poke use its full potential.

I am very excited about it.

However, this all depends on:

a) the app:// protocol we designed
b) the little app-client utility that you wrote
c) Having the different terminals configured to use (or to implement
   themselves) app-client.

Your past attempt to get this somehow standardized with the XDG people
wasn't successful, and the original author of terminal hyperlinks
explicitly said he doesn't want to be involved with them any longer.

But when poke gets packaged in Debian, for example, we want hyperlinks
to work for the Debian user.  Same for other distros.

What would be needed for that to happen?
I would say:

1) To go ahead and use app:// anyway.  Let's just ignore XDG and other
   standardization boards/groups.  A good old de-facto standard works
   just as well.

2) To release app-client on its own.  A release tarball that distros
   could easily package.

3) To add app-client as an explicitly (optional) dependency of poke.

4) To ask whatever distro packaging poke to also package app-client, and
   to configure their terminal packages to use it when they see app://
   hyperlinks.

WDYT?