Add to the design log the set of Choices used

[bmaclach]

As of #2172, the generated design log documents any cases where a user's first choice cannot be used, but it does not document the actual choices used by the generator, meaning a user would have to decipher that information themselves by looking at their choices specification and the default choices.

We should expand the design log by having it document which choice was used for every design variability. Ideas for how to do this are given in: #2172 (comment)

In more detail, we should implement a pass on Choices that defines a design log message for every field in the structure except for any fields specified with a preferentially-ordered list of options. This portion of the design log should be passed to generator and included in the initialization of the _designLog field.

For the three choices represented with preferentially-ordered lists, the chooseConcept, chooseSpace, and chooseODELib functions already have the infrastructure for defining design log messages. They currently define messages in the cases where a conflict is discovered. We just need to update them to also define a message in the "successful" case where there is no conflict. The message should say which UID was matched to which CodeConcept (for chooseConcept), which Space was matched with which CodeType (for chooseSpace), and which ODE library was used (for chooseODELib).

[smiths]

Very well worded issue. Thank you @bmaclach. Given that you have mapped out a path to a solution, is this issue feasible for one of the summer students, or is it better to postpone it for a while?

[bmaclach]

@smiths I think it's feasible for a summer student.

[muhammadaliog3]

@JacquesCarette To convert the choices to Doc's, do you mind if I derive show for a couple datatypes in Choices.hs

[JacquesCarette]

I would actually rather you didn't. We want to make explicit choices (pun intended) when we design our output 'syntax', and we don't want these to be impacted by changes in Haskell versions or code refactorings under the hood. So I prefer that we not use show at all.

[muhammadaliog3]

@JacquesCarette Do you mind if I make all the datatypes an instance of a class that implements show, for example

class ChsShow a where
    chsShow :: a -> String

[muhammadaliog3]

designLog.txt
designLog.txt
Some sample design logs.

[smiths]

I like where you are going with these design log examples @muhammadaliog3. This is useful information to have summarized, without a need to delve through the code to figure it out. (If you are generating these files somehow, there is a typo in how Behaviour is spelled for Physical Constraint.)

[JacquesCarette]

You should seriously think whether String is the correct "output" type here; I think that something closer to Sentence will be preferable in the long term. Something even more Chunk-like might be even better. Though for now, the higher-level language of drasil-printer might do too.

Also, I would prefer RenderChoices over ChsShow.

[muhammadaliog3]

I think @bmaclach would agree with me that declaring sentences, chunks, or a new drasil-printers module would not be helpful here. Instead we should stick to strings (or docs).

Firstly this is drasil-code, so declaring new sentences does not seem to be correct (Drasil code takes ALREADY made chunks and converts them to code chunks).
Secondly all of this possibilities involve moving information related to GOOL choices being moved away from Choices.hs , which may decrease code readability.
Thirdly, at least for sentences, this would require adding new parameters, in particular a chunk database that needs to be passed around everywhere.
Fourthly other design log messages are created and added without chunks or sentences, so if they are able to use strings/docs so should this design log message.

[bmaclach]

Note that though I started the design log by using String, that doesn't mean it's the best option. Also, when @muhammadaliog3 asked me about this, I didn't have the context of some of the above comments. @muhammadaliog3, I think you misinterpreted @JacquesCarette's comment. I don't think he meant to write a new drasil printer, but rather to re-use an existing one (probably the plain one), which makes more sense to me.

In response to the four points you raise:

1. You are correct that, so far, drasil-code has rarely (if ever) defined new Sentences. But that doesn't necessarily mean it can't or shouldn't.
2. Not sure exactly what you mean by this.
3. The chunk database is stored already in DrasilState, and switching to using Sentence should only create one additional place where you need to access the ChunkDB (namely, when you use a drasil printer to render the Sentences for the complete design log).
4. I think if you switch to using Sentences, it makes sense to switch ALL design log messages to use Sentences.

[muhammadaliog3]

@smiths Shoul I add the design log to stable?

[smiths]

Yes, go ahead and add the design log to stable. This is a good idea. If someone makes a change that "breaks" the design log, we want to know about that. I think the design log will continue to evolve, but it would be nice to have the infrastructure in place for the CI now.