Nixpkgs: Getting more developers to contribute to Nixpkgs documentation

[domenkozar]

In order for documentation to be written by different contributors, it has to be trivial to write it. I believe docbook is not appropriate for such task. Markup has to be easy and we don't need something very semantic.

I've made an experiment and converted current docbook to RestructuredText (using pandoc) and generated html documentation with Sphinx.

See http://static.domenkozar.com/nixpkgs-manual-sphinx-exp/

For examples of documentation see https://cryptography.io/en/latest/ or http://phpsecurity.readthedocs.org/en/latest/ (note "Edit on Github" button)

Notes:

• some by-hand correction were made (and some typos still need to be fixed)
• Sphinx supports language domains and we could have inline documentation
• conversion was made manually, we could integrate that to build man/pdf/epub/html with Nix for each build

[edolstra]

To be honest, I have a dislike for all markdown/wiki-like documentation languages. They're superficially attractive, but:

• They tend to break down if you try to do something slightly complicated, like having a list item with multiple paragraphs or a code example in it.
• You never know which characters have a special meaning in a particular position at a particular time of day. E.g., you write an identifier like _foo_bar_, and suddenly foo becomes italicised - but not bar. But if you write foo_bar_, nothing happens. So it's a minefield: every character I type might end up being interpreted in a way I didn't intend, and my editor won't tell me.

They're "do-what-I-mean" languages, trying to assign semantic meaning using ad hoc rules typically implemented by a bunch of regexes. By contrast, with DocBook, for all its verbosity, there are never any surprises: there are only two special characters, and if you screw them up, you'll notice right away. You never have to wonder how you can nest X in Y.

And with good editor support (e.g. nxml-mode in Emacs), the verbosity is not much of an issue, since you get tab completion. In fact, Emacs will even tell you which elements are allowed in the current context, which is a lot nicer to me than Markdown-like languages, where I always have to google which particular combination of "indent X spaces and add some magic characters" does the trick.

I'm also a bit skeptical about claims that people would suddenly start writing documentation if only they didn't have to write <para>. People don't write documentation because most people don't like writing documentation. We do already have a place where people can easily contribute, namely the wiki. Good Wiki articles should probably be added to the manual eventually.

Finally, practically speaking, DocBook already gives us what we need: HTML, PDF, manpages, etc. The whole toolchain is in place so I'd prefer not to mess with it unless there is a really compelling reason. Sure, the HTML could look better, but that's a matter of slapping some CSS on it.

[offlinehacker]

I agree with you @edolstra, but there's only one issue. There are plenty
more programmers writing markdown as docbook. People will write
documentation if you change format that they understand. There's also
another problem, a lot of opensource programmers don't like xml-ish
formats. There's also a question, why not (simply) use both, docbook and
markdown, if we can generate for both, i don't see a problem. Inline docs
support is also needed.

On Sun, Mar 16, 2014 at 11:47 AM, Eelco Dolstra [email protected]:

To be honest, I have a dislike for all markdown/wiki-like documentation
languages. They're superficially attractive, but:

-

They tend to break down if you try to do something slightly
complicated, like having a list item with multiple paragraphs or a code
example in it.
-

You never know which characters have a special meaning in a particular
position at a particular time of day. E.g., you write an identifier like
_foo_bar_, and suddenly foo becomes italicised - but not bar. But if
you write foo_bar_, nothing happens. So it's a minefield: every
character I type might end up being interpreted in a way I didn't intend,
and my editor won't tell me.

They're "do-what-I-mean" languages, trying to assign semantic meaning
using ad hoc rules typically implemented by a bunch of regexes. By
contrast, with DocBook, for all its verbosity, there are never any
surprises: there are only two special characters, and if you screw them up,
you'll notice right away. You never have to wonder how you can nest X in Y.

And with good editor support (e.g. nxml-mode in Emacs), the verbosity is
not much of an issue, since you get tab completion. In fact, Emacs will
even tell you which elements are allowed in the current context, which is a
lot nicer to me than Markdown-like languages, where I always have to google
which particular combination of "indent X spaces and add some magic
characters" does the trick.

I'm also a bit skeptical about claims that people would suddenly start
writing documentation if only they didn't have to write . People
don't write documentation because most people don't like writing
documentation. We do already have a place where people can easily
contribute, namely the wiki. Good Wiki articles should probably be added to
the manual eventually.

