lib-src/make-docfile.c

   1 /* Generate doc-string file for GNU Emacs from source files.
   2    Copyright (C) 1985, 1986, 1992, 1993, 1994 Free Software Foundation, Inc.
   3
   4 This file is part of GNU Emacs.
   5
   6 GNU Emacs is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Emacs is distributed in the hope that it will be useful,
  12 but WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14 GNU General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Emacs; see the file COPYING.  If not, write to
  18 the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.  */
  19
  20 /* The arguments given to this program are all the C and Lisp source files
  21  of GNU Emacs.  .elc and .el and .c files are allowed.
  22  A .o file can also be specified; the .c file it was made from is used.
  23  This helps the makefile pass the correct list of files.
  24
  25  The results, which go to standard output or to a file
  26  specified with -a or -o (-a to append, -o to start from nothing),
  27  are entries containing function or variable names and their documentation.
  28  Each entry starts with a ^_ character.
  29  Then comes F for a function or V for a variable.
  30  Then comes the function or variable name, terminated with a newline.
  31  Then comes the documentation for that function or variable.
  32  */
  33
  34 #include <stdio.h>
  35 #ifdef MSDOS
  36 #include <fcntl.h>
  37 #endif /* MSDOS */
  38
  39 #ifdef MSDOS
  40 #define READ_TEXT "rt"
  41 #define READ_BINARY "rb"
  42 #else /* not MSDOS */
  43 #define READ_TEXT "r"
  44 #define READ_BINARY "r"
  45 #endif /* not MSDOS */
  46
  47 FILE *outfile;
  48
  49 main (argc, argv)
  50      int argc;
  51      char **argv;
  52 {
  53   int i;
  54   int err_count = 0;
  55
  56 #ifdef MSDOS
  57   _fmode = O_BINARY;    /* all of files are treated as binary files */
  58   (stdout)->_flag &= ~_IOTEXT;
  59   _setmode (fileno (stdout), O_BINARY);
  60 #endif /* MSDOS */
  61   outfile = stdout;
  62
  63   /* If first two args are -o FILE, output to FILE.  */
  64   i = 1;
  65   if (argc > i + 1 && !strcmp (argv[i], "-o"))
  66     {
  67       outfile = fopen (argv[i + 1], "w");
  68       i += 2;
  69     }
  70   if (argc > i + 1 && !strcmp (argv[i], "-a"))
  71     {
  72       outfile = fopen (argv[i + 1], "a");
  73       i += 2;
  74     }
  75   if (argc > i + 1 && !strcmp (argv[i], "-d"))
  76     {
  77       chdir (argv[i + 1]);
  78       i += 2;
  79     }
  80
  81   for (; i < argc; i++)
  82     err_count += scan_file (argv[i]);   /* err_count seems to be {mis,un}used */
  83 #ifndef VMS
  84   exit (err_count);                     /* see below - shane */
  85 #endif /* VMS */
  86 }
  87
  88 /* Read file FILENAME and output its doc strings to outfile.  */
  89 /* Return 1 if file is not found, 0 if it is found.  */
  90
  91 scan_file (filename)
  92      char *filename;
  93 {
  94   int len = strlen (filename);
  95   if (!strcmp (filename + len - 4, ".elc"))
  96     return scan_lisp_file (filename, READ_BINARY);
  97   else if (!strcmp (filename + len - 3, ".el"))
  98     return scan_lisp_file (filename, READ_TEXT);
  99   else
 100     return scan_c_file (filename, READ_TEXT);
 101 }
 102 \f
 103 char buf[128];
 104
 105 /* Skip a C string from INFILE,
 106  and return the character that follows the closing ".
 107  If printflag is positive, output string contents to outfile.
 108  If it is negative, store contents in buf.
 109  Convert escape sequences \n and \t to newline and tab;
 110  discard \ followed by newline.  */
 111
 112 read_c_string (infile, printflag)
 113      FILE *infile;
 114      int printflag;
 115 {
 116   register int c;
 117   char *p = buf;
 118
 119   c = getc (infile);
 120   while (c != EOF)
 121     {
 122       while (c != '"' && c != EOF)
 123         {
 124           if (c == '\\')
 125             {
 126               c = getc (infile);
 127               if (c == '\n')
 128                 {
 129                   c = getc (infile);
 130                   continue;
 131                 }
 132               if (c == 'n')
 133                 c = '\n';
 134               if (c == 't')
 135                 c = '\t';
 136             }
 137           if (printflag > 0)
 138             putc (c, outfile);
 139           else if (printflag < 0)
 140             *p++ = c;
 141           c = getc (infile);
 142         }
 143       c = getc (infile);
 144       if (c != '"')
 145         break;
 146       /* If we had a "", concatenate the two strings.  */
 147       c = getc (infile);
 148     }
 149
 150   if (printflag < 0)
 151     *p = 0;
 152
 153   return c;
 154 }
 155 \f
 156 /* Write to file OUT the argument names of function FUNC, whose text is in BUF.
 157    MINARGS and MAXARGS are the minimum and maximum number of arguments.  */
 158
 159 write_c_args (out, func, buf, minargs, maxargs)
 160      FILE *out;
 161      char *func, *buf;
 162      int minargs, maxargs;
 163 {
 164   register char *p;
 165   int in_ident = 0;
 166   int just_spaced = 0;
 167   int need_space = 1;
 168
 169   fprintf (out, "(%s", func);
 170
 171   if (*buf == '(')
 172     ++buf;
 173
 174   for (p = buf; *p; p++)
 175     {
 176       char c = *p;
 177       int ident_start = 0;
 178
 179       /* Notice when we start printing a new identifier.  */
 180       if ((('A' <= c && c <= 'Z')
 181            || ('a' <= c && c <= 'z')
 182            || ('0' <= c && c <= '9')
 183            || c == '_')
 184           != in_ident)
 185         {
 186           if (!in_ident)
 187             {
 188               in_ident = 1;
 189               ident_start = 1;
 190
 191               if (need_space)
 192                 putc (' ', out);
 193
 194               if (minargs == 0 && maxargs > 0)
 195                 fprintf (out, "&optional ");
 196               just_spaced = 1;
 197
 198               minargs--;
 199               maxargs--;
 200             }
 201           else
 202             in_ident = 0;
 203         }
 204
 205       /* Print the C argument list as it would appear in lisp:
 206          print underscores as hyphens, and print commas as spaces.
 207          Collapse adjacent spaces into one.  */
 208       if (c == '_') c = '-';
 209       if (c == ',') c = ' ';
 210
 211       /* In C code, `default' is a reserved word, so we spell it
 212          `defalt'; unmangle that here.  */
 213       if (ident_start
 214           && strncmp (p, "defalt", 6) == 0
 215           && ! (('A' <= p[6] && p[6] <= 'Z')
 216                 || ('a' <= p[6] && p[6] <= 'z')
 217                 || ('0' <= p[6] && p[6] <= '9')
 218                 || p[6] == '_'))
 219         {
 220           fprintf (out, "default");
 221           p += 5;
 222           in_ident = 0;
 223           just_spaced = 0;
 224         }
 225       else if (c != ' ' || ! just_spaced)
 226         {
 227           if (c >= 'a' && c <= 'z')
 228             /* Upcase the letter.  */
 229             c += 'A' - 'a';
 230           putc (c, out);
 231         }
 232
 233       just_spaced = (c == ' ');
 234       need_space = 0;
 235     }
 236 }
 237 \f
 238 /* Read through a c file.  If a .o file is named,
 239    the corresponding .c file is read instead.
 240    Looks for DEFUN constructs such as are defined in ../src/lisp.h.
 241    Accepts any word starting DEF... so it finds DEFSIMPLE and DEFPRED.  */
 242
 243 scan_c_file (filename, mode)
 244      char *filename, *mode;
 245 {
 246   FILE *infile;
 247   register int c;
 248   register int commas;
 249   register int defunflag;
 250   register int defvarperbufferflag;
 251   register int defvarflag;
 252   int minargs, maxargs;
 253
 254   if (filename[strlen (filename) - 1] == 'o')
 255     filename[strlen (filename) - 1] = 'c';
 256
 257   infile = fopen (filename, mode);
 258
 259   /* No error if non-ex input file */
 260   if (infile == NULL)
 261     {
 262       perror (filename);
 263       return 0;
 264     }
 265
 266   c = '\n';
 267   while (!feof (infile))
 268     {
 269       if (c != '\n')
 270         {
 271           c = getc (infile);
 272           continue;
 273         }
 274       c = getc (infile);
 275       if (c == ' ')
 276         {
 277           while (c == ' ')
 278             c = getc (infile);
 279           if (c != 'D')
 280             continue;
 281           c = getc (infile);
 282           if (c != 'E')
 283             continue;
 284           c = getc (infile);
 285           if (c != 'F')
 286             continue;
 287           c = getc (infile);
 288           if (c != 'V')
 289             continue;
 290           c = getc (infile);
 291           if (c != 'A')
 292             continue;
 293           c = getc (infile);
 294           if (c != 'R')
 295             continue;
 296           c = getc (infile);
 297           if (c != '_')
 298             continue;
 299
 300           defvarflag = 1;
 301           defunflag = 0;
 302
 303           c = getc (infile);
 304           defvarperbufferflag = (c == 'P');
 305
 306           c = getc (infile);
 307         }
 308       else if (c == 'D')
 309         {
 310           c = getc (infile);
 311           if (c != 'E')
 312             continue;
 313           c = getc (infile);
 314           if (c != 'F')
 315             continue;
 316           c = getc (infile);
 317           defunflag = c == 'U';
 318           defvarflag = 0;
 319         }
 320       else continue;
 321
 322       while (c != '(')
 323         {
 324           if (c < 0)
 325             goto eof;
 326           c = getc (infile);
 327         }
 328
 329       c = getc (infile);
 330       if (c != '"')
 331         continue;
 332       c = read_c_string (infile, -1);
 333
 334       if (defunflag)
 335         commas = 5;
 336       else if (defvarperbufferflag)
 337         commas = 2;
 338       else if (defvarflag)
 339         commas = 1;
 340       else  /* For DEFSIMPLE and DEFPRED */
 341         commas = 2;
 342
 343       while (commas)
 344         {
 345           if (c == ',')
 346             {
 347               commas--;
 348               if (defunflag && (commas == 1 || commas == 2))
 349                 {
 350                   do
 351                     c = getc (infile);
 352                   while (c == ' ' || c == '\n' || c == '\t');
 353                   if (c < 0)
 354                     goto eof;
 355                   ungetc (c, infile);
 356                   if (commas == 2) /* pick up minargs */
 357                     fscanf (infile, "%d", &minargs);
 358                   else /* pick up maxargs */
 359                     if (c == 'M' || c == 'U') /* MANY || UNEVALLED */
 360                       maxargs = -1;
 361                     else
 362                       fscanf (infile, "%d", &maxargs);
 363                 }
 364             }
 365           if (c < 0)
 366             goto eof;
 367           c = getc (infile);
 368         }
 369       while (c == ' ' || c == '\n' || c == '\t')
 370         c = getc (infile);
 371       if (c == '"')
 372         c = read_c_string (infile, 0);
 373       while (c != ',')
 374         c = getc (infile);
 375       c = getc (infile);
 376       while (c == ' ' || c == '\n' || c == '\t')
 377         c = getc (infile);
 378
 379       if (c == '"')
 380         {
 381           putc (037, outfile);
 382           putc (defvarflag ? 'V' : 'F', outfile);
 383           fprintf (outfile, "%s\n", buf);
 384           c = read_c_string (infile, 1);
 385
 386           /* If this is a defun, find the arguments and print them.  If
 387              this function takes MANY or UNEVALLED args, then the C source
 388              won't give the names of the arguments, so we shouldn't bother
 389              trying to find them.  */
 390           if (defunflag && maxargs != -1)
 391             {
 392               char argbuf[1024], *p = argbuf;
 393               while (c != ')')
 394                 {
 395                   if (c < 0)
 396                     goto eof;
 397                   c = getc (infile);
 398                 }
 399               /* Skip into arguments.  */
 400               while (c != '(')
 401                 {
 402                   if (c < 0)
 403                     goto eof;
 404                   c = getc (infile);
 405                 }
 406               /* Copy arguments into ARGBUF.  */
 407               *p++ = c;
 408               do
 409                 *p++ = c = getc (infile);
 410               while (c != ')');
 411               *p = '\0';
 412               /* Output them.  */
 413               fprintf (outfile, "\n\n");
 414               write_c_args (outfile, buf, argbuf, minargs, maxargs);
 415             }
 416         }
 417     }
 418  eof:
 419   fclose (infile);
 420   return 0;
 421 }
 422 \f
 423 /* Read a file of Lisp code, compiled or interpreted.
 424  Looks for
 425   (defun NAME ARGS DOCSTRING ...)
 426   (defmacro NAME ARGS DOCSTRING ...)
 427   (autoload (quote NAME) FILE DOCSTRING ...)
 428   (defvar NAME VALUE DOCSTRING)
 429   (defconst NAME VALUE DOCSTRING)
 430   (fset (quote NAME) (make-byte-code ... DOCSTRING ...))
 431   (fset (quote NAME) #[... DOCSTRING ...])
 432   (defalias (quote NAME) #[... DOCSTRING ...])
 433  starting in column zero.
 434  (quote NAME) may appear as 'NAME as well.
 435  For defun, defmacro, and autoload, we know how to skip over the arglist.
 436  For defvar, defconst, and fset we skip to the docstring with a kludgy
 437  formatting convention: all docstrings must appear on the same line as the
 438  initial open-paren (the one in column zero) and must contain a backslash
 439  and a double-quote immediately after the initial double-quote.  No newlines
 440  must appear between the beginning of the form and the first double-quote.
 441  The only source file that must follow this convention is loaddefs.el; aside
 442  from that, it is always the .elc file that we look at, and they are no
 443  problem because byte-compiler output follows this convention.
 444  The NAME and DOCSTRING are output.
 445  NAME is preceded by `F' for a function or `V' for a variable.
 446  An entry is output only if DOCSTRING has \ newline just after the opening "
 447  */
 448
 449 void
 450 skip_white (infile)
 451      FILE *infile;
 452 {
 453   char c = ' ';
 454   while (c == ' ' || c == '\t' || c == '\n')
 455     c = getc (infile);
 456   ungetc (c, infile);
 457 }
 458
 459 void
 460 read_lisp_symbol (infile, buffer)
 461      FILE *infile;
 462      char *buffer;
 463 {
 464   char c;
 465   char *fillp = buffer;
 466
 467   skip_white (infile);
 468   while (1)
 469     {
 470       c = getc (infile);
 471       if (c == '\\')
 472         *(++fillp) = getc (infile);
 473       else if (c == ' ' || c == '\t' || c == '\n' || c == '(' || c == ')')
 474         {
 475           ungetc (c, infile);
 476           *fillp = 0;
 477           break;
 478         }
 479       else
 480         *fillp++ = c;
 481     }
 482
 483   if (! buffer[0])
 484     fprintf (stderr, "## expected a symbol, got '%c'\n", c);
 485
 486   skip_white (infile);
 487 }
 488
 489
 490 scan_lisp_file (filename, mode)
 491      char *filename, *mode;
 492 {
 493   FILE *infile;
 494   register int c;
 495
 496   infile = fopen (filename, mode);
 497   if (infile == NULL)
 498     {
 499       perror (filename);
 500       return 0;                         /* No error */
 501     }
 502
 503   c = '\n';
 504   while (!feof (infile))
 505     {
 506       char buffer [BUFSIZ];
 507       char *fillp = buffer;
 508       char type;
 509
 510       if (c != '\n')
 511         {
 512           c = getc (infile);
 513           continue;
 514         }
 515       c = getc (infile);
 516       if (c != '(')
 517         continue;
 518
 519       read_lisp_symbol (infile, buffer);
 520
 521       if (! strcmp (buffer, "defun") ||
 522           ! strcmp (buffer, "defmacro"))
 523         {
 524           type = 'F';
 525           read_lisp_symbol (infile, buffer);
 526
 527           /* Skip the arguments: either "nil" or a list in parens */
 528
 529           c = getc (infile);
 530           if (c == 'n') /* nil */
 531             {
 532               if ((c = getc (infile)) != 'i' ||
 533                   (c = getc (infile)) != 'l')
 534                 {
 535                   fprintf (stderr, "## unparsable arglist in %s (%s)\n",
 536                            buffer, filename);
 537                   continue;
 538                 }
 539             }
 540           else if (c != '(')
 541             {
 542               fprintf (stderr, "## unparsable arglist in %s (%s)\n",
 543                        buffer, filename);
 544               continue;
 545             }
 546           else
 547             while (c != ')')
 548               c = getc (infile);
 549           skip_white (infile);
 550
 551           /* If the next three characters aren't `dquote bslash newline'
 552              then we're not reading a docstring.
 553            */
 554           if ((c = getc (infile)) != '"' ||
 555               (c = getc (infile)) != '\\' ||
 556               (c = getc (infile)) != '\n')
 557             {
 558 #ifdef DEBUG
 559               fprintf (stderr, "## non-docstring in %s (%s)\n",
 560                        buffer, filename);
 561 #endif
 562               continue;
 563             }
 564         }
 565
 566       else if (! strcmp (buffer, "defvar") ||
 567                ! strcmp (buffer, "defconst"))
 568         {
 569           char c1 = 0, c2 = 0;
 570           type = 'V';
 571           read_lisp_symbol (infile, buffer);
 572
 573           /* Skip until the first newline; remember the two previous chars. */
 574           while (c != '\n' && c >= 0)
 575             {
 576               c2 = c1;
 577               c1 = c;
 578               c = getc (infile);
 579             }
 580
 581           /* If two previous characters were " and \,
 582              this is a doc string.  Otherwise, there is none.  */
 583           if (c2 != '"' || c1 != '\\')
 584             {
 585 #ifdef DEBUG
 586               fprintf (stderr, "## non-docstring in %s (%s)\n",
 587                        buffer, filename);
 588 #endif
 589               continue;
 590             }
 591         }
 592
 593       else if (! strcmp (buffer, "fset") || ! strcmp (buffer, "defalias"))
 594         {
 595           char c1 = 0, c2 = 0;
 596           type = 'F';
 597
 598           c = getc (infile);
 599           if (c == '\'')
 600             read_lisp_symbol (infile, buffer);
 601           else
 602             {
 603               if (c != '(')
 604                 {
 605                   fprintf (stderr, "## unparsable name in fset in %s\n",
 606                            filename);
 607                   continue;
 608                 }
 609               read_lisp_symbol (infile, buffer);
 610               if (strcmp (buffer, "quote"))
 611                 {
 612                   fprintf (stderr, "## unparsable name in fset in %s\n",
 613                            filename);
 614                   continue;
 615                 }
 616               read_lisp_symbol (infile, buffer);
 617               c = getc (infile);
 618               if (c != ')')
 619                 {
 620                   fprintf (stderr,
 621                            "## unparsable quoted name in fset in %s\n",
 622                            filename);
 623                   continue;
 624                 }
 625             }
 626
 627           /* Skip until the first newline; remember the two previous chars. */
 628           while (c != '\n' && c >= 0)
 629             {
 630               c2 = c1;
 631               c1 = c;
 632               c = getc (infile);
 633             }
 634
 635           /* If two previous characters were " and \,
 636              this is a doc string.  Otherwise, there is none.  */
 637           if (c2 != '"' || c1 != '\\')
 638             {
 639 #ifdef DEBUG
 640               fprintf (stderr, "## non-docstring in %s (%s)\n",
 641                        buffer, filename);
 642 #endif
 643               continue;
 644             }
 645         }
 646
 647       else if (! strcmp (buffer, "autoload"))
 648         {
 649           type = 'F';
 650           c = getc (infile);
 651           if (c == '\'')
 652             read_lisp_symbol (infile, buffer);
 653           else
 654             {
 655               if (c != '(')
 656                 {
 657                   fprintf (stderr, "## unparsable name in autoload in %s\n",
 658                            filename);
 659                   continue;
 660                 }
 661               read_lisp_symbol (infile, buffer);
 662               if (strcmp (buffer, "quote"))
 663                 {
 664                   fprintf (stderr, "## unparsable name in autoload in %s\n",
 665                            filename);
 666                   continue;
 667                 }
 668               read_lisp_symbol (infile, buffer);
 669               c = getc (infile);
 670               if (c != ')')
 671                 {
 672                   fprintf (stderr,
 673                            "## unparsable quoted name in autoload in %s\n",
 674                            filename);
 675                   continue;
 676                 }
 677             }
 678           skip_white (infile);
 679           if ((c = getc (infile)) != '\"')
 680             {
 681               fprintf (stderr, "## autoload of %s unparsable (%s)\n",
 682                        buffer, filename);
 683               continue;
 684             }
 685           read_c_string (infile, 0);
 686           skip_white (infile);
 687
 688           /* If the next three characters aren't `dquote bslash newline'
 689              then we're not reading a docstring.
 690            */
 691           if ((c = getc (infile)) != '"' ||
 692               (c = getc (infile)) != '\\' ||
 693               (c = getc (infile)) != '\n')
 694             {
 695 #ifdef DEBUG
 696               fprintf (stderr, "## non-docstring in %s (%s)\n",
 697                        buffer, filename);
 698 #endif
 699               continue;
 700             }
 701         }
 702
 703 #ifdef DEBUG
 704       else if (! strcmp (buffer, "if") ||
 705                ! strcmp (buffer, "byte-code"))
 706         ;
 707 #endif
 708
 709       else
 710         {
 711 #ifdef DEBUG
 712           fprintf (stderr, "## unrecognised top-level form, %s (%s)\n",
 713                    buffer, filename);
 714 #endif
 715           continue;
 716         }
 717
 718       /* At this point, there is a docstring that we should gobble.
 719          The opening quote (and leading backslash-newline) have already
 720          been read.
 721        */
 722       putc (037, outfile);
 723       putc (type, outfile);
 724       fprintf (outfile, "%s\n", buffer);
 725       read_c_string (infile, 1);
 726     }
 727   fclose (infile);
 728   return 0;
 729 }