Re: lost argument and doc string

[Tak Ota <Takaaki.Ota@am.sony.com>]

12 Feb 2002 18:57:58 +0000: Jason Rumney <jasonr@gnu.org> wrote:

> There is a comment in make-docfile.c that says that docstrings in .el
> files must start with a backslash and newline immediately after the
> opening double quote.  The files listed above (should) have docstrings
> that comply with that requirement.
> 
> I tried running make-docfile on just simple.el, and only one docstring
> was produced (for previous-complete-history-element), which is
> consistent with that comment.

I've just finished reading make-docfile.c.  You are absolutely right.
I did the same experiment, running make-docfile manually on simple.el,
and got surprised.  And the source file is requesting the sequence
`dquote bslash newline' as the beginning of the valid doc string in
case of el files.  I don't think this is right.  Starting doc string
that way is only optional I believe.

Since read_c_string_or_comment takes care of line continuation
(bslash at the end of line) there is really no need of handling the
very first continuation in a special manner in the individual cases.

I propose the following patch.  It corrects the problem and the code
becomes cleaner too.

-Tak

*** lib-src/make-docfile.c.orig	Sat Jan  5 15:37:58 2002
--- lib-src/make-docfile.c	Tue Feb 12 11:28:01 2002
***************
*** 911,925 ****
  	  else
  	    while (c != ')')
  	      c = getc (infile);
- 	  skip_white (infile);
  
! 	  /* If the next three characters aren't `dquote bslash newline'
! 	     then we're not reading a docstring.
! 	   */
! 	  if ((c = getc (infile)) != '"'
! 	      || (c = getc (infile)) != '\\'
! 	      || ((c = getc (infile)) != '\n' && c != '\r'))
! 	    {
  #ifdef DEBUG
  	      fprintf (stderr, "## non-docstring in %s (%s)\n",
  		       buffer, filename);
--- 911,920 ----
  	  else
  	    while (c != ')')
  	      c = getc (infile);
  
! 	  skip_white (infile);
! 	  if ((c = getc (infile)) != '\"')
!             {
  #ifdef DEBUG
  	      fprintf (stderr, "## non-docstring in %s (%s)\n",
  		       buffer, filename);
***************
*** 931,954 ****
        else if (! strcmp (buffer, "defvar")
  	       || ! strcmp (buffer, "defconst"))
  	{
- 	  char c1 = 0, c2 = 0;
  	  type = 'V';
  	  read_lisp_symbol (infile, buffer);
  
  	  if (saved_string == 0)
  	    {
! 
! 	      /* Skip until the end of line; remember two previous chars.  */
! 	      while (c != '\n' && c != '\r' && c >= 0)
! 		{
! 		  c2 = c1;
! 		  c1 = c;
! 		  c = getc (infile);
! 		}
! 
! 	      /* If two previous characters were " and \,
! 		 this is a doc string.  Otherwise, there is none.  */
! 	      if (c2 != '"' || c1 != '\\')
  		{
  #ifdef DEBUG
  		  fprintf (stderr, "## non-docstring in %s (%s)\n",
--- 926,938 ----
        else if (! strcmp (buffer, "defvar")
  	       || ! strcmp (buffer, "defconst"))
  	{
  	  type = 'V';
  	  read_lisp_symbol (infile, buffer);
  
  	  if (saved_string == 0)
  	    {
!               skip_white (infile);
!               if ((c = getc (infile)) != '\"')
  		{
  #ifdef DEBUG
  		  fprintf (stderr, "## non-docstring in %s (%s)\n",
***************
*** 961,967 ****
  
        else if (! strcmp (buffer, "custom-declare-variable"))
  	{
- 	  char c1 = 0, c2 = 0;
  	  type = 'V';
  
  	  c = getc (infile);
--- 945,950 ----
***************
*** 997,1013 ****
  
  	  if (saved_string == 0)
  	    {
! 	      /* Skip to end of line; remember the two previous chars.  */
! 	      while (c != '\n' && c != '\r' && c >= 0)
! 		{
! 		  c2 = c1;
! 		  c1 = c;
! 		  c = getc (infile);
! 		}
! 
! 	      /* If two previous characters were " and \,
! 		 this is a doc string.  Otherwise, there is none.  */
! 	      if (c2 != '"' || c1 != '\\')
  		{
  #ifdef DEBUG
  		  fprintf (stderr, "## non-docstring in %s (%s)\n",
--- 980,987 ----
  
  	  if (saved_string == 0)
  	    {
!               skip_white (infile);
!               if ((c = getc (infile)) != '\"')
  		{
  #ifdef DEBUG
  		  fprintf (stderr, "## non-docstring in %s (%s)\n",
***************
*** 1020,1026 ****
  
        else if (! strcmp (buffer, "fset") || ! strcmp (buffer, "defalias"))
  	{
- 	  char c1 = 0, c2 = 0;
  	  type = 'F';
  
  	  c = getc (infile);
--- 994,999 ----
***************
*** 1054,1070 ****
  
  	  if (saved_string == 0)
  	    {
! 	      /* Skip to end of line; remember the two previous chars.  */
! 	      while (c != '\n' && c != '\r' && c >= 0)
! 		{
! 		  c2 = c1;
! 		  c1 = c;
! 		  c = getc (infile);
! 		}
! 
! 	      /* If two previous characters were " and \,
! 		 this is a doc string.  Otherwise, there is none.  */
! 	      if (c2 != '"' || c1 != '\\')
  		{
  #ifdef DEBUG
  		  fprintf (stderr, "## non-docstring in %s (%s)\n",
--- 1027,1034 ----
  
  	  if (saved_string == 0)
  	    {
!               skip_white (infile);
!               if ((c = getc (infile)) != '\"')
  		{
  #ifdef DEBUG
  		  fprintf (stderr, "## non-docstring in %s (%s)\n",
***************
*** 1117,1129 ****
  	  skip_white (infile);
  
  	  if (saved_string == 0)
! 	    {
! 	      /* If the next three characters aren't `dquote bslash newline'
! 		 then we're not reading a docstring.  */
! 	      if ((c = getc (infile)) != '"'
! 		  || (c = getc (infile)) != '\\'
! 		  || ((c = getc (infile)) != '\n' && c != '\r'))
! 		{
  #ifdef DEBUG
  		  fprintf (stderr, "## non-docstring in %s (%s)\n",
  			   buffer, filename);
--- 1081,1090 ----
  	  skip_white (infile);
  
  	  if (saved_string == 0)
!             {
!               skip_white (infile);
!               if ((c = getc (infile)) != '\"')
!                 {
  #ifdef DEBUG
  		  fprintf (stderr, "## non-docstring in %s (%s)\n",
  			   buffer, filename);
***************
*** 1152,1159 ****
  	 dynamic doc string in saved_string
  	 or gobble a doc string from the input file.
  
! 	 In the latter case, the opening quote (and leading
! 	 backslash-newline) have already been read.  */
  
        putc (037, outfile);
        putc (type, outfile);
--- 1113,1120 ----
  	 dynamic doc string in saved_string
  	 or gobble a doc string from the input file.
  
! 	 In the latter case, the opening quote has already been
! 	 read.  */
  
        putc (037, outfile);
        putc (type, outfile);

_______________________________________________
Emacs-devel mailing list
Emacs-devel@gnu.org
http://mail.gnu.org/mailman/listinfo/emacs-devel