lib-src/make-docfile.c

   1 /* Generate doc-string file for GNU Emacs from source files.
   2    Copyright (C) 1985, 86, 92, 93, 94, 97, 1999, 2000, 01, 2004
   3    Free Software Foundation, Inc.
   4
   5 This file is part of GNU Emacs.
   6
   7 GNU Emacs is free software; you can redistribute it and/or modify
   8 it under the terms of the GNU General Public License as published by
   9 the Free Software Foundation; either version 2, or (at your option)
  10 any later version.
  11
  12 GNU Emacs is distributed in the hope that it will be useful,
  13 but WITHOUT ANY WARRANTY; without even the implied warranty of
  14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15 GNU General Public License for more details.
  16
  17 You should have received a copy of the GNU General Public License
  18 along with GNU Emacs; see the file COPYING.  If not, write to
  19 the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  20 Boston, MA 02111-1307, USA.  */
  21
  22 /* The arguments given to this program are all the C and Lisp source files
  23  of GNU Emacs.  .elc and .el and .c files are allowed.
  24  A .o file can also be specified; the .c file it was made from is used.
  25  This helps the makefile pass the correct list of files.
  26  Option -d DIR means change to DIR before looking for files.
  27
  28  The results, which go to standard output or to a file
  29  specified with -a or -o (-a to append, -o to start from nothing),
  30  are entries containing function or variable names and their documentation.
  31  Each entry starts with a ^_ character.
  32  Then comes F for a function or V for a variable.
  33  Then comes the function or variable name, terminated with a newline.
  34  Then comes the documentation for that function or variable.
  35  */
  36
  37 #define NO_SHORTNAMES   /* Tell config not to load remap.h */
  38 #include <config.h>
  39
  40 /* defined to be emacs_main, sys_fopen, etc. in config.h */
  41 #undef main
  42 #undef fopen
  43 #undef chdir
  44
  45 #include <stdio.h>
  46 #ifdef MSDOS
  47 #include <fcntl.h>
  48 #endif /* MSDOS */
  49 #ifdef WINDOWSNT
  50 #include <stdlib.h>
  51 #include <fcntl.h>
  52 #include <direct.h>
  53 #endif /* WINDOWSNT */
  54
  55 #ifdef DOS_NT
  56 #define READ_TEXT "rt"
  57 #define READ_BINARY "rb"
  58 #else  /* not DOS_NT */
  59 #define READ_TEXT "r"
  60 #define READ_BINARY "r"
  61 #endif /* not DOS_NT */
  62
  63 #ifndef IS_DIRECTORY_SEP
  64 #define IS_DIRECTORY_SEP(_c_) ((_c_) == '/')
  65 #endif
  66
  67 int scan_file ();
  68 int scan_lisp_file ();
  69 int scan_c_file ();
  70
  71 #ifdef MSDOS
  72 /* s/msdos.h defines this as sys_chdir, but we're not linking with the
  73    file where that function is defined.  */
  74 #undef chdir
  75 #endif
  76
  77 #ifdef HAVE_UNISTD_H
  78 #include <unistd.h>
  79 #endif
  80
  81 /* Stdio stream for output to the DOC file.  */
  82 FILE *outfile;
  83
  84 /* Name this program was invoked with.  */
  85 char *progname;
  86
  87 /* Print error message.  `s1' is printf control string, `s2' is arg for it.  */
  88
  89 /* VARARGS1 */
  90 void
  91 error (s1, s2)
  92      char *s1, *s2;
  93 {
  94   fprintf (stderr, "%s: ", progname);
  95   fprintf (stderr, s1, s2);
  96   fprintf (stderr, "\n");
  97 }
  98
  99 /* Print error message and exit.  */
 100
 101 /* VARARGS1 */
 102 void
 103 fatal (s1, s2)
 104      char *s1, *s2;
 105 {
 106   error (s1, s2);
 107   exit (EXIT_FAILURE);
 108 }
 109
 110 /* Like malloc but get fatal error if memory is exhausted.  */
 111
 112 void *
 113 xmalloc (size)
 114      unsigned int size;
 115 {
 116   void *result = (void *) malloc (size);
 117   if (result == NULL)
 118     fatal ("virtual memory exhausted", 0);
 119   return result;
 120 }
 121 \f
 122 int
 123 main (argc, argv)
 124      int argc;
 125      char **argv;
 126 {
 127   int i;
 128   int err_count = 0;
 129   int first_infile;
 130
 131   progname = argv[0];
 132
 133   outfile = stdout;
 134
 135   /* Don't put CRs in the DOC file.  */
 136 #ifdef MSDOS
 137   _fmode = O_BINARY;
 138 #if 0  /* Suspicion is that this causes hanging.
 139           So instead we require people to use -o on MSDOS.  */
 140   (stdout)->_flag &= ~_IOTEXT;
 141   _setmode (fileno (stdout), O_BINARY);
 142 #endif
 143   outfile = 0;
 144 #endif /* MSDOS */
 145 #ifdef WINDOWSNT
 146   _fmode = O_BINARY;
 147   _setmode (fileno (stdout), O_BINARY);
 148 #endif /* WINDOWSNT */
 149
 150   /* If first two args are -o FILE, output to FILE.  */
 151   i = 1;
 152   if (argc > i + 1 && !strcmp (argv[i], "-o"))
 153     {
 154       outfile = fopen (argv[i + 1], "w");
 155       i += 2;
 156     }
 157   if (argc > i + 1 && !strcmp (argv[i], "-a"))
 158     {
 159       outfile = fopen (argv[i + 1], "a");
 160       i += 2;
 161     }
 162   if (argc > i + 1 && !strcmp (argv[i], "-d"))
 163     {
 164       chdir (argv[i + 1]);
 165       i += 2;
 166     }
 167
 168   if (outfile == 0)
 169     fatal ("No output file specified", "");
 170
 171   first_infile = i;
 172   for (; i < argc; i++)
 173     {
 174       int j;
 175       /* Don't process one file twice.  */
 176       for (j = first_infile; j < i; j++)
 177         if (! strcmp (argv[i], argv[j]))
 178           break;
 179       if (j == i)
 180         err_count += scan_file (argv[i]);
 181     }
 182   return (err_count > 0 ? EXIT_FAILURE : EXIT_SUCCESS);
 183 }
 184
 185 /* Add a source file name boundary marker in the output file.  */
 186 void
 187 put_filename (filename)
 188      char *filename;
 189 {
 190   char *tmp;
 191
 192   for (tmp = filename; *tmp; tmp++)
 193     {
 194       if (IS_DIRECTORY_SEP(*tmp))
 195         filename = tmp + 1;
 196     }
 197
 198   putc (037, outfile);
 199   putc ('S', outfile);
 200   fprintf (outfile, "%s\n", filename);
 201 }
 202
 203 /* Read file FILENAME and output its doc strings to outfile.  */
 204 /* Return 1 if file is not found, 0 if it is found.  */
 205
 206 int
 207 scan_file (filename)
 208      char *filename;
 209 {
 210   int len = strlen (filename);
 211
 212   put_filename (filename);
 213   if (len > 4 && !strcmp (filename + len - 4, ".elc"))
 214     return scan_lisp_file (filename, READ_BINARY);
 215   else if (len > 3 && !strcmp (filename + len - 3, ".el"))
 216     return scan_lisp_file (filename, READ_TEXT);
 217   else
 218     return scan_c_file (filename, READ_TEXT);
 219 }
 220 \f
 221 char buf[128];
 222
 223 /* Some state during the execution of `read_c_string_or_comment'.  */
 224 struct rcsoc_state
 225 {
 226   /* A count of spaces and newlines that have been read, but not output.  */
 227   unsigned pending_spaces, pending_newlines;
 228
 229   /* Where we're reading from.  */
 230   FILE *in_file;
 231
 232   /* If non-zero, a buffer into which to copy characters.  */
 233   char *buf_ptr;
 234   /* If non-zero, a file into which to copy characters.  */
 235   FILE *out_file;
 236
 237   /* A keyword we look for at the beginning of lines.  If found, it is
 238      not copied, and SAW_KEYWORD is set to true.  */
 239   char *keyword;
 240   /* The current point we've reached in an occurance of KEYWORD in
 241      the input stream.  */
 242   char *cur_keyword_ptr;
 243   /* Set to true if we saw an occurance of KEYWORD.  */
 244   int saw_keyword;
 245 };
 246
 247 /* Output CH to the file or buffer in STATE.  Any pending newlines or
 248    spaces are output first.  */
 249
 250 static INLINE void
 251 put_char (ch, state)
 252      int ch;
 253      struct rcsoc_state *state;
 254 {
 255   int out_ch;
 256   do
 257     {
 258       if (state->pending_newlines > 0)
 259         {
 260           state->pending_newlines--;
 261           out_ch = '\n';
 262         }
 263       else if (state->pending_spaces > 0)
 264         {
 265           state->pending_spaces--;
 266           out_ch = ' ';
 267         }
 268       else
 269         out_ch = ch;
 270
 271       if (state->out_file)
 272         putc (out_ch, state->out_file);
 273       if (state->buf_ptr)
 274         *state->buf_ptr++ = out_ch;
 275     }
 276   while (out_ch != ch);
 277 }
 278
 279 /* If in the middle of scanning a keyword, continue scanning with
 280    character CH, otherwise output CH to the file or buffer in STATE.
 281    Any pending newlines or spaces are output first, as well as any
 282    previously scanned characters that were thought to be part of a
 283    keyword, but were in fact not.  */
 284
 285 static void
 286 scan_keyword_or_put_char (ch, state)
 287      int ch;
 288      struct rcsoc_state *state;
 289 {
 290   if (state->keyword
 291       && *state->cur_keyword_ptr == ch
 292       && (state->cur_keyword_ptr > state->keyword
 293           || state->pending_newlines > 0))
 294     /* We might be looking at STATE->keyword at some point.
 295        Keep looking until we know for sure.  */
 296     {
 297       if (*++state->cur_keyword_ptr == '\0')
 298         /* Saw the whole keyword.  Set SAW_KEYWORD flag to true.  */
 299         {
 300           state->saw_keyword = 1;
 301
 302           /* Reset the scanning pointer.  */
 303           state->cur_keyword_ptr = state->keyword;
 304
 305           /* Canonicalize whitespace preceding a usage string.  */
 306           state->pending_newlines = 2;
 307           state->pending_spaces = 0;
 308
 309           /* Skip any whitespace between the keyword and the
 310              usage string.  */
 311           do
 312             ch = getc (state->in_file);
 313           while (ch == ' ' || ch == '\n');
 314
 315           /* Output the open-paren we just read.  */
 316           put_char (ch, state);
 317
 318           /* Skip the function name and replace it with `fn'.  */
 319           do
 320             ch = getc (state->in_file);
 321           while (ch != ' ' && ch != ')');
 322           put_char ('f', state);
 323           put_char ('n', state);
 324
 325           /* Put back the last character.  */
 326           ungetc (ch, state->in_file);
 327         }
 328     }
 329   else
 330     {
 331       if (state->keyword && state->cur_keyword_ptr > state->keyword)
 332         /* We scanned the beginning of a potential usage
 333            keyword, but it was a false alarm.  Output the
 334            part we scanned.  */
 335         {
 336           char *p;
 337
 338           for (p = state->keyword; p < state->cur_keyword_ptr; p++)
 339             put_char (*p, state);
 340
 341           state->cur_keyword_ptr = state->keyword;
 342         }
 343
 344       put_char (ch, state);
 345     }
 346 }
 347
 348
 349 /* Skip a C string or C-style comment from INFILE, and return the
 350    character that follows.  COMMENT non-zero means skip a comment.  If
 351    PRINTFLAG is positive, output string contents to outfile.  If it is
 352    negative, store contents in buf.  Convert escape sequences \n and
 353    \t to newline and tab; discard \ followed by newline.
 354    If SAW_USAGE is non-zero, then any occurances of the string `usage:'
 355    at the beginning of a line will be removed, and *SAW_USAGE set to
 356    true if any were encountered.  */
 357
 358 int
 359 read_c_string_or_comment (infile, printflag, comment, saw_usage)
 360      FILE *infile;
 361      int printflag;
 362      int *saw_usage;
 363      int comment;
 364 {
 365   register int c;
 366   struct rcsoc_state state;
 367
 368   state.in_file = infile;
 369   state.buf_ptr = (printflag < 0 ? buf : 0);
 370   state.out_file = (printflag > 0 ? outfile : 0);
 371   state.pending_spaces = 0;
 372   state.pending_newlines = 0;
 373   state.keyword = (saw_usage ? "usage:" : 0);
 374   state.cur_keyword_ptr = state.keyword;
 375   state.saw_keyword = 0;
 376
 377   c = getc (infile);
 378   if (comment)
 379     while (c == '\n' || c == '\r' || c == '\t' || c == ' ')
 380       c = getc (infile);
 381
 382   while (c != EOF)
 383     {
 384       while (c != EOF && (comment ? c != '*' : c != '"'))
 385         {
 386           if (c == '\\')
 387             {
 388               c = getc (infile);
 389               if (c == '\n' || c == '\r')
 390                 {
 391                   c = getc (infile);
 392                   continue;
 393                 }
 394               if (c == 'n')
 395                 c = '\n';
 396               if (c == 't')
 397                 c = '\t';
 398             }
 399
 400           if (c == ' ')
 401             state.pending_spaces++;
 402           else if (c == '\n')
 403             {
 404               state.pending_newlines++;
 405               state.pending_spaces = 0;
 406             }
 407           else
 408             scan_keyword_or_put_char (c, &state);
 409
 410           c = getc (infile);
 411         }
 412
 413       if (c != EOF)
 414         c = getc (infile);
 415
 416       if (comment)
 417         {
 418           if (c == '/')
 419             {
 420               c = getc (infile);
 421               break;
 422             }
 423
 424           scan_keyword_or_put_char ('*', &state);
 425         }
 426       else
 427         {
 428           if (c != '"')
 429             break;
 430
 431           /* If we had a "", concatenate the two strings.  */
 432           c = getc (infile);
 433         }
 434     }
 435
 436   if (printflag < 0)
 437     *state.buf_ptr = 0;
 438
 439   if (saw_usage)
 440     *saw_usage = state.saw_keyword;
 441
 442   return c;
 443 }
 444
 445
 446 \f
 447 /* Write to file OUT the argument names of function FUNC, whose text is in BUF.
 448    MINARGS and MAXARGS are the minimum and maximum number of arguments.  */
 449
 450 void
 451 write_c_args (out, func, buf, minargs, maxargs)
 452      FILE *out;
 453      char *func, *buf;
 454      int minargs, maxargs;
 455 {
 456   register char *p;
 457   int in_ident = 0;
 458   int just_spaced = 0;
 459   int need_space = 1;
 460
 461   fprintf (out, "(fn");
 462
 463   if (*buf == '(')
 464     ++buf;
 465
 466   for (p = buf; *p; p++)
 467     {
 468       char c = *p;
 469       int ident_start = 0;
 470
 471       /* Notice when we start printing a new identifier.  */
 472       if ((('A' <= c && c <= 'Z')
 473            || ('a' <= c && c <= 'z')
 474            || ('0' <= c && c <= '9')
 475            || c == '_')
 476           != in_ident)
 477         {
 478           if (!in_ident)
 479             {
 480               in_ident = 1;
 481               ident_start = 1;
 482
 483               if (need_space)
 484                 putc (' ', out);
 485
 486               if (minargs == 0 && maxargs > 0)
 487                 fprintf (out, "&optional ");
 488               just_spaced = 1;
 489
 490               minargs--;
 491               maxargs--;
 492             }
 493           else
 494             in_ident = 0;
 495         }
 496
 497       /* Print the C argument list as it would appear in lisp:
 498          print underscores as hyphens, and print commas and newlines
 499          as spaces.  Collapse adjacent spaces into one.  */
 500       if (c == '_')
 501         c = '-';
 502       else if (c == ',' || c == '\n')
 503         c = ' ';
 504
 505       /* In C code, `default' is a reserved word, so we spell it
 506          `defalt'; unmangle that here.  */
 507       if (ident_start
 508           && strncmp (p, "defalt", 6) == 0
 509           && ! (('A' <= p[6] && p[6] <= 'Z')
 510                 || ('a' <= p[6] && p[6] <= 'z')
 511                 || ('0' <= p[6] && p[6] <= '9')
 512                 || p[6] == '_'))
 513         {
 514           fprintf (out, "DEFAULT");
 515           p += 5;
 516           in_ident = 0;
 517           just_spaced = 0;
 518         }
 519       else if (c != ' ' || !just_spaced)
 520         {
 521           if (c >= 'a' && c <= 'z')
 522             /* Upcase the letter.  */
 523             c += 'A' - 'a';
 524           putc (c, out);
 525         }
 526
 527       just_spaced = c == ' ';
 528       need_space = 0;
 529     }
 530 }
 531 \f
 532 /* Read through a c file.  If a .o file is named,
 533    the corresponding .c file is read instead.
 534    Looks for DEFUN constructs such as are defined in ../src/lisp.h.
 535    Accepts any word starting DEF... so it finds DEFSIMPLE and DEFPRED.  */
 536
 537 int
 538 scan_c_file (filename, mode)
 539      char *filename, *mode;
 540 {
 541   FILE *infile;
 542   register int c;
 543   register int commas;
 544   register int defunflag;
 545   register int defvarperbufferflag;
 546   register int defvarflag;
 547   int minargs, maxargs;
 548   int extension = filename[strlen (filename) - 1];
 549
 550   if (extension == 'o')
 551     filename[strlen (filename) - 1] = 'c';
 552
 553   infile = fopen (filename, mode);
 554
 555   /* No error if non-ex input file */
 556   if (infile == NULL)
 557     {
 558       perror (filename);
 559       return 0;
 560     }
 561
 562   /* Reset extension to be able to detect duplicate files.  */
 563   filename[strlen (filename) - 1] = extension;
 564
 565   c = '\n';
 566   while (!feof (infile))
 567     {
 568       int doc_keyword = 0;
 569
 570       if (c != '\n' && c != '\r')
 571         {
 572           c = getc (infile);
 573           continue;
 574         }
 575       c = getc (infile);
 576       if (c == ' ')
 577         {
 578           while (c == ' ')
 579             c = getc (infile);
 580           if (c != 'D')
 581             continue;
 582           c = getc (infile);
 583           if (c != 'E')
 584             continue;
 585           c = getc (infile);
 586           if (c != 'F')
 587             continue;
 588           c = getc (infile);
 589           if (c != 'V')
 590             continue;
 591           c = getc (infile);
 592           if (c != 'A')
 593             continue;
 594           c = getc (infile);
 595           if (c != 'R')
 596             continue;
 597           c = getc (infile);
 598           if (c != '_')
 599             continue;
 600
 601           defvarflag = 1;
 602           defunflag = 0;
 603
 604           c = getc (infile);
 605           defvarperbufferflag = (c == 'P');
 606
 607           c = getc (infile);
 608         }
 609       else if (c == 'D')
 610         {
 611           c = getc (infile);
 612           if (c != 'E')
 613             continue;
 614           c = getc (infile);
 615           if (c != 'F')
 616             continue;
 617           c = getc (infile);
 618           defunflag = c == 'U';
 619           defvarflag = 0;
 620         }
 621       else continue;
 622
 623       while (c != '(')
 624         {
 625           if (c < 0)
 626             goto eof;
 627           c = getc (infile);
 628         }
 629
 630       /* Lisp variable or function name.  */
 631       c = getc (infile);
 632       if (c != '"')
 633         continue;
 634       c = read_c_string_or_comment (infile, -1, 0, 0);
 635
 636       /* DEFVAR_LISP ("name", addr, "doc")
 637          DEFVAR_LISP ("name", addr /\* doc *\/)
 638          DEFVAR_LISP ("name", addr, doc: /\* doc *\/)  */
 639
 640       if (defunflag)
 641         commas = 5;
 642       else if (defvarperbufferflag)
 643         commas = 2;
 644       else if (defvarflag)
 645         commas = 1;
 646       else  /* For DEFSIMPLE and DEFPRED */
 647         commas = 2;
 648
 649       while (commas)
 650         {
 651           if (c == ',')
 652             {
 653               commas--;
 654
 655               if (defunflag && (commas == 1 || commas == 2))
 656                 {
 657                   do
 658                     c = getc (infile);
 659                   while (c == ' ' || c == '\n' || c == '\r' || c == '\t');
 660                   if (c < 0)
 661                     goto eof;
 662                   ungetc (c, infile);
 663                   if (commas == 2) /* pick up minargs */
 664                     fscanf (infile, "%d", &minargs);
 665                   else /* pick up maxargs */
 666                     if (c == 'M' || c == 'U') /* MANY || UNEVALLED */
 667                       maxargs = -1;
 668                     else
 669                       fscanf (infile, "%d", &maxargs);
 670                 }
 671             }
 672
 673           if (c == EOF)
 674             goto eof;
 675           c = getc (infile);
 676         }
 677
 678       while (c == ' ' || c == '\n' || c == '\r' || c == '\t')
 679         c = getc (infile);
 680
 681       if (c == '"')
 682         c = read_c_string_or_comment (infile, 0, 0, 0);
 683
 684       while (c != EOF && c != ',' && c != '/')
 685         c = getc (infile);
 686       if (c == ',')
 687         {
 688           c = getc (infile);
 689           while (c == ' ' || c == '\n' || c == '\r' || c == '\t')
 690             c = getc (infile);
 691           while ((c >= 'a' && c <= 'z') || (c >= 'Z' && c <= 'Z'))
 692             c = getc (infile);
 693           if (c == ':')
 694             {
 695               doc_keyword = 1;
 696               c = getc (infile);
 697               while (c == ' ' || c == '\n' || c == '\r' || c == '\t')
 698                 c = getc (infile);
 699             }
 700         }
 701
 702       if (c == '"'
 703           || (c == '/'
 704               && (c = getc (infile),
 705                   ungetc (c, infile),
 706                   c == '*')))
 707         {
 708           int comment = c != '"';
 709           int saw_usage;
 710
 711           putc (037, outfile);
 712           putc (defvarflag ? 'V' : 'F', outfile);
 713           fprintf (outfile, "%s\n", buf);
 714
 715           if (comment)
 716             getc (infile);      /* Skip past `*' */
 717           c = read_c_string_or_comment (infile, 1, comment, &saw_usage);
 718
 719           /* If this is a defun, find the arguments and print them.  If
 720              this function takes MANY or UNEVALLED args, then the C source
 721              won't give the names of the arguments, so we shouldn't bother
 722              trying to find them.
 723
 724              Various doc-string styles:
 725               0: DEFUN (..., "DOC") (args)            [!comment]
 726               1: DEFUN (..., /\* DOC *\/ (args))      [comment && !doc_keyword]
 727               2: DEFUN (..., doc: /\* DOC *\/) (args) [comment && doc_keyword]
 728           */
 729           if (defunflag && maxargs != -1 && !saw_usage)
 730             {
 731               char argbuf[1024], *p = argbuf;
 732
 733               if (!comment || doc_keyword)
 734                 while (c != ')')
 735                   {
 736                     if (c < 0)
 737                       goto eof;
 738                     c = getc (infile);
 739                   }
 740
 741               /* Skip into arguments.  */
 742               while (c != '(')
 743                 {
 744                   if (c < 0)
 745                     goto eof;
 746                   c = getc (infile);
 747                 }
 748               /* Copy arguments into ARGBUF.  */
 749               *p++ = c;
 750               do
 751                 *p++ = c = getc (infile);
 752               while (c != ')');
 753               *p = '\0';
 754               /* Output them.  */
 755               fprintf (outfile, "\n\n");
 756               write_c_args (outfile, buf, argbuf, minargs, maxargs);
 757             }
 758           else if (defunflag && maxargs == -1 && !saw_usage)
 759             /* The DOC should provide the usage form.  */
 760             fprintf (stderr, "Missing `usage' for function `%s'.\n", buf);
 761         }
 762     }
 763  eof:
 764   fclose (infile);
 765   return 0;
 766 }
 767 \f
 768 /* Read a file of Lisp code, compiled or interpreted.
 769  Looks for
 770   (defun NAME ARGS DOCSTRING ...)
 771   (defmacro NAME ARGS DOCSTRING ...)
 772   (defsubst NAME ARGS DOCSTRING ...)
 773   (autoload (quote NAME) FILE DOCSTRING ...)
 774   (defvar NAME VALUE DOCSTRING)
 775   (defconst NAME VALUE DOCSTRING)
 776   (fset (quote NAME) (make-byte-code ... DOCSTRING ...))
 777   (fset (quote NAME) #[... DOCSTRING ...])
 778   (defalias (quote NAME) #[... DOCSTRING ...])
 779   (custom-declare-variable (quote NAME) VALUE DOCSTRING ...)
 780  starting in column zero.
 781  (quote NAME) may appear as 'NAME as well.
 782
 783  We also look for #@LENGTH CONTENTS^_ at the beginning of the line.
 784  When we find that, we save it for the following defining-form,
 785  and we use that instead of reading a doc string within that defining-form.
 786
 787  For defvar, defconst, and fset we skip to the docstring with a kludgy
 788  formatting convention: all docstrings must appear on the same line as the
 789  initial open-paren (the one in column zero) and must contain a backslash
 790  and a newline immediately after the initial double-quote.  No newlines
 791  must appear between the beginning of the form and the first double-quote.
 792  For defun, defmacro, and autoload, we know how to skip over the
 793  arglist, but the doc string must still have a backslash and newline
 794  immediately after the double quote.
 795  The only source files that must follow this convention are preloaded
 796  uncompiled ones like loaddefs.el and bindings.el; aside
 797  from that, it is always the .elc file that we look at, and they are no
 798  problem because byte-compiler output follows this convention.
 799  The NAME and DOCSTRING are output.
 800  NAME is preceded by `F' for a function or `V' for a variable.
 801  An entry is output only if DOCSTRING has \ newline just after the opening "
 802  */
 803
 804 void
 805 skip_white (infile)
 806      FILE *infile;
 807 {
 808   char c = ' ';
 809   while (c == ' ' || c == '\t' || c == '\n' || c == '\r')
 810     c = getc (infile);
 811   ungetc (c, infile);
 812 }
 813
 814 void
 815 read_lisp_symbol (infile, buffer)
 816      FILE *infile;
 817      char *buffer;
 818 {
 819   char c;
 820   char *fillp = buffer;
 821
 822   skip_white (infile);
 823   while (1)
 824     {
 825       c = getc (infile);
 826       if (c == '\\')
 827         *(++fillp) = getc (infile);
 828       else if (c == ' ' || c == '\t' || c == '\n' || c == '\r' || c == '(' || c == ')')
 829         {
 830           ungetc (c, infile);
 831           *fillp = 0;
 832           break;
 833         }
 834       else
 835         *fillp++ = c;
 836     }
 837
 838   if (! buffer[0])
 839     fprintf (stderr, "## expected a symbol, got '%c'\n", c);
 840
 841   skip_white (infile);
 842 }
 843
 844 int
 845 scan_lisp_file (filename, mode)
 846      char *filename, *mode;
 847 {
 848   FILE *infile;
 849   register int c;
 850   char *saved_string = 0;
 851
 852   infile = fopen (filename, mode);
 853   if (infile == NULL)
 854     {
 855       perror (filename);
 856       return 0;                         /* No error */
 857     }
 858
 859   c = '\n';
 860   while (!feof (infile))
 861     {
 862       char buffer[BUFSIZ];
 863       char type;
 864
 865       /* If not at end of line, skip till we get to one.  */
 866       if (c != '\n' && c != '\r')
 867         {
 868           c = getc (infile);
 869           continue;
 870         }
 871       /* Skip the line break.  */
 872       while (c == '\n' || c == '\r')
 873         c = getc (infile);
 874       /* Detect a dynamic doc string and save it for the next expression.  */
 875       if (c == '#')
 876         {
 877           c = getc (infile);
 878           if (c == '@')
 879             {
 880               int length = 0;
 881               int i;
 882
 883               /* Read the length.  */
 884               while ((c = getc (infile),
 885                       c >= '0' && c <= '9'))
 886                 {
 887                   length *= 10;
 888                   length += c - '0';
 889                 }
 890
 891               /* The next character is a space that is counted in the length
 892                  but not part of the doc string.
 893                  We already read it, so just ignore it.  */
 894               length--;
 895
 896               /* Read in the contents.  */
 897               if (saved_string != 0)
 898                 free (saved_string);
 899               saved_string = (char *) malloc (length);
 900               for (i = 0; i < length; i++)
 901                 saved_string[i] = getc (infile);
 902               /* The last character is a ^_.
 903                  That is needed in the .elc file
 904                  but it is redundant in DOC.  So get rid of it here.  */
 905               saved_string[length - 1] = 0;
 906               /* Skip the line break.  */
 907               while (c == '\n' && c == '\r')
 908                 c = getc (infile);
 909               /* Skip the following line.  */
 910               while (c != '\n' && c != '\r')
 911                 c = getc (infile);
 912             }
 913           continue;
 914         }
 915
 916       if (c != '(')
 917         continue;
 918
 919       read_lisp_symbol (infile, buffer);
 920
 921       if (! strcmp (buffer, "defun")
 922           || ! strcmp (buffer, "defmacro")
 923           || ! strcmp (buffer, "defsubst"))
 924         {
 925           type = 'F';
 926           read_lisp_symbol (infile, buffer);
 927
 928           /* Skip the arguments: either "nil" or a list in parens */
 929
 930           c = getc (infile);
 931           if (c == 'n') /* nil */
 932             {
 933               if ((c = getc (infile)) != 'i'
 934                   || (c = getc (infile)) != 'l')
 935                 {
 936                   fprintf (stderr, "## unparsable arglist in %s (%s)\n",
 937                            buffer, filename);
 938                   continue;
 939                 }
 940             }
 941           else if (c != '(')
 942             {
 943               fprintf (stderr, "## unparsable arglist in %s (%s)\n",
 944                        buffer, filename);
 945               continue;
 946             }
 947           else
 948             while (c != ')')
 949               c = getc (infile);
 950           skip_white (infile);
 951
 952           /* If the next three characters aren't `dquote bslash newline'
 953              then we're not reading a docstring.
 954            */
 955           if ((c = getc (infile)) != '"'
 956               || (c = getc (infile)) != '\\'
 957               || ((c = getc (infile)) != '\n' && c != '\r'))
 958             {
 959 #ifdef DEBUG
 960               fprintf (stderr, "## non-docstring in %s (%s)\n",
 961                        buffer, filename);
 962 #endif
 963               continue;
 964             }
 965         }
 966
 967       else if (! strcmp (buffer, "defvar")
 968                || ! strcmp (buffer, "defconst"))
 969         {
 970           char c1 = 0, c2 = 0;
 971           type = 'V';
 972           read_lisp_symbol (infile, buffer);
 973
 974           if (saved_string == 0)
 975             {
 976
 977               /* Skip until the end of line; remember two previous chars.  */
 978               while (c != '\n' && c != '\r' && c >= 0)
 979                 {
 980                   c2 = c1;
 981                   c1 = c;
 982                   c = getc (infile);
 983                 }
 984
 985               /* If two previous characters were " and \,
 986                  this is a doc string.  Otherwise, there is none.  */
 987               if (c2 != '"' || c1 != '\\')
 988                 {
 989 #ifdef DEBUG
 990                   fprintf (stderr, "## non-docstring in %s (%s)\n",
 991                            buffer, filename);
 992 #endif
 993                   continue;
 994                 }
 995             }
 996         }
 997
 998       else if (! strcmp (buffer, "custom-declare-variable"))
 999         {
1000           char c1 = 0, c2 = 0;
1001           type = 'V';
1002
1003           c = getc (infile);
1004           if (c == '\'')
1005             read_lisp_symbol (infile, buffer);
1006           else
1007             {
1008               if (c != '(')
1009                 {
1010                   fprintf (stderr,
1011                            "## unparsable name in custom-declare-variable in %s\n",
1012                            filename);
1013                   continue;
1014                 }
1015               read_lisp_symbol (infile, buffer);
1016               if (strcmp (buffer, "quote"))
1017                 {
1018                   fprintf (stderr,
1019                            "## unparsable name in custom-declare-variable in %s\n",
1020                            filename);
1021                   continue;
1022                 }
1023               read_lisp_symbol (infile, buffer);
1024               c = getc (infile);
1025               if (c != ')')
1026                 {
1027                   fprintf (stderr,
1028                            "## unparsable quoted name in custom-declare-variable in %s\n",
1029                            filename);
1030                   continue;
1031                 }
1032             }
1033
1034           if (saved_string == 0)
1035             {
1036               /* Skip to end of line; remember the two previous chars.  */
1037               while (c != '\n' && c != '\r' && c >= 0)
1038                 {
1039                   c2 = c1;
1040                   c1 = c;
1041                   c = getc (infile);
1042                 }
1043
1044               /* If two previous characters were " and \,
1045                  this is a doc string.  Otherwise, there is none.  */
1046               if (c2 != '"' || c1 != '\\')
1047                 {
1048 #ifdef DEBUG
1049                   fprintf (stderr, "## non-docstring in %s (%s)\n",
1050                            buffer, filename);
1051 #endif
1052                   continue;
1053                 }
1054             }
1055         }
1056
1057       else if (! strcmp (buffer, "fset") || ! strcmp (buffer, "defalias"))
1058         {
1059           char c1 = 0, c2 = 0;
1060           type = 'F';
1061
1062           c = getc (infile);
1063           if (c == '\'')
1064             read_lisp_symbol (infile, buffer);
1065           else
1066             {
1067               if (c != '(')
1068                 {
1069                   fprintf (stderr, "## unparsable name in fset in %s\n",
1070                            filename);
1071                   continue;
1072                 }
1073               read_lisp_symbol (infile, buffer);
1074               if (strcmp (buffer, "quote"))
1075                 {
1076                   fprintf (stderr, "## unparsable name in fset in %s\n",
1077                            filename);
1078                   continue;
1079                 }
1080               read_lisp_symbol (infile, buffer);
1081               c = getc (infile);
1082               if (c != ')')
1083                 {
1084                   fprintf (stderr,
1085                            "## unparsable quoted name in fset in %s\n",
1086                            filename);
1087                   continue;
1088                 }
1089             }
1090
1091           if (saved_string == 0)
1092             {
1093               /* Skip to end of line; remember the two previous chars.  */
1094               while (c != '\n' && c != '\r' && c >= 0)
1095                 {
1096                   c2 = c1;
1097                   c1 = c;
1098                   c = getc (infile);
1099                 }
1100
1101               /* If two previous characters were " and \,
1102                  this is a doc string.  Otherwise, there is none.  */
1103               if (c2 != '"' || c1 != '\\')
1104                 {
1105 #ifdef DEBUG
1106                   fprintf (stderr, "## non-docstring in %s (%s)\n",
1107                            buffer, filename);
1108 #endif
1109                   continue;
1110                 }
1111             }
1112         }
1113
1114       else if (! strcmp (buffer, "autoload"))
1115         {
1116           type = 'F';
1117           c = getc (infile);
1118           if (c == '\'')
1119             read_lisp_symbol (infile, buffer);
1120           else
1121             {
1122               if (c != '(')
1123                 {
1124                   fprintf (stderr, "## unparsable name in autoload in %s\n",
1125                            filename);
1126                   continue;
1127                 }
1128               read_lisp_symbol (infile, buffer);
1129               if (strcmp (buffer, "quote"))
1130                 {
1131                   fprintf (stderr, "## unparsable name in autoload in %s\n",
1132                            filename);
1133                   continue;
1134                 }
1135               read_lisp_symbol (infile, buffer);
1136               c = getc (infile);
1137               if (c != ')')
1138                 {
1139                   fprintf (stderr,
1140                            "## unparsable quoted name in autoload in %s\n",
1141                            filename);
1142                   continue;
1143                 }
1144             }
1145           skip_white (infile);
1146           if ((c = getc (infile)) != '\"')
1147             {
1148               fprintf (stderr, "## autoload of %s unparsable (%s)\n",
1149                        buffer, filename);
1150               continue;
1151             }
1152           read_c_string_or_comment (infile, 0, 0, 0);
1153           skip_white (infile);
1154
1155           if (saved_string == 0)
1156             {
1157               /* If the next three characters aren't `dquote bslash newline'
1158                  then we're not reading a docstring.  */
1159               if ((c = getc (infile)) != '"'
1160                   || (c = getc (infile)) != '\\'
1161                   || ((c = getc (infile)) != '\n' && c != '\r'))
1162                 {
1163 #ifdef DEBUG
1164                   fprintf (stderr, "## non-docstring in %s (%s)\n",
1165                            buffer, filename);
1166 #endif
1167                   continue;
1168                 }
1169             }
1170         }
1171
1172 #ifdef DEBUG
1173       else if (! strcmp (buffer, "if")
1174                || ! strcmp (buffer, "byte-code"))
1175         ;
1176 #endif
1177
1178       else
1179         {
1180 #ifdef DEBUG
1181           fprintf (stderr, "## unrecognised top-level form, %s (%s)\n",
1182                    buffer, filename);
1183 #endif
1184           continue;
1185         }
1186
1187       /* At this point, we should either use the previous
1188          dynamic doc string in saved_string
1189          or gobble a doc string from the input file.
1190
1191          In the latter case, the opening quote (and leading
1192          backslash-newline) have already been read.  */
1193
1194       putc (037, outfile);
1195       putc (type, outfile);
1196       fprintf (outfile, "%s\n", buffer);
1197       if (saved_string)
1198         {
1199           fputs (saved_string, outfile);
1200           /* Don't use one dynamic doc string twice.  */
1201           free (saved_string);
1202           saved_string = 0;
1203         }
1204       else
1205         read_c_string_or_comment (infile, 1, 0, 0);
1206     }
1207   fclose (infile);
1208   return 0;
1209 }
1210
1211 /* arch-tag: f7203aaf-991a-4238-acb5-601db56f2894
1212    (do not change this comment) */
1213
1214 /* make-docfile.c ends here */