janet-projects-notes.txt

* make all new things not use project.janet as much as possible?

* try to make pieces of project usable as "single file"

* before "redoing" a project, find whether any projects are being used
  as dependencies.  if it isn't, easier to just change things.

  * use jipper to get at :dependencies value in declare-project in
    project.janet?  is this a bit like querying?

  * also scan for files where something might be vendored?

  * could apply to determine how often each project (of all collected
    projects) is being reused across all collected projects?

    * who-uses command

      * learning about usage of various projects

      * figure out what projects need updating

      * project.janet declare-project based search

      * info.jdn based search

      * filename (optionally checksum?) based search (who-has command?)

  * use as part of figuring out batch updating of some vendored piece
    followed by batch testing?

* random

  * create pre-commit scripts using sh-dsl in various projects

    tried already in:

    * niche
    * small-peg-tracer

    probably makes sense in:

    * jref - dump script
    * pdoc - dump script

  * certain functions are being used by "other projects", perhaps
    these should be documented as being an intended to be used api.
    e.g. gen and par from location.janet.  may be this fits well
    providing a single file in the root of a repository?

    * any way to automate the discovery of which functions are used by
      which projects and how often?

      * used-by command

  * single repository that vendors all / many tools for ease of
    obtaining?

  * picky

    * remote vendoring - git, curl, other?

    * local vendoring (copy jakl.janet to jakl)

    * ordered operations, because sometimes order matters

    * store checksums?

  * patchy - for patching files?  how about something like editscript?

  * snap (input), crackle (transform), pop (output)

  * jed - a bit like sed, but for editing janet and jdn?

* 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.jdn

    (transitioning to .tche.jdn) 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...

* random

  * argument 0 of args might be inspected to change the behavior of a
    janet script.  is there some value in this?  one can make multiple
    symlinks to the same file, each symlink having a different name
    for example.

  * fast-forwarding may have the benefit that the commit hashes used
    to vendor various points along the refine-renaming branch won't
    change so bundle/info.jdn files that used those commit hashes
    won't need to change.

* 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
  * random (for capturing stuff)
  * hidden features
  * semi-recurring tasks
  * pre commit steps

* 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

-----------------------------------------
transition away from git subrepo and jeat
-----------------------------------------

------------------
not so useful atm?
------------------
* can-we-do-better
  * jeat
* clojure-peg
  * jeat
* janet-bits
  * jeat
* index-janet-source
  * jeat
* janet-please
  * jeat
* jpm-tasks-view
  * jeat

* babashka-tasks-view
  * clojure-peg
  * janet-zipper
  * jeat

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

* janet-aliases
  * janet-peg
  * janet-walk-dir
  * janet-zipper
  * janet-location-zipper
  * jeat

--------
consider
--------

* jdoc?

* janet-localpath
  * jeat
* janet-minipbt-transation
  * jeat
* janet-punyishcode
  * jeat
* janet-syntax-highlighting
  * jeat
* janet-tempdir
  * jeat
* janet-walk-dir (1)
  * jeat
* janet-xmlish
  * jeat
* janet-zipper (5)
  * jeat
* review-janet
  * jeat

* janet-pcg-random
  * jeat
  * pcg-c

* 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

--------
archived
--------
* janet-pegdoc - made pdoc which is a replacement / successor?
* janet-ref - made jref which is a replacement / successor?

-----------------------
uses jell - single file
-----------------------
* index-janet (2)
* jackal
* jargon
* jell
* jipper
  - vendor location.janet from janet-peg, but if janet-peg is split up...
* jog
* jref
* lastly (1)
* look-up-janet-def (1)
* niche
* pdoc
* quiche
* small-peg-tracer

--------------------------------
uses jell - not just single file
--------------------------------
* jandent (3)
  - still has executable in project.janet - split off?
  - also library bits unclear?
* janet-totp
  - gh-totp is built using jell - split off?
  - janet-totp dir has lib files
    - base32.janet
    - hmac-sha-1.janet
    - hotp.janet
    - totp.janet

----------------------------------------------------
not single-file - should it be or possibly split up?
----------------------------------------------------
* janet-checksums
  - pieces
    - md5.janet - utils, uint32
    - sha-1.janet - utils, uint32
    - sha-2.janet - utils, uint32, uint64
    - uint32.janet
    - uint64.janet
    - utils.janet
  - split off uint32 and uint64 into own project(s) and vendor?
    - then split off md5 on its own
    - then split off sha-* elsewhere
  - what about utils?
* janet-peg (4)
  - isn't a single file artifact - split?
    - location.janet - used by jipper.janet
    - bounds.janet - used by janet-bounds
    - rewrite.janet (uses grammar.janet) - used by hiccup lexer
    - extras.janet - not really used elsewhere?
  - revisit use of lib directory?
  - if starting new project, consider renaming things (e.g. jg)
  - rewrite.janet can be built via jell

-----------------------------------
doesn't use jell but is single file
-----------------------------------
* dalimit (?)
* janet-etags
* janet-jsonish
* margaret (2)
  - nicer if meg.janet was directly in root directory

----------
to archive
----------
* janet-delims (4) -> dalimit
  - actually has a janet-delims/init.janet file but
    probably doesn't need?
* janet-last-expression -> lastly

------------
transitioned
------------
* ajrepl

--------------------
breaking out pieces?
--------------------

----------------
to remove use of
----------------
* janet-ex-as-tests (34)
* git subrepo