Finally, practically speaking, DocBook already gives us what we need:
HTML, PDF, manpages, etc. The whole toolchain is in place so I'd prefer not
to mess with it unless there is a really compelling reason. Sure, the HTML
could look better, but that's a matter of slapping some CSS on it.

Reply to this email directly or view it on GitHubhttps://github.com/NixOS/nixpkgs/issues/1960#issuecomment-37753960
.

[mmerickel]

I'm not interested in contributing docs at the moment as I'm still happily attempting to read them (thanks mostly to @iElectric) but I do have a lot of experience fighting with these Markdown languages and feel your pain. I just wanted to mention a couple points. Sphinx is ubiquitous in the Python community, used for all of the Python core documentation and almost every open source project I've seen. Pyramid itself, which I contribute, has over 700 pages of Sphinx docs that have been rendered to a published book as well as PDFs, ePubs and HTML. Finally, and most importantly to me, is that Sphinx is much more powerful than Markdown and is not nearly as coupled to the HTML representation. There are multiple contexts which can be an issue (which my editor, vim, helps me with) but it does not suffer from problems such as placing code examples in lists. Anyway excuse me, I just wanted to chime in since I use Sphinx all the time but can't stand a lot of the new projects these days using Markdown. :-)

[peti]

Thanks to the wonders of Pandoc pretty much all of the popular wiki'ish mark-up formats can be converted from one to the other without loss of information.

Personally, I like the extended Markdown from Pandoc because it has very good support for rendering maths. I don't think any other tool can do that, but I might be wrong.

[vcunat]

Yes, I've also found pandoc very useful over the years. The ambiguities can e.g. be resolved by the fact that you can just splice HTML inside pandoc's markdown. (Side note: I do like the maths rendering, but I guess we won't utilize that around nixos.org ;-)

[domenkozar]

I'm proposing RestructuredText over Docbook for practical reasons to increase and encourage contributions to documentation. Wiki has a lot contributions from the community as opposed to manual, exactly for that reason: it's easy to add "docs". See also http://yannramin.com/2011/06/22/semantic-end-user-documentation-docbook-or-sphinx/

RestructuredText is implemented as finite state machine backed by regexes

In my experience, https://readthedocs.org/ (free, hosted Sphinx documentation) has raised awareness for documentation and it proved that writing documentation depends on culture and low entry point.

As far as learning curve goes: I'd say you can learn RestructuredText primer in way less time than docbook, but that's hardly measured objectively.

[shlevy]

IMO we should separate two questions

1. What format should our documentation be written in?
2. How can we teach and encourage devs to write it?

I don't really have any answers there (though I share @edolstra's concerns about Markdown et. al.), but I see those two questions cropping up here.

[offlinehacker]

Markdown might not be best solution here. As @iElectric said restructedtext
would be best fit.
On Apr 5, 2014 7:44 PM, "Shea Levy" [email protected] wrote:

IMO we should separate two questions

1. What format should our documentation be written in?
2. How can we teach and encourage devs to write it?

I don't really have any answers there (though I share @edolstrahttps://github.com/edolstra's
concerns about Markdown et. al.), but I see those two questions cropping up
here.

Reply to this email directly or view it on GitHubhttps://github.com/NixOS/nixpkgs/issues/1960#issuecomment-39645405
.

[domenkozar]

@shlevy sadly the format has big correlation with number of contributions. It's hard to measure that, but docbook takes away the motivation from people doing one-time contributions.

I agree docbook is technically superior to RestructuredText, but is that really important for our documentation? Are we willing to sacrifice those few tiny technical details for sake of approachability?

[offlinehacker]

I'd had a few cases where i would write docs for a few things, but again i don't really feel like using docbook. Currently i have two sane options:

• Write wiki "documentation"
• Don't write documentation at all

There's one option, if we write quite a lot of new restructuredText documentation in a short period of time we change documentation to restrucutredText. It's a democratic solution, what do you think?

[vcunat]

In your place I would try this:

• Write it in whatever format+editor (that obstructs your writing the least).
• Then just convert it, e.g. by pandoc.
• Perhaps check it and hand-edit a few places, but these are nitpicks, as the content is what matters most.

[offlinehacker]

It would be cool if someone would share pandoc conversion instructions,
@iElectric?

On Thu, Jun 19, 2014 at 9:24 AM, Vladimír Čunát [email protected]
wrote:

In your place I would try this:

• Write it in whatever format+editor (that obstructs your writing the
  least).
