Re: lost argument and doc string

[Tak Ota]

12 Feb 2002 18:57:58 +0000: Jason Rumney <address@hidden> 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);