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

[Domen Kožar]

Heck, even Apple uses it: https://github.com/apple/swift/tree/master/docs

On Fri, Feb 26, 2016 at 10:05 AM, Freddy Rietdijk <freddyrietdijk at fridh.nl>
wrote:

> 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
>>
>>
>
> _______________________________________________
> 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/c9aef8ca/attachment-0001.html