On 25-09-2015 12:58:14, Eelco Dolstra wrote: > However, an alternative to relicensing is to combine it with a move to a > different Wiki, which many people have wanted in the past anyway. For > instance, > we could set up a GitHub wiki, and people could copy their own contributions > to > the new wiki. The new wiki should of course have a license from the start.
Well, if we start this discussion here: In fact, I asked the licensing question _because_ I'm working on an alternative wiki for nixos. The whole point of my question is that I want to be sure that I can use contents from the official wiki. I didn't want to ask for permission that early, so I just asked about the license of the wiki and docs, but well... as we are at that point in our discussion now... Anyhow, I strongly disagree with your proposal to use the github wiki. It is _far_ to complicated to keep things organized in there. Subpages and all this stuff. Of course, I did some investigation on the subject. I tried several wiki software packages. Let me elaborate: My requirements: 1. git. I want to have the content (and, if possible, all metainformation like page templates and so on) tracked in git. Contributions would go through git as well. So why is that? I can already hear voices argueing about this. Yes, it is a bit of an obstacle if you are only able to contribute via a pull-request procedure. BUT there are some big pro points: 1) Contributions are reviewed. One can't argue with that. People can actually review contributions before they go online. This keeps up the quality of the wiki and automatically protects it against abuse. I believe that this becomes more important as the wiki (or the number of people involved in nix{wiki, os, pkgs, }) grows. 2) Having a long(ish) running process for adding/editing content of the wiki keeps people from "just pasting this in the wiki somewhere". I believe that if there is a bit of a process behind all this, it keeps people from just dropping in content. Some more pro points which are not that major as the ones above: 3) git-log. You can log the history of single articles or even topic-trees (speaking of subdirectories). You can do the former with, for example, MediaWiki. But not the latter, I guess. 4) git-blame. You can actually see what happened where. And yes, you can do this wiki MediaWiki, too. But tell me: How often have you actually done this? Of course there are more points. Let me summarize them: git. 2. One-click contributions (not really, actually). I want user to be able to do contributions with only a few commandline calls. Idea was that a user only needs to fork the repository, edit the contents of some Markdown page and rebuild the wiki to review. One-click contributions like in a MediaWiki instance is not what I want, as described in 1. 3. Local clone. Well, git gives us the opportunity to run a _full clone_ of the wiki locally. You cannot do this with MediaWiki (maybe you can, but not _that_ easy). Okay, so here are the things I reviewed: - gitit (Haskell, integrated with nixos) - gollum (ruby, actually the software that powers the github wiki) These are the only options I found for a wiki with git as backend. gitit ----- Gitit is awesome. It works great and is fast. Anyways, it has some issues. First, it does not track templates. You can write page templates, but they are not tracked in git. I had to do some nasty hacks for this. The templates cannot be used to generate, for example, warning blocks: { warning_block "Do not install this in User env" } (Just an example, not the actual markup for templates) The above is _not_ possible with gitit. Kinda dealbreaker for me. There are few plugins for gitit. I failed installing even the simplest of them using nixos tools. Also, gitit is not actively maintained. There is an attempt to rewrite gitit (called gitit2 actually) which is even less maintained. Running not-that-well-maintained software is ... problematic at least. gollum ------ Powering the github wiki, relatively actively maintained... Good idea I thought. But: - No templates - No Plugins - Not even custom style (you can do it, but I couldn't find documentation about it) Also, gollum is great for single-user use. I use it locally to keep some notes. It works great. But I fear distributing it and merging around. It is just not the way it is supposed to work, I think. And, of course, it is rather complicated to keep track of where things are actually stored. You can mess up really bad (I already did) by just naming a _folder_ like a _file_. All in all, it did not _feel_ that good using it. So these were my options on wikis with git as backend. There are no others (well, there is a perl-thing, I didn't test this one, actually). Sadly, I couldn't satisfy myself with these options. So, an idea came up - why not using static pages for all of this? If you want to do contributions via git, you can use github. If one want to host it, one can use github pages and build it with travis-ci. These things are documented and they _work_ for other people, so why not for a wiki? To be able to build pages with travis-ci and github pages, one needs a static site compiler. I used a static site compiler which is actively maintained and developed and actually supported by github, because they use the same for github pages: Jekyll. I cannot build the page itself with github pages, because they do not allow plugins. But one can build with travis and push to the github-pages branch, there's a lot of documentation about it. Things like plugins, custom themes, templates and all this stuff are supported (more or less) out of the box. I started to write this as a template for a wiki and I plan to fork it and create a wiki for nixos out of it. Well, enough talking, here is the codebase: https://github.com/matthiasbeyer/wiki.template/tree/transform-to-jekyll (branch "transform-to-jekyll" because I actually started it with "nanoc", but jekyll is a much better option) The idea of the template is that one can fork it, delete the content which is in the wiki right now (documentation on how to use it) and start putting content in it. Everything else has to work out of the box. I used a jekyll-site template as you can see in the commit history. I'm not finished yet, some things are missing by now: - Non-Markdown pages (textile, for example) Don't know whether this is possible or needed. - Some plugins are included as source files, not as gems. Pull requests to the actual plugins are pending and I hope I can integrate them as gems asap. - Latex-Formulas (not tested yet). Not required for a nixos wiki, I think. - Style is not finished yet. I'm not a designer, though I think it looks rather pleasent for my limited designing skills. I'm not sure whether I want to have a discussion about it yet, but as Eelco mentioned quitting the old wiki and creating a new one, I had to post this to the mailing list. I hope we can have a calm and objective discussion about this now. I'm able to argue with people, but I don't like cursing, fighting or anything. Keep it objective, please! I'm rather confident I will do this, whether the nixos community agrees or not, but I would really love to have a collaborating atmosphere about this, so we can pull this together and cooperate. -- Mit freundlichen Grüßen, Kind regards, Matthias Beyer Proudly sent with mutt. Happily signed with gnupg.
pgpiwoDyuLgJw.pgp
Description: PGP signature
_______________________________________________ nix-dev mailing list nix-dev@lists.science.uu.nl http://lists.science.uu.nl/mailman/listinfo/nix-dev