texinfo is pretty nice. Many GNU projects use this for their manuals. That way you can create a printed manual, an HTML manual, and an info manual from the same source.
>You cannot even reliably generate it from in-source Emacs Lisp comments which doubles the maintenance effort for most elisp code.
Good code comments do not make a good manual. A manual needs to do much more. I don't really believe in generating docs from docstrings in source code. I am surprised that you can't bootstrap a manual with the docstrings, though. That's unfortunate. I was able to do so rather easily with Guile.
I think that this new generation of programmers (which I am included in) should learn that Markdown is inadequate for large documents.
Oh, and I am in full support of the git migration.
texinfo is pretty nice. Many GNU projects use this for their manuals. That way you can create a printed manual, an HTML manual, and an info manual from the same source.
>You cannot even reliably generate it from in-source Emacs Lisp comments which doubles the maintenance effort for most elisp code.
Good code comments do not make a good manual. A manual needs to do much more. I don't really believe in generating docs from docstrings in source code. I am surprised that you can't bootstrap a manual with the docstrings, though. That's unfortunate. I was able to do so rather easily with Guile.
I think that this new generation of programmers (which I am included in) should learn that Markdown is inadequate for large documents.
Oh, and I am in full support of the git migration.