docs: improve readme + nixpkgs section

README.md

@@ -1,32 +1,31 @@
 ## [WIP] dream2nix - A generic framework for 2nix tools
+
 dream2nix is a generic framework for 2nix converters (converting from other build systems to nix).  
 It focuses on the following aspects:
-  - Modularity
-  - Customizability
-  - Maintainability
-  - Nixpkgs Compatibility (not enforcing IFD)
-  - Code de-duplication across 2nix converters
-  - Code de-duplication in nixpkgs
-  - Risk free opt-in FOD fetching (no reproducibility issues)
-  - Common UI across 2nix converters
-  - Reduce effort to develop new 2nix solutions
-  - Exploration and adoption of new nix features
-  - Simplified updating of packages
+
+- Modularity
+- Customizability
+- Maintainability
+- Nixpkgs Compatibility (not enforcing IFD)
+- Code de-duplication across 2nix converters
+- Code de-duplication in nixpkgs
+- Risk free opt-in FOD fetching (no reproducibility issues)
+- Common UI across 2nix converters
+- Reduce effort to develop new 2nix solutions
+- Exploration and adoption of new nix features
+- Simplified updating of packages
 
 ### Motivation
+
 2nix converters, or in other words, tools converting instructions of other build systems to nix build instructions, are an important part of the nix/nixos ecosystem. These converters make packaging workflows easier and often allow to manage complexity that would be hard or impossible to manage without.
 
-Yet the current landscape of 2nix converters has certain weaknesses. Existing 2nix converters are very monolithic. Authors of these converters are often motivated by some specific use case and therefore the individual approaches are strongly biased and not flexible. All existing converters have quite different user interfaces, use different strategies of parsing, resolving, fetching, building with significantly different options for customizability. As a user of these converters it often feels like there is some part of it that suits the needs well, but at the same time it has undesirable hard coded behaviour. Often one would like to use some aspect of one converter combined with some aspect of another converter. One converter might do a good job in reading a specific lock file format, but lacks customizability for building. Another converters might come with a good customization interface, but is unable to parse the lock file format. Some tools are restricted to use IFD or FOD, while others enforce code generation.
+Yet the current landscape of 2nix converters has certain weaknesses. Existing 2nix converters are very monolithic. Authors of these converters are often motivated by some specific use case and therefore the individual approaches are strongly biased and not flexible. All existing converters have quite different user interfaces, use different strategies of parsing, resolving, fetching, building while providing significantly different options for customizability. As a user of such converter it often feels like there is some part of it that suits the needs well, but at the same time it has undesirable hard coded behaviour. Often one would like to use some aspect of one converter combined with some aspect of another converter. One converter might do a good job in reading a specific lock file format, but lacks customizability for building. Another converters might come with a good customization interface, but is unable to parse the lock file format. Some converters are restricted to use IFD or FOD, while others enforce code generation.
 
 The idea of this project is therefore to create a standardized, generic, modular framework for 2nix solutions, aiming for better flexibility, maintainability and usability.
 
-The plan is to integrate many existing 2nix converters into this framework, and thereby improving many of the previously named aspects and providing a unified UI for all 2nix solutions.
+The intention is to integrate many existing 2nix converters into this framework, thereby improving many of the previously named aspects and providing a unified UI for all 2nix solutions.
 
 ### Further Reading
+
 - [Summary of the core concepts and benefits](/docs/concepts-and-benefits.md)
 - [How would this improve the packaging situation in nixpkgs](/docs/nixpkgs-improvements.md)
-
-
-
-
-

docs/nixpkgs-improvements.md

@@ -1,70 +1,92 @@
 ## List of problems which currently exist in nixpkgs
 
-### Generated Code Size/Duplication:
+### Generated Code Size/Duplication
+
+#### Problem
+
 - large .nix files containing auto generated code for fetching sources (example: nodejs)
 - many duplicated .nix files containing build logic
 
-### Update Scripts Duplicaiton/Complexity:
+#### Solution
+
+- dream2nix minimizes the amount of generated nix code, as most of the logic required to build a package resides in the framework and therefore is not duplicated across individual packages.
+
+- If the upstream lock file format can be interpreted with pure nix and is present at evaluation time, then generating any intermediary code can be omitted.
+
+- Once any kind of recursive nix (IFD, recursive-nix, RFC-92) is enabled in nixpkgs, dream2nix will utilize it and eliminate the requirement of generating nix code or storing upsteam lock files
+
+### Update Scripts Duplication/Complexity
+
+#### Problem
+
 - update scripts are largely duplicated
 - update scripts are complex
 
-### Fetching / Caching issues (large FODs):
+#### Solution
+
+- storing `update.sh` scripts alongside packages will not be necessary anymore. dream2nix can generate update procedures on the fly by reading the package declaration.
+- The UI for updating packages is the same across all languages/frameworks
+
+### Fetching / Caching issues (large FODs)
+
+#### Problem
+
 - non-reproducible large FOD fetchers (example: rust)
 - updating FODs is not risk free (forget to update hash)
 - bad caching properties due to large FODs
 
-### Update Workflows:
-- package update workflows can be complicated
-- package update workflows vary significantly depending on the language/fragmework
+#### Solution
 
-### Merge Conflicts for shared dependencies:
-- Due to badly organized shared dependencies, merge conflicts are likely (example: global node-packages.nix)
-
-### Customizability / Overriding:
-- Capabilities vary depending on the underlying solution.
-- UI is different depending on the underlying solution.
-
-### Inefficient/Slow Innovation
-- Design issues (FOD-impurity, Merge Conflicts, etc.) cannot be fixed easily and lead to long term suffering of maintainers.
-- Innovation often happens on individual solutions and are not adapted ecosystem wide
-- New nix features will not be easily adapted as this will require updating many individual solutions.
-
----
-
-
-## How dream2nix intends to fix these issues
-
-### Generated Code Size/Duplication:
-- dream2nix minimizes the amount of generated nix code, as all the fetch/build logic resides in the framework and therefore is not duplicated across packages.
-
-- If the upstream lock file format can be interpreted with pure nix, then generating any intermediary code can be ommited if the upstream lock file is stored instead.
-
-- Once any kind of recursive nix (IFD, recursive-nix, RFC-92) is enabled in nixpkgs, dream2nix will utilize it and eliminate the requirement of generating nix code or storing upsteam lock files
-
-### Update Scripts Duplicaiton/Complexity:
-- storing `update.sh` scripts alongside packages will not be necessary anymore. dream2nix can generate update procedures on the fly by reading the package declaration.
-- The UI for updating packages is the same across all languages/frameworks
-
-### Fetching / Caching issues:
-- dream2nix' upstream metadata translators and always produce a clear list of URLs to fetch
+- the translators of dream2nix always produce a clear list of URLs to fetch
 - large-FOD fetching is not necessary and never enforced
-- large-FOD fetching can be used optionally (to reduce amount of hashes to be stored)
+- large-FOD fetching can be used optionally to reduce amount of hashes to be stored
 - even if large-FOD fetching is used, it won't have any of the known reproducibility issues, since dream2nix does never make use of upstream toolchain for fetching and potentially impure operations like dependency resolution are never done inside an FOD.
 - updating hashes of FODs is done via dream2nix CLI, which ensures that the correct hashes are in place
 - As the use of large-FOD fetching is not necessary and therefore minimized, dependencies are cached on an individual basis and shared between packages.
 
+### Update Workflows
 
-### Update Workflows:
-the workflow for updating packages will be unified and largely independenct of the underlying language/framework.
+#### Problem
 
-### Merge Conflicts for shared dependencies:
-- Having a central set of shared dependencies can make sense to reduce the code size of nixpkgs and load on the cache.
-- To eliminate merge conflicts, the globabl package set can be maintained via a two stage process. Individual package maintainers can manage their dependencies independently. Once every staging cycle, common dependencies can be found via graph analysis and moved into a global package set.
-- The total amount of dependency versions used can also be minimized by re-running the resolver on individual packages, prioritizing dependencies from the global set of common packages.
+- package update workflows can be complicated
+- package update workflows vary significantly depending on the language/fragmework
 
-### Customizability / Overriding:
-dream2nix provides good interfaces for customizability which are unified as much as possible independently from the underlying buildsystems.
+#### Solution
+
+- the workflow for updating packages will be unified and largely independenct of the underlying language/framework.
+
+### Merge Conflicts for shared dependencies
+
+#### Problem
+
+- Due to how shared dependencies are managed, merge conflicts are likely (example: global node-packages.nix)
+
+#### Solution
+
+- Having a central set of shared dependencies can make sense to reduce the code size of nixpkgs, load on hydra+cache.
+- To eliminate merge conflicts, the global package set can be maintained via a two stage process. Individual package maintainers can manage their dependencies independently. Once every staging cycle, common dependencies can be found via graph analysis and moved into a global package set.
+- The total amount of dependency versions used can also be minimized by re-running the resolver, prioritizing dependencies from the global set of common packages.
+
+### Customizability / Overriding
+
+#### Problem
+
+- Capabilities vary depending on the underlying generator/translator.
+- UI is different depending on the underlying generator/translator.
+
+#### Solution
+
+- dream2nix provides good interfaces for customizability which are unified as much as possible independently from the underlying buildsystems.
 
 ### Inefficient/Slow Innovation
-- Since dream2nix centrally handles many core elements of packaging like different strategies for fetching and building, it is much easier to fix problems at large scale and apply  new innovations to all underlysing buildsystems at once.
+
+#### Problem
+
+- Design issues (FOD-impurity, Maintainability, etc.) cannot be fixed easily and lead to long term suffering of maintainers.
+- Innovation often happens on individual tools and are not adapted ecosystem wide
+- New nix features will not be easily adapted as this will require updating many individual tools.
+
+#### Solution
+
+- Since dream2nix centrally handles many core elements of packaging like different strategies for fetching and building, it is much easier to fix problems at large scale and apply new innovations to all underlysing buildsystems at once.
 - Experimenting with and adding support for new nix features will be easier as the framework offers better abstractions than existing 2nix converters and allows adding/modifying strategies more easily.