[prev in list] [next in list] [prev in thread] [next in thread]
List: nix-dev
Subject: [Nix-dev] Fwd: Fwd: Wiki is dead
From: Freddy Rietdijk <freddyrietdijk () fridh ! nl>
Date: 2016-02-26 10:05:39
Message-ID: CAOQtOH2asicM957BZ4eZW-1JjN+r3AEn-S7nor=K_GtEiTyGTA () mail ! gmail ! com
[Download RAW message or body]
[Attachment #2 (multipart/alternative)]
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@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@lists.science.uu.nl
> http://lists.science.uu.nl/mailman/listinfo/nix-dev
>
>
[Attachment #5 (text/html)]
<div dir="ltr">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.<div><br></div><div>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?</div><div><br></div><div>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.</div><div><br></div><div>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. </div><div><br></div><div>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.</div><div><br></div><div>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.</div><div><br></div><div><div><br></div></div><div class="gmail_extra"><br><div \
class="gmail_quote">On Fri, Feb 26, 2016 at 9:29 AM, Vladimír Čunát <span \
dir="ltr"><<a href="mailto:vcunat@gmail.com" \
target="_blank">vcunat@gmail.com</a>></span> wrote:<br><blockquote \
class="gmail_quote" style="margin:0px 0px 0px \
0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><span>On \
02/25/2016 01:39 PM, zimbatm wrote:<br> > The output file wasn't exactly \
right, I had to replace `<sect1<br> > id="something">` to \
`<section>` tags and wrap it in a <chapter> tag.<br> <br>
</span>That's because pandoc uses an older version of docbook where some tags<br>
are different. (IIRC I looked a few months ago and it didn't support the<br>
newer one yet.)<br>
<br>
<br>
<br>_______________________________________________<br>
nix-dev mailing list<br>
<a href="mailto:nix-dev@lists.science.uu.nl" \
target="_blank">nix-dev@lists.science.uu.nl</a><br> <a \
href="http://lists.science.uu.nl/mailman/listinfo/nix-dev" rel="noreferrer" \
target="_blank">http://lists.science.uu.nl/mailman/listinfo/nix-dev</a><br> \
<br></blockquote></div><br></div></div>
_______________________________________________
nix-dev mailing list
nix-dev@lists.science.uu.nl
http://lists.science.uu.nl/mailman/listinfo/nix-dev
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic