/[emacs]/emacs/lispref/tips.texi
ViewVC logotype

Diff of /emacs/lispref/tips.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.40 by rms, Tue Nov 13 02:20:53 2001 UTC revision 1.41 by rms, Sat Jan 26 22:43:53 2002 UTC
# Line 483  longer the case---documentation strings Line 483  longer the case---documentation strings
483  a running Emacs.  a running Emacs.
484    
485  @item  @item
486    Format the documentation string so that it fits in an Emacs window on an
487    80-column screen.  It is a good idea for most lines to be no wider than
488    60 characters.  The first line should not be wider than 67 characters
489    or it will look bad in the output of @code{apropos}.
490    
491    You can fill the text if that looks good.  However, rather than blindly
492    filling the entire documentation string, you can often make it much more
493    readable by choosing certain line breaks with care.  Use blank lines
494    between topics if the documentation string is long.
495    
496    @item
497  The first line of the documentation string should consist of one or two  The first line of the documentation string should consist of one or two
498  complete sentences that stand on their own as a summary.  @kbd{M-x  complete sentences that stand on their own as a summary.  @kbd{M-x
499  apropos} displays just the first line, and if that line's contents don't  apropos} displays just the first line, and if that line's contents don't
# Line 503  documentation string as an imperative--f Line 514  documentation string as an imperative--f
514  cons of A and B.'' in preference to ``Returns the cons of A and B@.''  cons of A and B.'' in preference to ``Returns the cons of A and B@.''
515  Usually it looks good to do likewise for the rest of the first  Usually it looks good to do likewise for the rest of the first
516  paragraph.  Subsequent paragraphs usually look better if each sentence  paragraph.  Subsequent paragraphs usually look better if each sentence
517  has a proper subject.  is indicative and has a proper subject.
518    
519  @item  @item
520  Write documentation strings in the active voice, not the passive, and in  Write documentation strings in the active voice, not the passive, and in
# Line 527  In Dired, visit the file or directory na Line 538  In Dired, visit the file or directory na
538    
539  @item  @item
540  Do not start or end a documentation string with whitespace.  Do not start or end a documentation string with whitespace.
   
 @item  
 Format the documentation string so that it fits in an Emacs window on an  
 80-column screen.  It is a good idea for most lines to be no wider than  
 60 characters.  The first line should not be wider than 67 characters  
 or it will look bad in the output of @code{apropos}.  
   
 You can fill the text if that looks good.  However, rather than blindly  
 filling the entire documentation string, you can often make it much more  
 readable by choosing certain line breaks with care.  Use blank lines  
 between topics if the documentation string is long.  
541    
542  @item  @item
543  @strong{Do not} indent subsequent lines of a documentation string so  @strong{Do not} indent subsequent lines of a documentation string so

Legend:
Removed from v.1.40  
changed lines
  Added in v.1.41

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26