• Then just convert it, e.g. by pandoc.
• Perhaps check it and hand-edit a few places, but these are nitpicks,
  as the content is what matters most.

—
Reply to this email directly or view it on GitHub
https://github.com/NixOS/nixpkgs/issues/1960#issuecomment-46530950.

-----BEGIN PGP PUBLIC KEY BLOCK-----
Version: GnuPG v1.4.11 (GNU/Linux)

mQENBFEY1PEBCADPOfERF2wo4qeoq9L1m2z4pKfWqNd4B6BsoFUWPNd7BXmY+9JG
jJddSkmYobWec7XjAFTBL0Xbttt+rK9SIED2dCOmU1FYMQElhGlM3PNA3kaiQFeV
ijgH318GCfZzDd0dWa5TN/IshVeWXwgngsIEmZTVf1VSeb3eO3B8Fxe3zsSLUq0b
71MmU5eLVP9pMkm5V5BTYp+lV70FIekKygkKq+uTDo1csWUatbs4Qvgv37Bymy2t
oTwOBXGoinQk5N/6asR1jWs3vKv0L0SruoZy/kEG/jXb4l2OZUP85EVMganYKouE
OchVmcmhBdWV+t3HK4r2ATfyEcMRzvzSflA1ABEBAAG0Jkpha2EgSHVkb2tsaW4g
PGpha2FodWRva2xpbkBnbWFpbC5jb20+iQE+BBMBAgAoBQJRGNTxAhsDBQkB4TOA
BgsJCAcDAgYVCAIJCgsEFgIDAQIeAQIXgAAKCRD6Zxi5hZclKnXNCACLOKa8abQp
eTWv9SXUwC7LVM5pP2mXcgn+Ipqr6YWBdLx4Iij0YlvUok9VeKvwTpUlT+cx++o3
wCM3AYrUyJE+zrtw49lInUmutz9seqJLU895oq+D+UuGoORrLBpEZrYR5f83uUmQ
E3Z1ZmWrNGXYtITWDtVZD/KauMF2nkPcmy/XaYXhd4WHD81DGNlKtGAHig6A3Phc
8Mr0A4yLDeRQJm8lCFEsxMJUNTupgY+ybbsMfVGx1gQvvGOTioV8CLCoRchUCCcm
YPArFg40KzIDSNjwdo9EVZDnlPx1hbOppfQydxP+JVnZsqoYmVY4UhIWi/NfOl3V
UMjl338INW1zuQENBFEY1PEBCADRSIfelOMjaTH7IfpMFFUc5Gys//njFnW9QAUg
wyfs2AFxUp6vKQ7nxXQiJXVhKTwe9iqo+oGxaHp4AeTjC7vXsfMuF5g5lfttbAo3
YEobEe6OG5so41nbwan6SyeIIQ2AmQqJBw8TKKMSec2qUN0Pw7iZRs0o9uJM/obG
DPsAsMOQgNLxJyMCP7X2jBtDXxkMFVHMmk50Tl3h3Fi9qWuNxgTXjs0tUvKkXiu2
Pco952jnm7HpCIKBek2pqR/UJXXb5qxy5G6Lc0qaMWZ5GKnSMTJmTY6Xl44EnaLK
zh0rqgF9qpoWck470ZbiGASMtB008hy2l0cyxUfvDaS3tY4hABEBAAGJASUEGAEC
AA8FAlEY1PECGwwFCQHhM4AACgkQ+mcYuYWXJSoT6AgAkvzvC0EGmeCR3cn9O3Gf
yG00Kqk9/1gJvlphis7AAce8iUgU+4xd94Vp0u8rghpdy88xKN5lF1W2YZQmmBaf
AVe6b7TOg6kxc3GKkVsWDxNyQKkpB46BwefIGaSljH7502X9aEWosrqWyJJNYCtt
QDit4BysX0Ww3Ka5Rx6ZFhC9ybPKoW2i8JwpyBaXDt7R2k+PC/ClBf9qzL+sb2es
zh/zCMVKNdm8KUITHU/5lgn2qZpUFZwiASPCMGGFP9u8g6UKeUTYTPD+GWaHIW63
RAgNIAffxx0M1r3P/2ipkAdI3NX/1iBKDQNG8Odsf+BswFKrNCnyUDdLPvJAhODS
gw==
=tmrm
-----END PGP PUBLIC KEY BLOCK-----

[vcunat]

$ pandoc foo.md -t docbook You can optionally specify -f myFormat if it doesn't detect correctly (filename-based detection IIRC).

[vcunat]

A quick intro is on the web http://johnmacfarlane.net/pandoc/README.html#using-pandoc.

[third3ye]

Me and chexxor have been discussing this for a while. We eventually came to the conclusion that we had to try a wiki solution that has a git mechanism for editing or adding more wiki pages. We eventually wanted to try gitit, since it used pandoc to allow the user to use pretty much whatever dang text markup format they wanted.

By using a git solution we could create a hydra processes that prepackages a specific gitit instance, that fetches it's wiki structure as a nixpkgs package. So the developers could then opt out of using a web-browser entirely and stick to their favourite text editor and the nixpkgs system. Also, since it's a dang nixpkgs package, you could install the wiki on a secure intranet with no access to the internet (please... can I haz this? I needs this :3).

I think this is the easiest way to bridge the gap between development and documentation. I wouldn't suggest making wiki a part of NixOS declarations, as we don't want to bloat up the definition sets to much, but to at least try a way of making it easier for both developers and users to update and add to the man pages.

Credit to Chexxor for research. He has been focusing on restructuring the wiki for some time now and has a lot of good stuff in the works on https://nixos.org/wiki/Main_Page_B that's taking a new approach to how the wiki is structured. But this kind of restructuring requires feedback from developers, especially at this point in time when there are a lot of new users (like me) and also a lot of new changes being made to the general approach behind nix (that's you guys).

So, big boy pants time: do you want to give developers the ability to post wiki docu in whatever text markup they want, through the process of which they already avidly use to post packages and updates to also post updates and new pages to the wiki?

http://gitit.net/

[vcunat]

Yes, without looking deeper, moving our wiki to gitit-managed repo sounds good.

I didn't know it allowed to edit in any markup you like. Is it even if the article was originally written in another one?

[offlinehacker]

That looks cool, so do you suggest using gitit only for wiki or also for
docs?
On Jun 19, 2014 3:05 PM, "Vladimír Čunát" [email protected] wrote:

Yes, without looking deeper, moving our wiki to gitit-managed repo sounds
good.

I didn't know it allowed to edit in any markup you like. Is it even if the
article was originally written in another one?

—
Reply to this email directly or view it on GitHub
https://github.com/NixOS/nixpkgs/issues/1960#issuecomment-46557292.

[goodwillcoding]

+1 on rST and Sphinx. I would help port it if this was decided.

[vcunat]

Docs has been discussed many times; I don't remember any agreement on conversion, and it seems unlikely ATM (I myself e.g. see little benefit in switching the format).

[third3ye]

We've discussed the docs via mailing list and the consensus is that there should be a clear and definite difference between a manual and a wiki. One should be set in stone and the other shouldn't. The general open source software wiki is ment for certain aspects that may not fit in to a manual, things that maybe subject to immediate change.

I personally don't mind the idea of a central docu/wiki solution (perhaps certain sections should only subject to change when a major overhaul occurs), but then again the distinction is that the manual is ment to be very pedantic in it's approach, to teach people about the whole process of what nix does in the background as well as the commands and the explanations of what they do.

It would be a pain to everytime "parse" all that text with your eyes if you just wanted to quickly install nixos via terminal and needed to read the procedure quickly just to be sure. That means that wiki/Installing_NixOS could be much more brief with the specifics and give you some hints and tips on what to do with the install, how to do it in several methods, test unstable settings, and so forth (beneath the "Quick Install" guide, ofc).

Therefor it is definetly beneficial to keep them both separate. Plus we get to complain to the authors when somethings wrong, instead of changing it our selves. Get those jabbing sticks ready...!

[third3ye]

I got this idle VPS that I'm not directly using (yet). It's also pretty much disposable at the click of a button. Chexxor setup gitit and I'm going to setup git one of these days to test it's capabilities, and also, try to create an initial mockup of a wiki structure for Nix(OS).

If you want access or to try something else let me know; this version was installed by Chexxor and doesn't have git working yet. However, there is some room there for people to try out and see if pandoc works to their expectations. So register, try, comment and let me know what you think.

http://dreamsindigital.net

[wmertens]

I like it, MediaWiki is annoying for writing about code.

The true test though is if you can import the old wiki into it...
On Jun 20, 2014 5:00 PM, "third3ye" [email protected] wrote:

