Re: `thunk-let'?

[Eli Zaretskii <eliz@gnu.org>]

> Date: Wed, 22 Nov 2017 05:43:30 +0200
> From: Eli Zaretskii <eliz@gnu.org>
> 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".