Hi Eelco, >> I've given this a try [1] for the zero-build-failures entry and my >> experience so >> far was: >> >> 1/ How do I actually build docbook? >> => copy doc/default.nix and adjust >> 2/ nix-build is rebuilding GHC 7.8 and 7.10 (for pandoc I think). >> => Wait 2h. >> 3/ GHC build fails [2] >> 4/ We're not using standard docbook but preprocess with XSLT so references on >> the internet don't actually work. > > This speaks in favor of keeping *all* docs in Docbook format so we don't need > conversion tools like Pandoc. Then the manual generation only depends on > xsltproc and docbook-xsl. This is pretty much a hard requirement for the > NixOS > manual because I don't think it's a good idea for the core system to pull in > Pandoc. > > In fact, I think having multiple formats is not a good idea in general, > because > it makes it hard to restructure the manual (e.g., you can't just move a manual > fragment between different sections if they're written in different formats). > And it requires contributors to learn the idiosyncrasies of multiple formats. >
adding another tool to the build chain is something nobody wants. we all agree on that. on the other hand we _must_ look at why contributors are using other tools. docbook is just something that is not known by majority of our community. markdown or such would be much more generally accepted markup, which wouldn't require majority of our community to learn in order to contribute to documentation. current situation is as it is and while we migrate wiki and refactor the manual into something also more suitable for newcomers, we should not change the tools. but as we will move forward with the project i urge you to consider some other markup for documentation which have bigger community adoption. i will learn whatever is decided (even docbook), but i will be very hard to convince others to do as well. i would not like to rush in any decision, but please put some thoughts on this. once you said "until i'm mostly the only one writing documentation we will not change from docbook". i hope that in next months i will be able to show you that documentation is being written/extended by many and many more would contribute if docbook wouldn't be an obstacle. my only goal is to have as good documentation as possible. i'm sure everybody feels the same. i think we can also agree that the only way to keep documentation of a community project like this is that everybody contributes. being docbook or any other markup please consider giving a hand. thank you! -- Rok Garbas - https://www.garbas.si _______________________________________________ nix-dev mailing list nix-dev@lists.science.uu.nl http://lists.science.uu.nl/mailman/listinfo/nix-dev