I got this idle VPS that I'm not directly using (yet). It's also pretty
much disposable at the click of a button. Chexxor setup gitit and I'm going
to setup git one of these days to test it's capabilities, and also, try to
create an initial mockup of a wiki structure for Nix(OS).

If you want access or to try something else let me know; this version was
installed by Chexxor and doesn't have git working yet. However, there is
some room there for people to try out and see if pandoc works to their
expectations. So register, try, comment and let me know what you think.

http://dreamsindigital.net

—
Reply to this email directly or view it on GitHub
https://github.com/NixOS/nixpkgs/issues/1960#issuecomment-46687986.

[linquize]

https://github.com/jgm/gitit

[third3ye]

Me and _deepfire have been getting gitit and git to work and they both work together perfectly. Git users can commit & clone and web users can add & edit. There is however one problem in way of implementation. Gitit generates a user password file called gitit-users, which is structured thusly:

[("user",User {uUsername = "user", uPassword = Password {pSalt = "...", pHashed = "..."}, uEmail = "[email protected]"})
,("anotherUser",User {uUsername = "anotherUser", uPassword = Password {pSalt = "...", pHashed = "..."}, uEmail = "[email protected]"})

I'm told by _deepfire that happstack calls the authUser mechanism to generate and parse the user files. So how does one make getting access to the git mechanisms as easy as registering on the gitit instance or possibly via git-shell in interactive mode, and then having access to both as one approach is made (to keep a consistent user database)?

I'm going to ask the lead developer of gitit if there is any plans to add ssh keys to the user registration, as right now me and _deepfire are at a stand still, since authentication is a pretty big deal. Alternatively the whole thing is written in Haskell and can be used as a library. If someone who actually works with the git repos for nixos (who knows procedure) could suggest the best way of setting up user authentication between gitit and git (sshd) we could get this experiment back on wheels again.

That URL again:
http://dreamsindigital.net
(Request ssh account for git access, if you want to test it out)

[deepfire]

Here's a preliminary import of the wiki:
https://github.com/deepfire/nixos-wiki

Here's the modded hw2gitit, which was used to obtain the above:
https://github.com/deepfire/hw2gitit

Simply ghc-ing it and running the binary produces a git repo equivalent to the above.

The import mechanism will require additional tuning, most likely.

[domenkozar]

Closing, we're sticking with manuals for now.

[domenkozar]

Just want to make it super official that I still despise docbook toolchain.

Following error message is nothing but useless:

$ nix-build -A manual pkgs/top-level/release.nix
these derivations will be built:
  /nix/store/bl57qvl6xy8qbsaa7nmkwd38h1h42yqy-nixpkgs-manual.drv
building path(s) ‘/nix/store/sn49zlm4yxc93ly75nsylz8b1hx2sd9v-nixpkgs-manual’
building /nix/store/sn49zlm4yxc93ly75nsylz8b1hx2sd9v-nixpkgs-manual
manual.xml:7: element para: Relax-NG validity error : Did not expect element para there
manual.xml:16: element section: Relax-NG validity error : Did not expect element section there
manual.xml:16: element section: Relax-NG validity error : Element chapter has extra content: section
manual.xml:4: element info: Relax-NG validity error : Element book has extra content: info
manual.xml fails to validate
builder for ‘/nix/store/bl57qvl6xy8qbsaa7nmkwd38h1h42yqy-nixpkgs-manual.drv’ failed with exit code 3
error: build of ‘/nix/store/bl57qvl6xy8qbsaa7nmkwd38h1h42yqy-nixpkgs-manual.drv’ failed

[7c6f434c]

Just want to make it super official that I still despise docbook toolchain.

Following error message is nothing but useless:

$ nix-build -A manual pkgs/top-level/release.nix
these derivations will be built:
 /nix/store/bl57qvl6xy8qbsaa7nmkwd38h1h42yqy-nixpkgs-manual.drv
building path(s) ‘/nix/store/sn49zlm4yxc93ly75nsylz8b1hx2sd9v-nixpkgs-manual’
building /nix/store/sn49zlm4yxc93ly75nsylz8b1hx2sd9v-nixpkgs-manual
manual.xml:7: element para: Relax-NG validity error : Did not expect element para there
manual.xml:16: element section: Relax-NG validity error : Did not expect element section there
manual.xml:16: element section: Relax-NG validity error : Element chapter has extra content: section
manual.xml:4: element info: Relax-NG validity error : Element book has extra content: info
manual.xml fails to validate

At least we know the line number…

What branch is it?

[domenkozar]

No, the line number is completely wrong. manual.xml just includes xinclude statements........

[domenkozar]

Branch python/docs, nix-build -A manual pkgs/top-level/release.nix to reproduce.

[domenkozar]

it's somewhere in following section:

<variablelist>
  <title>
    Extra parameters supported by buildPythonPackage.
    Everything from mkDerivation function is supported.
  </title>

  <varlistentry>
    <term><varname>namePrefix</varname></term>
    <listitem>
      Prefix prepended to <varname>${name}</varname> parameter.
      Defaults "python3.3-${name}" for Python 3.3, etc. Set it to
      <literal>namePrefix = "";</literal>
      if you're packaging an application or a command line tool.
    </listitem>

    <term><varname>disabled</varname></term>
    <listitem>
      If <varname>true</varname>, package is not build for
      particular python interpreter version. Grep around
      <filename>pkgs/top-level/python-packages.nix</filename>
      for examples.
    </listitem>

    <term><varname>setupPyInstallFlags</varname></term>
    <listitem>
      List of flags passed to setup.py install command.
    </listitem>

    <term><varname>setupPyBuildFlags</varname></term>
    <listitem>
      List of flags passed to setup.py build command.
    </listitem>

    <term><varname>pythonPath</varname></term>
    <listitem>
      List of packages to be added into $PYTHONPATH.
      Packages in pythonPath are not propagated into user environment.

      TODO: this could be removed, is there a use case?
    </listitem>

    <term><varname>preShellHook</varname></term>
    <listitem>
      Hook to execute commands before <varname>shellHook</varname>.
    </listitem>

    <term><varname>postShellHook</varname></term>
    <listitem>
      Hook to execute commands after <varname>shellHook</varname>.
    </listitem>

    <term><varname>distutilsExtraCfg</varname></term>
    <listitem>
      Extra lines passed to <varname>[easy_install]</varname> section of
      <varname>distutils.cfg</varname> (acts as global setup.cfg
      configuration).
    </listitem>
  </varlistentry>

</variablelist>

[domenkozar]

Resolved, each entry needs to be wrapped in varlistentry..

[deepfire]

Why not choose something easier to handle, like org-mode?

[vcunat]

There have been many discussions on this IIRC; see the beginning of this issue for an example.

I think any format is relatively easy to handle if you have a good editor support. Org-mode is very editor-specific, i.e. it is readable plain text in any editor, but it's tricky to change/validate it without editor support or lots of practice. BTW, Eelco said there's some Emacs mode that's nice for editing docbook.

[domenkozar]

Saying "our documentation is easy to contribute if you use correct editor" is a little bit pretentious, if you ask me.

[offlinehacker]

I agree with @iElectric, documentation format should be easy to write for
everyone using any editor you have.
On Nov 10, 2014 11:48 AM, "Domen Kožar" [email protected] wrote:

Saying "our documentation is easy to contribute if you use correct editor"
is a little bit pretentious, if you ask me.

—
Reply to this email directly or view it on GitHub
https://github.com/NixOS/nixpkgs/issues/1960#issuecomment-62361874.

[goodwillcoding]

I also agree with @iElectric ... docbok is ok, but it is a pain. Something like rST/Sphinx is definately easier to handle.

[deepfire]

Org-mode for:

• sublime: https://github.com/danielmagnussons/orgmode
• vim: http://vim.wikia.com/wiki/Script:List_of_scripts_for_outlining#Org-mode_related

[offlinehacker]

Org-mode for zed/atom?
On Nov 14, 2014 12:57 PM, "Kosyrev Serge" [email protected] wrote:

Org-mode for:

• sublime: https://github.com/danielmagnussons/orgmode
• vim:
  http://vim.wikia.com/wiki/Script:List_of_scripts_for_outlining#Org-mode_related

—
Reply to this email directly or view it on GitHub
https://github.com/NixOS/nixpkgs/issues/1960#issuecomment-63051829.

[deepfire]

@offlinehacker,
for Atom, at least those:

• https://github.com/psylinse/atom/tree/master/packages/org
• https://github.com/wolfgang/org

none found for zed, unfortunately.

[bachp]

Sorry for commenting on such an old issue, but I just wanted to say that docbook really doesn't make it easy to contribute to the documentation. And I think solutions like Asciidoctor or Sphinx are more accessible and I believe they are powerful enough to allow writing well structured documentation.
Another advantage is that GitHub can directly render reStructuredText and Asciidoc in the web UI, which is not the case for docbook.

[davidak]

I would also rather contribute to a rST documentation than docbook. Have done it once and it was a pain!

[vyp]

With Commonmark the output is not a guessing game because it's actually a spec. Lead by the author of pandoc. Sorry just mentioning because not already mentioned here.

[phile314]

Just as some anecdotal evidence, using rST documentation has worked very well for the Agda project. We started using rST for our user manual about 1 year ago, today we have ~100 pages of rST documentation. Note that you can also do fancy stuff like math formulas, see e.g. here.

Using rST has led to much more documentations contributions for us, both from outsiders _and_ existing contributors.

[domenkozar]

I haven't lost all hope here, I'll reopen.

Note that today we have some documentation in markdown that is auto-converted using pandoc: https://github.com/NixOS/nixpkgs/tree/master/doc/languages-frameworks

This is discouraged (because it makes things really hard to have different toolchains for building docs), but also hints for need of the change of tooling.

[bachp]

It's also worth noting that the Linux kernel is starting to use rST and sphinx: https://lwn.net/Articles/692704/

[aneeshusa]

I'm a big fan of Asciidoc (with the Asciidoctor toolchain), which is markdown-like but doesn't suffer from variant explosion, has well defined extension points, and was created with Docbook in mind, meaning it has really good Docbook compatibility and the toolchain can do conversions out of the box. This makes it easy to use in parallel with Docbook, but it also has easy outputters for HTML, PDF, man pages and more.

[aneeshusa]

Also, the Linux kernel originally was leaning towards switching to Asciidoctor, but moved to rst/Sphinx later on due to concerns about adding Ruby code (Asciidoctor) to their build toolchain. IMO, in our case Asciidoctor is a lighter-weight dependency than Pandoc in Haskell which we're already using.

[bachp]

@aneeshusa I originally also preferred Sphinx and rST but recently learned to appreciate Asciidoc with Asciidoctor. However I think if the transition would be done everything should be converted in one batch and then move on from there.

[AndersonTorres]

I can say by myself, but in my personal blogs I use rST (as a
HTML-generator, not directly). It's a lot easier to maintain, and have
great support for html, latex and more. There's even docbook support for it
(https://github.com/Abstrys/rst2db).

2016-10-14 11:14 GMT-03:00 Pascal Bach [email protected]:

@aneeshusa https://github.com/aneeshusa I originally also preferred
Sphinx and rST but recently learned to appreciate Asciidoc with
Asciidoctor. However I think if the transition would be done everything
should be converted in one batch and then move on from there.

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub
https://github.com/NixOS/nixpkgs/issues/1960#issuecomment-253812089, or mute
the thread
https://github.com/notifications/unsubscribe-auth/AFrc9lgKr9Tv59B-nwObUsr1jvB9ozasks5qz442gaJpZM4Bp7BS
.

[Mic92]

@aneeshusa what I dislike about the current documentation is, that everything is one hard to navigate page. Does Asciidoctor support splitting documentation in multiple pages, while offering an offline search like Sphinx does? I also think we do not need global ordering of chapters. We have independent topics here.

[aneeshusa]

@Mic92 It is possible to have separate Asciidoc files that are rendered to separate pages; I'm not sure what you mean by "offline search". I agree there is no natural global ordering of chapters, but I think it is useful to put all the content in some order to render for e.g. single page HTML or a single PDF with the complete docs for ease of offline usage.

[Mic92]

@aneeshusa https://modulemd.readthedocs.io/en/latest/ the search box in upper left, is a javascript based search-engine. If there are enough topics, I don't think there is a meaningful order.

[aneeshusa]

@Mic92 It seems this is not yet implemented in Asciidoctor (scroll down to see comments about search capabilities). Personally, Ctrl-F fulfills my needs, but if javascript-based search is important to have then I'd support using Sphinx, as it's also a great toolset (and better than DocBook).

[domenkozar]

Another example how this is stalling documentation efforts: https://github.com/NixOS/hydra/pull/316

[gilligan]

@domenkozar Nothing happened here in over a year.. do you think there is even any chance of making decisions here?

[bachp]

I think one other issues with Docbook, besides being XML, is the lack of open source editors for it.

[domenkozar]

As this is not really looking to have a solution, I'll close it.

https://github.com/NixOS/nixpkgs/issues/29324 is promising for easing the contributions.