> Date: Thu, 6 Jul 2006 09:08:03 -0400 > From: Ken Goldman <[EMAIL PROTECTED]> > > In general the docs are not very useful for creating a .emacs.
Please report any such specific failures as bugs, but please describe in detail what you were trying to do and how. Emacs has a wealth of documentation features, but it takes time and effort to learn how to use them efficiently in each specific situation. I frequently find that people who complain about documentation usability didn't use the right approach to search for the information. Of course, even if this is true, it can still be a bug in the docs, that's why it is important to tell the details. > As I've been "reporting as bugs" for years, the reason is that it > has no sample code. There seems to be a philosophical objection to > putting sample code in the documentation. The sections about the init file do show sample code. And the ELisp manual is, of course, replete with sample code, so I cannot see how you can conclude that there's some philosophical objection about that. > Here's an example: > > Suppose I want to set the color for comments. I figure out that the > variable is font-lock-face-attributes. The manual says "See its > documentation string for details." C-h v font-lock-face-attributes > says "not documented as a variable". Dead end. Jason already answered this. In any case, if it will be eventually decided that there is some bug here, please send the bug reports to emacs-devel, where the maintainers will see them and act upon them. Thanks in advance. > What I'd like to see in the manual is sample code like this: > > (setq font-lock-face-attributes > ;; FACE FG BG bold italic underline > '((font-lock-comment-face "gold" "red" 1 nil > nil) > )) If you need sample code for simple assignments like that, you should either use Customize (which will write the code for you) or invest some effort in reading the ELisp manual, which teaches Lisp and many important ELisp coding issues. It is generally impossible to write programs without knowing the language; Customize was invented so that users will not have to write code in an unknown language just to customize Emacs. > The documentation gives me a homework assignment; Google gives me the > answer. The problem with Google is that its answers are frequently outdated and just plain wrong, and so could cause you more trouble than help. The documentation, OTOH, is always correct and up to date by definition (modulo bugs).
