[Nix-dev] NixOS-Wiki alternative. Was: What license does the content of the nixos wiki and the manuals have?

[Matthias Beyer]

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.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 819 bytes
Desc: not available
Url : http://lists.science.uu.nl/pipermail/nix-dev/attachments/20150925/9a62ab0d/attachment.bin