[Nix-dev] Fwd: Fwd: Wiki is dead

[Freddy Rietdijk]

It makes sense not to have multiple formats inside a single document. As
Eelco mentioned, it makes it harder to move around fragments, and, as I
experienced now by using the `toDocbook` function, you still end up with
XML errors. Therefore, instead of having to debug errors related to one
format you now have to do so for two.

What format then? Is there a single format that would fit? Should there be
a single format for all our documentation? I actually don't think that's
necessary. No, we better not have multiple formats in a single document.
But how about multiple documents, with each possibly having another format?

We have to think about what type of documentation we need, who each type is
meant for, and actually also who would write that documentation. I think we
are going to need multiple documents, as we have now, but reorganized.

The most relevant one for many of us from the contributor point of view is
going to be a User Guide, which the way I see it, would contain reference
material to specific items in Nixpkgs (modules, functions, ...) and
introductions. Many people should contribute to this guide, and
contributing to it should therefore be sufficiently accessible.

If we now consider formats again then Commonmark is very accessible, almost
everyone knows it. Being a well-specified dialect of Markdown it doesn't
suffer from ambiguity between implementations. However, it still lacks one
important feature: references to sections. You cannot write a manual
without internal references.

Sphinx with reStructuredText has this feature, and many others that are
also covered by Docbook but without the verbosity that comes with it.
Furthermore, the step from Commonmark/Markdown to reStructuredText is
small. Markdown is close to being valid rST.



On Fri, Feb 26, 2016 at 9:29 AM, Vladimír Čunát <vcunat at gmail.com> wrote:

> On 02/25/2016 01:39 PM, zimbatm wrote:
> > The output file wasn't exactly right, I had to replace `<sect1
> > id="something">` to `<section>` tags and wrap it in a <chapter> tag.
>
> That's because pandoc uses an older version of docbook where some tags
> are different. (IIRC I looked a few months ago and it didn't support the
> newer one yet.)
>
>
>
> _______________________________________________
> nix-dev mailing list
> nix-dev at lists.science.uu.nl
> http://lists.science.uu.nl/mailman/listinfo/nix-dev
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.science.uu.nl/pipermail/nix-dev/attachments/20160226/5f7074a5/attachment.html