On Thu, May 05, 2011 at 03:35:04PM +0200, Pieter Praet wrote: [...] > How about automatically generating docs from inline documentation in the > source? The (supposedly) only cartoon RMS has ever drawn [1] > specifically calls Emacs a "Self-Documenting extensible editor" [sic] > for good reason. :D
You can't auto-generate a (decent) manual. The docstrings are good when you want to know details about a particular function or variable, and that's what the "self-documentedness" is primarily about -- you have commands like `describe-function' etc. for conveniently accessing the in-source documentation. The manual on the other hand should provide a guidance on what you can do and how with this piece of software (when you don't want to read the source right away and (try to) figure it out, at least). Of course Info also has things like function/variable indices; one more reason you should mention the new variable in the manual. > > [...] (And I'd say "up to" > > instead of "up until", but I'm not a native speaker.) > > I'm not a native speaker either (although I consider English vastly > superior to my native tongues, and act accordingly) but I'd say that > depends on whether you regard the commit series as either a spatial or a > chronological vector. > > You're most welcome to change it if you like, though. :) I'll let others decide; you may have a point. "Up until the current head" just stroke me as a bit weird, so I figured I'd mention it. Štěpán
