[Nix-dev] Fwd: Wiki is dead

[Anderson Torres]

2016-02-23 19:22 GMT-03:00 zimbatm <zimbatm at zimbatm.com>:
> I started writing some docbook. Maybe I will get used to it but writing
> `<datasetlist><listitem>foobar</listitem></datasetlist>` is way more painful
> that `* foobar` in markdown. Especially in writing I think it's important to
> be able to move text around without too much overhead so that text can be
> reworked until it feels right.
>
> Thanks god there is pandoc so I can keep submitting docbook while writing my
> cozy markdown :)
>

I think the same. Docbook is extremely verbose and full of ugly XML
tagging, I don't like it.
Also, it is easier to use a lightweight markup as pandoc or Asciidoc.
The learning curve is smoother than XML, and it can be easily
converted to Docbook or anything we like.

But, about documentation: what do you think on a "NixOS Handbook",
like the FreeBSD Handbook? We can reach a wider audience if we use
such a style of handbook.

>
> On Tue, 23 Feb 2016 at 21:29 Vladimír Čunát <vcunat at gmail.com> wrote:
>>
>> On 02/23/2016 12:18 PM, Rok Garbas wrote:
>> > docbook is just something that is not known by majority of our community
>>
>> My personal opinion is that this is mostly an excuse. It's a XML subset
>> and everyone should know at least a bit of (X)HTML or similar stuff.
>> Note that for almost all docs we use ~10 types of tags and the format is
>> by itself human-understandable. (Typically it's enough to copy fragments
>> from a few paragraphs around and edit to have the new content. We might
>> also compose a list of tags with examples on what we typically use them
>> for.)
>>
>> In any case, once the HQ content is produced, conversions are easy
>> enough; regardless of doing them at build-time as the trend is now or at
>> commit-time (if we decide later to unify to docbook, for example).
>>
>> --Vladimir
>>
>>
>> _______________________________________________
>> nix-dev mailing list
>> nix-dev at lists.science.uu.nl
>> http://lists.science.uu.nl/mailman/listinfo/nix-dev
>
>
> _______________________________________________
> nix-dev mailing list
> nix-dev at lists.science.uu.nl
> http://lists.science.uu.nl/mailman/listinfo/nix-dev
>