janet-projects-notes.txt

* repository organization

  * make the main deliverable `<name>.janet` -- the extension is
    important if wanting to be able to use as a library.  nicest if
    this deliverable sits in the repository root as well.

  * for libraries, could still have a `<name>` directory that has the
    content `init.janet` and `<name>.janet` for jpm / jeep
    installation, but `<name>.janet` can still be used independently
    as a single file library?  would be nice to have `<name>.janet` at
    the repository root.  how to avoid the multiple files getting out
    of sync though...

  * jeep vendoring to track bits and their "versions".  better for
    reproducibility and investigation.  if not going to use jeep, need
    own vendoring bits.  the pieces can be brought together in a
    single file using a tool like jell.

  * by default, jell now embeds a date-time string as a version string
    in the file it produces.  this is potentially helpful for the case
    where the file is copied elsewhere and later one wants to get a
    sense of which "version" it might be.

  * can still provide jpm / jeep / etc. installation methods.

  * for some repositories, am bundling the specific jtfm.janet and
    jell files.  this makes the specific dev bits more self-contained
    and less brittle.  currently they can be brought in via jeep's
    vendoring mechanism.

  * for non-windows, can copy the `<name>.janet` file to PATH as
    `<name>`, or clone the repository and symlink from one's PATH dir to
    `<name>.janet`, but call the link `<name>`.

  * need to think a bit more for what to do about windows...shim,
    .bat launcher, etc...just include a suitable .bat file in the
    repository?

  * would be nice if README was straight-forward and simple.
    currently trying just usage output - but what about installation
    instructions...

* project organization

  apart from the repository organization, keep at least one notes.txt
  file which most likely doesn't get committed to the repository.

  notes.txt could contain:

  * description
  * rationale
  * non-goals
  * limits
  * hidden features
  * pre commit process

* identifying and addressing synchronization issues

  some projects are ending up with files with different names but
  the same content, e.g. jackal has `jakl` and `jakl.janet`.  is
  there some way to avoid these bits getting out of sync?

  vendor within the project using jeep?  this would at least make it
  possible to have only a single command that keeps things
  up-to-date...

  also, using jell means that "compiled" output might not be
  up-to-date...so this is also a synchronization issue.

  usage output being used in the README is also another
  synchronization situation.

  tests ought to be run before commiting as well.  how can this be
  checked?

  perhaps having a single command to automate at least checking if
  things are out-of-sync would be useful?

  would do nothing scripts be any use?

* testing

  * frequent enough batch testing across all projects

  * sub-batch testing for things like jell

  * testing of things in jtfm's search.janet is light perhaps because
    it involves the filesystem.  are there good ways to test such
    things?  touching of secondary storage has issues related to
    creating and destroying things?

  * platform-specific testing is not so straight-forward?
    e.g. windows file system paths are different from *nix paths.

* unwanted duplication

  * jtfm's parse-path (in utils.janet) appears to be something similar
    to split-path from jell's utils.janet.  also take a look at
    localpath.janet (from janet-localpath).

* operational points

  * adopt approach of recording thoughts in notes.txt but waiting
    until need is dire, painful, etc. to work on implementation or
    even sketching out what an implementation might look like?

  * spend time between "read-only mode" (e.g. via a tablet) and
    sitting in front of editor.  switch between them as well as
    spending time on other things (allow background processing).

* benefits from having a decent data formatter (e.g. suspect that
  zprint can do this for clojure)

  * less time spent on manual formatting while working with source in
    an editor (at least the actual value portions of tests)

  * programmatic updating of actual values in jtfm

  * investigating unformatted data values shared by others should
    become easier

  * other folks can use the tool to format the values they are about
    to share.

