That is, a documentation that is version controlled and it is explicitly noted with which commit of the project is it in sync with. (Or, to make it more granular, each section would refer to which commit they pertain to. This would breed confusion: e.g., one module depends on another, but the docs show different states of the development.)
Chunks of text would pull in a specific section of code to show what it is referring to. Probably whole lines would be the simplest, but there can be a lot going on in a single line, so explore referring to a specific selection in context. E.g.,
super dense ( code ): with & a lot of => symbols @ where the programmer-didnt-care to make it easier to read))
could be represented with highlighting different section that corresponding to the text explaining it (where VVVs represent the highlighted part, and the dots where it would be "dimmed" with CSS, for example)
This function is blabla
......VVVVVVVVVVVVVV..........................................................................................
super dense ( code ): with & a lot of => symbols @ where the programmer-didnt-care to make it easier to read))
but this part is balabab
......................................VVVVVVVVVVVV............................................................
super dense ( code ): with & a lot of => symbols @ where the programmer-didnt-care to make it easier to read))
[ ] Build in Nix store? How to handle updates? New derivations build on existing ones? Would there even be a point to use Nix store? (For one, it is an immutable store. Right?)
[ ] How to move the docs to a new project commit? Probably a new git branch, then diff referenced lines/sections with the ones at the published commit, and go through them.
[ ] Evaluate existing solutions (and find the right search terms to find them)
[ ] Are the ideas described here related to #1?
[ ] Literate programming?
[ ] temporal ontologies (This is very far ahead; basically a concept can evolve over time, and it may means (slightly) different in future commits. "Equivalence spans" ("the definition of this concept is the same for the following x commits")? Look up ontology engineering about how they deal with ontology evolution. Simple version control?
That is, a documentation that is version controlled and it is explicitly noted with which commit of the project is it in sync with. (
Or, to make it more granular, each section would refer to which commit they pertain to.This would breed confusion: e.g., one module depends on another, but the docs show different states of the development.)Chunks of text would pull in a specific section of code to show what it is referring to. Probably whole lines would be the simplest, but there can be a lot going on in a single line, so explore referring to a specific selection in context. E.g.,
could be represented with highlighting different section that corresponding to the text explaining it (where
VVVs represent the highlighted part, and the dots where it would be "dimmed" with CSS, for example)[ ] Build in Nix store? How to handle updates? New derivations build on existing ones? Would there even be a point to use Nix store? (For one, it is an immutable store. Right?)
[ ] How to move the docs to a new project commit? Probably a new git branch, then diff referenced lines/sections with the ones at the published commit, and go through them.
[ ] Evaluate existing solutions (and find the right search terms to find them)
[ ] Are the ideas described here related to #1?
[ ] Literate programming?
[ ] temporal ontologies (This is very far ahead; basically a concept can evolve over time, and it may means (slightly) different in future commits. "Equivalence spans" ("the definition of this concept is the same for the following x commits")? Look up ontology engineering about how they deal with ontology evolution. Simple version control?