Rethinking drasil-build

[JacquesCarette]

(A lot of the analysis behind this issue is in #2883; specifically in the 'shallow analysis' for drasil-build and side packages).

drasil-build is "good" in the sense that it has no dependencies, and contains a single "idea": everything to do with Makefiles. The problem with that is that it contains a printer, which thus naturally contains some code duplication as it doesn't reuse any of the work done on any of the other printers.

There are commonalities, as all of them end up using Doc. So drasil-build should have dependencies! The biggest question is: what exactly? drasil-printers is not a good answer. Because it contains both some general printing things, as well as specific printers.

This all leads to thinking that drasil-printers itself should be rethought. At the bottom, drasil-printer-utils can probably be created. But the other printers are more complex. For example, the HTML printer depends on the LaTeX one (and that's good).

[balacij]

There are commonalities, as all of them end up using Doc. So drasil-build should have dependencies! The biggest question is: what exactly? drasil-printers is not a good answer. Because it contains both some general printing things, as well as specific printers.

Just to be clear, I only mentioned the drasil-* dependencies on #2883. drasil-build does have a dependency on pretty (and technically drasil-lang at the moment, but #2881 resolves that). It appears that the majority of the commonality lies in Doc-related creation/functionality.

This all leads to thinking that drasil-printers itself should be rethought. At the bottom, drasil-printer-utils can probably be created. But the other printers are more complex. For example, the HTML printer depends on the LaTeX one (and that's good).

I like this idea a lot. In fact, if we wanted to, we can also re-export functionality from pretty through it as well just so that we have pretty a bit more contained too. Though, that might be unnecessary (I'm not sure of whether or not we will ever want to replace pretty). However, it does sound good to have put the common Doc constructors in a core package, from which all the Doc-printing printers would import.

This all leads to thinking that drasil-printers itself should be rethought. At the bottom, drasil-printer-utils can probably be created. But the other printers are more complex. For example, the HTML printer depends on the LaTeX one (and that's good).

Yes, I agree. As of right now, it seems like a natural step to break it up into packages for the encodings and packages for the language ASTs. Concretely,

drasil-printer-utils/  <- "core" package, all below will depend on this package
drasil-json/
drasil-build/   <- if we don't intend to open up the scope of `build`, perhaps we should rename this to `drasil-makefile`?
drasil-latex/
drasil-html/     <- note that there is no `drasil-latex` dependency here because HTML does not rely on LaTeX to be generated. 
                    However, the SRS document language/Math document language relies on embedding LaTeX in HTML secretly, so that dependency will be formed in `drasil-printers`
drasil-markdown/    <- depends on `drasil-html` (Common Markdown implementations generally also allows raw HTML statements in _near_ arbitrary spots)
drasil-jupyter/  <- depends on `drasil-json`, `drasil-markdown`, `drasil-html`
                       Note: like the above, this would only be for generating arbitrary documents in jupyter, not specifically for the SRS documents

(ASIDE: if this is right, then we might also have to create a package for Doxygen configuration files)

Then, we would have:

drasil-printers/ <- defines the Math document language AST, and creates ways to generate it via the above packages (importing all of them)

Since drasil-printers currently contains the printing AST for a mathematical document language and such, we can just slowly rewrite it to use components from the above packages as we build these packages.

~~Though, I should ask, what do you think the scope of drasil-printers should be? Specifically, should it contain these encodings listed above, or should it be strictly for laying a mathematical document language into these languages (and defining the mathematical document language)?~~ EDIT: This was already answered in https://github.com/JacquesCarette/Drasil/issues/2883#issuecomment-965794758

[JacquesCarette]

I think it's more complex than that. We need to rethink the very notion of 'printer', to make sure that what we have is conceptually correct.

Certainly it does make sense to have separate modules (note: I'm not saying package on purpose) corresponding to each file format. Those are 'secrets' that we don't want to share. And yes, doxygen config files count.

[balacij]

I think it's more complex than that. We need to rethink the very notion of 'printer', to make sure that what we have is conceptually correct.

Sounds good. I guess this will be pending #2896 then?

Certainly it does make sense to have separate modules (note: I'm not saying package on purpose) corresponding to each file format. Those are 'secrets' that we don't want to share.

Sounds good. As of right now, it sounds like we might have a central drasil-softifacts/-artifacts package with multiple "final softifact" printer modules exposed; HTML/etc.

And yes, doxygen config files count.

Sounds good. @peter-michalski might be interested in this discussion too then?

[peter-michalski]

@balacij thanks for looping me into this discussion.