Living documentation

[jcf]

I've been working on a zprint.edn configuration today, and it's hard work reading through the detailed documentation, historic issues and discussions.

A little while ago I started working on a web interface to speed up the process of experimentation and testing, but it never reached a point where I could share because of API rate limits and other complexities.

It occurred to me today that a reasonable solution might be a repo with a little bit of Clojure and some continuous integration.

https://github.com/jcf/zprint-playground

I wonder whether something like this might be worthy of inclusion in zprint itself?

[jcf]

Oh, and the tests are failing because I'm fighting with zprint around how to format a tests.edn file. I'm following clojure-mode and the project's recommendations.

[kkinnear]

FIrst, I think that what you describe might well be a worthy inclusion in zprint. Not that I really understand what you are proposing, unfortunately.

I too have had some thoughts about how to make something that would make configuring zprint more straightforward. Ranging from some tool to analyze code and create a zprint config which would reproduce that output. Which sounds hard, at least if you create rules to look at every single configurable thing in zprint. Perhaps a tool which would allow changing the various option map values in a screen and seeing the results immediately on your own code in another screen.

Anyway, I am certainly open to anything that would make zprint configuration easier. That said, I can't quite tell what your GitHub project actually does, but perhaps I'm just missing something?

As to your second comment, in looking at your test.edn, I see that you don't like the space after the #kaocha/v1 when this file is run through zprint?

I see tagged literals formatted with spaces after them both in:
https://clojure.org/reference/reader#tagged_literals

As well as in the kaocha documentation:
https://cljdoc.org/d/lambdaisland/kaocha/1.87.1366/doc/3-configuration

Which I think you referenced. I don't know about Clojure-mode's approach, as I'm not an emacs user.

Do you really want it to be like this?

#kaocha/v1{:plugins [:kaocha.plugin/randomize]}

At least in my admittedly brief perusal of the kaocha documentation, I sure didn't see that. I was unable to find a single case of the above form of tagged literal in the documentation, but I only looked at one or two pages. Usually they are on different lines, but when they were (rarely) on the same line, there was alway a space?

I must not be correctly understanding what you want here, so it would help if you could explain it to me.

Thanks for thinking of all of this and contacting me.

[jcf]

Anyway, I am certainly open to anything that would make zprint configuration easier. That said, I can't quite tell what your GitHub project actually does, but perhaps I'm just missing something?

The repository I've shared contains a directory of test cases, each containing an input, an output and a configuration. There's an integration test that enumerates the directories and asserts zprint does as expected.

The idea isn't to have zprint work out what's wanted and generate a configuration automatically. More to document what can be done and how to accomplish common tasks.

As to your second comment, in looking at your test.edn, I see that you don't like the space after the #kaocha/v1 when this file is run through zprint?

[...]

I must not be correctly understanding what you want here, so it would help if you could explain it to me.

The Kaocha documentation uses a single line reader syntax, hanging, or forced newlines without indentation.

#kaocha/v1 {:plugins [,,,]}

#kaocha/v1 {:formatter example/format
            :plugins [,,,]}

#kaocha/v1
{:formatter example/format
 :plugins [,,,]}

zprint inserts a single space before the map when on its own line, which is new to me.

#kaocha/v1
 {:formatter example/format
  :plugins [,,,]}

We're into subjective territory at this point, and my intention was to discover what's possible and document it for others in a reproducible way.

If you're open to adding something like a set of executable cases to zprint, I'd be happy to a pull request to get things started.

[kkinnear]

Thanks for clearing up which space was a problem. This is much clearer.

The space that you don't like looks like it is probably a bug to me. There is a config for tagged-literal, and the default indent is 0, which you would expect (or at least I would expect) to probably be what you want. However, I think the code is doing something like thinking that the # is a syntax element so that the :indent 0 shows up with the space you don't want. You can get the look you want now with :tagged-literal {:indent -1} in your options map. You don't want to depend on that long term until I get a chance to look at the code and do some tests to see if what it is doing now is (or could be considered) a bug, or whether it needs to stay as it is. In any case, you can now and will continue to be able to get the look you want, I just don't know if you will need an :indent 0 or :indent -1 to get it long term.

I'm interested in your ideas for a set of examples for zprint. Let me look at it in more detail and I'll get back to you in the next day or two.

Thanks again.

[kkinnear]

I don't have a definitive answer on what I think about the "Living Documentation" idea that I see presented in the repo you reference. I do have some thoughts and, in addition, some minor concerns.

Overview

In general, I am definitely up for somewhere people can go to get lots of examples of what zprint will do with their code. It seems like organizing it with major functions, e.g. defn, let, cond, if, etc. as well a major datatypes: lists, vectors, maps, sets, (strings?) might make sense. I think you have started to do this.

I haven't actually tried to do anything with your repo, I have just been reading the code there. If there is something I should try, please let me know. With, hopefully, some idea of how to try it?

How to organize these examples is an interesting problem.

The "in" and "out" certainly works, and I have done exactly that with some tests for both zprint and lein-zprint. I'm not sure that is the best teaching approach.

You probably don't use leiningen, but I got started with it, and still use it. It has a full-on tutorial, which is great, and it also has a contrived and annotated project.clj file with nearly all of the possible entries filled in. See the project.clj. I found this valuable as I was learning the (rather little) bit of leiningen that I actually use.

Since the actual input to zprint isn't actually interesting (except when demonstrating comment formatting), showing people the "in" and then the "out" may not be all that valuable. This is for classic zprint -- it ignores almost all input white space (except as it
impacts comments). I wonder if a single file for defn, and another for cond, and so on might be useful. One of the (rarely used) zprint features is the ability to change the options map while in a source file. A comment like this:

;!zprint {:list {:indent-arg 2}}

will change the :indent-arg for the rest of the file. There are a series of control keys which let you affect just the next expression, etc. See this for the details of the additional controls.

I'm thinking that a moderately complex defn formatted the default way, then the "community" way, then with increasingly different approaches, might be useful. This would all be one file, and comments could explain what was going on.

One issue is how to best convey the behavior of zprint when using the "community" style. One approach is to intermix that with the default approach in a single file, while another might be to have two directories: the default one, and a community one, with the same code in each but the community one has the community style in all of the examples.

Of course, the input would be important for :respect-nl and :respect-bl examples. It still seems like it would be good to present them in the same file, instead of moving back and forth.

Concerns

One minor but real concern I have is that I would like to keep the number of tools in the zprint project to a minimum. Every tool means that I not only have to learn it, but also to update the repo when it changes, and debug what doesn't work when that happens. And all of that isn't what I prefer to be doing. So if you were expecting to integrate kaocha as part of this set of examples/documenation, I am definitely hesitant about that. I don't love writing tests, but I do it -- 1787 and counting, but I really don't love dealing with testing frameworks.

Next Steps

These are my thoughts do far, please share yours with me, and we will see where we can go from here. Thank you again for bringing this up, and doing the work you have already done to prototype something that looks like it could work.

[kkinnear]

I spent a good amount of time working on the tagged literal indentation issue you brought up (above). I made some code changes so you wouldn't have to use the :indent -1, but it turns out that breaks a bunch of other things. In particular, if the right hand side of the thing didn't flow onto the next line but hung down from the current line, then the indents for the subsequent things in the hang were off by one. There was no good way to fix this. The space (that you don't like) is there because the "#" is handled like a "(" or "[", and is not really part of the tagged literal itself. Anyway, if you use {:tagged-literal {:indent -1}} you will get what you want, the other things will still work, and it isn't a bug and won't go away.