From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: `thunk-let'? Date: Wed, 22 Nov 2017 18:16:53 +0200 Message-ID: <83mv3eb85m.fsf@gnu.org> References: <87infp9z6j.fsf@web.de> <87zi90eehg.fsf@web.de> <87o9ocd6s4.fsf@web.de> <87wp2zcwm2.fsf@web.de> <87mv3vwb2c.fsf_-_@web.de> <87h8tnowl4.fsf@web.de> <83vai3asgt.fsf@gnu.org> Reply-To: Eli Zaretskii NNTP-Posting-Host: blaine.gmane.org X-Trace: blaine.gmane.org 1511367434 21778 195.159.176.226 (22 Nov 2017 16:17:14 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Wed, 22 Nov 2017 16:17:14 +0000 (UTC) Cc: emacs-devel@gnu.org To: michael_heerdegen@web.de, nicolas@petton.fr, monnier@IRO.UMontreal.CA Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Wed Nov 22 17:17:10 2017 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1eHXhw-00053s-DD for ged-emacs-devel@m.gmane.org; Wed, 22 Nov 2017 17:17:04 +0100 Original-Received: from localhost ([::1]:40233 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1eHXi3-00014A-Fv for ged-emacs-devel@m.gmane.org; Wed, 22 Nov 2017 11:17:11 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:43429) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1eHXhs-000115-6g for emacs-devel@gnu.org; Wed, 22 Nov 2017 11:17:01 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1eHXhn-00034k-V6 for emacs-devel@gnu.org; Wed, 22 Nov 2017 11:17:00 -0500 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:35853) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1eHXhn-00034b-RF; Wed, 22 Nov 2017 11:16:55 -0500 Original-Received: from [176.228.60.248] (port=4770 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1eHXhn-00047f-6x; Wed, 22 Nov 2017 11:16:55 -0500 In-reply-to: <83vai3asgt.fsf@gnu.org> (message from Eli Zaretskii on Wed, 22 Nov 2017 05:43:30 +0200) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2001:4830:134:3::e X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.org gmane.emacs.devel:220359 Archived-At: > Date: Wed, 22 Nov 2017 05:43:30 +0200 > From: Eli Zaretskii > Cc: nicolas@petton.fr, monnier@IRO.UMontreal.CA, emacs-devel@gnu.org > > > @Eli: I think we can still add the words I wrote to the manual. What is > > the cheapest way to learn enough of texinfo and its usage by the Emacs > > manual to be able to create a correct patch? > > I will send a message with "Texinfo 101" later today. Here it is. Let me know if something in your plain-text draft is not covered. 1. General markup: Symbols like `this' should be written like @code{this}. Formal arguments and other meta-syntactic variables like THIS should be written like @var{this}. Keyboard input by user should be written @kbd{like this}. Keys mentioned by their name should be written as @key{RET}. First time you mention some important term, write @dfn{term}. File names should be written as @file{like/this}. Program names should be written as @command{prog}. Emphasized text is written @emph{like this}. 2. Functions, macros, variables, etc. Function: @defun my-func arg1 arg2 &optional arg3 Put description here, referencing arguments as @var{arg1} etc. @end defun Likewise with macros, but use @defmac. Likewise with special forms, like condition-case, but use @defspec. For commands, use the generalized @deffn: @deffn Command foo arg1 ... @end deffn For variables, use @defvar, for user options @defopt. 3. Examples: Like this: @example (defun f (number) (lazy-let ((derived-number (progn (message "Calculating 1 plus 2 times %d" number) (1+ (* 2 number))))) (if (> number 10) derived-number number))) @end example 4. Useful glyphs: Result of evaluation: @result{} 42 Expansion of a macro: @expansion{} 42 Generation of output: @print{} 42 Error message: @error{} Wrong type argument: stringp, nil Show point: This is the @point{}buffer text 5. Cross-references: As a separate sentence: @xref{Node name}, for the details. In the middle of a sentence ... see @ref{Node name}, for more. In parentheses: Some text (@pxref{Some node}) more text. 6. Indexing: It is a good idea to have an index entry before a chunk of text describing some topic. For example, in your case, I would have these index entries before the beginning of text: @cindex deferred evaluation @cindex lazy evaluation Functions, variables, etc. described using the @def* commands are automatically added to the index, so you don't need to index them separately. 7. Where to put this stuff: This should be a separate section under the Evaluation chapter, as the last section, after "Eval". (You should also add it to the menu in "Evaluation" and to the top-level detailed menu in elisp.texi.) You begin a section like this: @node Deferred and Lazy Evaluation @section Deferred and Lazy Evaluation These 2 lines start a new node. Follow them with the index entries mentioned above. 8. Always run "make" after modifying the manual, to make sure you didn't leave any errors in the text! 9. Last, but not least: consult the Texinfo manual when in doubt. It is well indexed, so that every command can be easily found by typing "i COMMAND", which invokes Index-search. Example: "i xref RET".