Re: Libtextstyle in Jitter and Poke: sub-package mode and CSS installation

[Jose E. Marchesi]

Hi Luca!
    
    After committing the Jitter API change for José the time has finally
    come for me to play with libtextstyle.
    
    (José, if the libtextstyle integration tends to be quick as well I
    will port Poke to the new Jitter right after it, to avoid two unrelated
    API changes in quick succession.  Otherwise I will handle Poke first,
    and libtextstyle later).
    
    My simple tests work with no problems, and the basic integration of
    libtextstyle in Jitter seems easy as well, as expected.  Anyway I
    have run across an issue I had not anticipated:
    
    Jitter can now be used in "sub-package mode" rather than as a
    dependency, in the style of Gnulib.  The particular issue I had
    to resolve is explained here:
      http://ageinghacker.net/talks/#ghm-2019-talk
    Poke will use Jitter this way.
    In "sub-package mode" the Jitter sources are only distributed as a
    subdirectory of some other package; the Jitter C-generating program
    is only used at build time, if at all, and the Jitter runtime library
    is built statically and not installed.  Nothing whatsoever from
    Jitter is installed in fact, and this is intentional: from the point
    of view of a user who is interested in, say, Poke, the Jittery VM is
    just part of the hidden internal machinery.  After the super-package
    is installed its source code can be deleted, and Jitter with it.
    
    Where shall I put the default CSS file for Jitter, then?  A
    workaround I can imagine is generating some default CSS into a
    temporary file, at startup, and then loading when opening a
    libtextstyle stream.  But this is horrible.

I would have expected for the Jitter user (in this case poke) to provide
whatever customizations for the classes.  Jitter should provide a list
of these classes.
    
    What about the possibility of reading CSS from a constant string in
    memory?
    
    What would you suggest me to do in this case, Bruno?
    
    
    I am closing with some remarks about Jitter which will be mostly
    interesting to José.
    
    A program including a Jittery VM can print exactly two kind of
    outputs benefiting from libtextstyle:
    
    * VM programs in symbolic form
    * disassemblies.
    
    Both require a surprisingly simple and uniform styling, as long as you
    do not want to decorate VM program literals in a complex way; say, in
    a Lisp VM, something like
    
      push #(aa 11)
    
    where the vector delimiters and the vector elements elements are all
    printed in different styles.  For the time being José has told me he
    is not interested in that.

I achieve that using a custom printer:

void
pvm_literal_printer (FILE *out, jitter_uint val)
{
  /* XXX what about out.  */
  fflush (out);
  pvm_print_val ((pvm_val) val, poke_obase, 0);
  pk_term_flush ();
}

Note the flushing and the fact I'm not using `out'.

    Excluding this advanced printing of structured literal data, the user of
    a Jittery VM has to customize the style for a fixed number of entities,
    independent from the VM:
    
    * whitespace;
    * comments;
    * addresses;
    * VM routine labels;
    * VM instruction names;
    * VM instruction literals [!];
    * VM registers;
    * VM stacks, possibly, if they can occur as VM instruction operands
      in the future;
    * hardware instructions as bytes;
    * hardware instructions in textual form [I would not bother distinguishing
                                             even mnemonics from operands, as
                                             those and short enough anyway].
    
    I may be forgetting some cases, but nothing else seems fundamentally
    different.

Sounds good.

    Notice that [!] is the only case where the user can meaningfully define
    a custom printer.  Again, as long as we do not print structured literals
    with internal styling, this is trivial: the author of a VM does not even
    need to know the details of styling.  She will just call C functions to
    print text and numbers, in a context where the style has already been
    set.  These functions will be provided by Jitter, and their internal
    definition will use libtextstyle.
    
    Do you think I am missing some point?  Is the API I am describing
    expressive enough for you?

It is expressive.  But I don't understand why the user cannot print
structured literals with internal styling in the custom printers.  I am
doing exactly that right now.

Also, what about the FILE argument passed to custom printers?

    The way you are styling output in Poke itself, while nice and
    potentially involved, to me appears unrelated to the VM.  I believe
    the Jitter part to be quite easy, apart from the problem above.

Yep.