* notes on data formatting / pretty printing

  * possibly a "good enough" / "close enough" thing plus manual
    intervention would be better than nothing?  or may be one
    could use the existing value as a hint for formatting the new
    value in some cases?

  * could it somehow be easier to use zippers for reformatting?
    the clojure zprint program uses rewrite-clj.  perhaps there
    are some hints there...

  * if an approach that ignored line lengths were adopted
    initially, could it be practically adapted to an approach that
    accounted for line length limits?

  * indenting the formatted result should match the indentation
    that the editor provides so when working in an editor with the
    "results", indentation doesn't alter what was generated.

  * some constructs may not be desirable for output such as
    long-strings and long-buffers.  in source code, these can end
    up being affected by special "dedenting" and they evaluate to
    strings anyway so it might be better to avoid using them for
    output (except if non-multiline?).

    paren arrays (e.g. `@(:a :b)`) are also an "input"
    representation.  they just evaluate to ordinary (i.e. square
    bracket) arrays anyway so these may also be "ignorable".

    ordinary (i.e. "round paren") tuples may be good to avoid as
    well because expected values that contain them don't expect
    them to resolve to function / macro / etc.  calls.  may be
    better to stick with square bracket tuples or quote paren
    tuples (the former seems nicer, but not sure if that might
    cause issues).

    hex and other non-decimal ways of expressing numbers for input
    might be problematic for output.  how would one know when to
    use some non-decimal representation?

    comparing expected and actual results for numbers seems tricky
    / problematic because of things like:

      (= 0.3 (+ 0.1 0.2))
      # =>
      false

    quoting and quasiquoting don't show up in output.  they, like
    other reader macros, get transformed into "calls", e.g. 'a is
    replaced with (quote a), ~a is replaced with (quasiquote a)

    line comments will not be output as they can't be the result
    of evaluation.

    draft list of things to handle in an output format:

    * nil, true, false (constants)
    * decimal numbers
    * strings (using double quote delimiters)
    * buffers (handle similarly to strings)
    * keywords
    * symbols
    * bracket array
    * bracket tuple
    * table
    * struct
    * non-eol whitespace
    * eol sequence

    the "atomic" things in the list above (starting at `nil` and
    continuing through symbols) should never be "broken" across lines
    (except perhaps buffers and strings using the functions `buffer`
    or `string` but that kind of thing should probably be held off on
    until much later if at all?).  in practice, things strings and
    buffers seem like they can end up being quite a bit longer than
    constants, numbers, keywords, and symbols.

    non-atomic things (from bracket arrays through structs) can
    (and likely should in some cases) be broken across lines to
    improve readability.

    non-eol whitespace and eol sequences are probably most of what
    can be manipulated toward arriving at an improved formatting
    of data?

    the collections (e.g. structs, etc.) have visible delimiters.
    the opening sets of delimiters are just like atomic things
    from a formatting perspective(?).  the closing delimiters can
    bunch up and possibly end up making the last "item" of a
    collection "longer".

  * come up with samples of formatted data?  spelling out specific
    data (e.g. structs, tuples, etc.) and then observing the
    process of formatting them might result in ideas for various
    approaches?  collect samples in to a directory as individual
    files instead of inlining them in this file?

* jeep vendoring notes

  trying to switch to using jeep's vendoring.

  this should result in:

  * tracking of explicit pieces and commits used when vendoring

  * no more use of git subrepo

  * switching over to use jtfm (over jeat)

  * usage of jell where it makes sense

(numbers below a bit out-of-date)
deps	number of projects
1	22
2	4
3	5
4	1
5	2
6	1

----
todo
----

* can-we-do-better
  * jeat
* clojure-peg
  * jeat
* index-janet-source
  * jeat
* janet-bits
  * jeat
* janet-checksums
  * jeat
* janet-jsonish
  * jeat
* janet-localpath
  * jeat
* janet-minipbt-transation
  * jeat
* janet-please
  * jeat
* janet-punyishcode
  * jeat
* janet-syntax-highlighting
  * jeat
* janet-tempdir
  * jeat
* janet-totp (could vendor parts of janet-checksums)
  * jeat
* janet-walk-dir (1)
  * jeat
* janet-xmlish
  * jeat
* janet-zipper (5)
  * jeat
* jpm-tasks-view
  * jeat
* margaret (2)
  * jeat
* review-janet
  * jeat

* ajrepl
  * jeat
  * janet-last-expression
* janet-last-expression (1)
  * janet-delims
  * jeat
* janet-pcg-random
  * jeat
  * pcg-c
* small-peg-tracer
  * jeat
  * margaret

* babashka-tasks-view
  * clojure-peg
  * janet-zipper
  * jeat
* janet-bounds (2)
  * janet-delims
  * janet-peg
  * jeat
* janet-indent (1)
  * janet-delims
  * jandent
  * jeat
* janet-location-zipper (3)
  * janet-peg
  * janet-zipper
  * jeat
* janet-unwrap (1)
  * janet-bounds
  * janet-delims
  * jeat

* janet-editor-elf
  * janet-bounds
  * janet-indent
  * janet-unwrap
  * jeat

* janet-aliases
  * janet-peg
  * janet-walk-dir
  * janet-zipper
  * janet-location-zipper
  * jeat
* janet-ref
  * index-janet
  * jandent
  * janet-location-zipper
  * janet-zipper
  * look-up-janet-def

* janet-pegdoc
  * jandent
  * janet-peg
  * janet-location-zipper
  * janet-zipper
  * jeat
  * margaret

-------
revisit
-------
* janet-peg (4) - revisit use of lib directory?  janet-delims avoided that approach.
* jandent (3) - still has executable in project.janet, also library bits unclear?

----------
unanalyzed
----------
jell
jipper
jog
jtfm

----
done
----
* index-janet (1)
* janet-delims (4)
* jargon
* jackal

------------
to deprecate
------------
* janet-ex-as-tests (34)