DOC for Mac OS shown for Emacs compiled for X.

DOC for Mac OS shown for Emacs compiled for X.

[Jan D.]

Hello.

With an Emacs built for X I do C-h f x-server-vendor and get the MacOS help:

...
Returns the vendor ID string of the Mac OS system (Apple).
...

I should get the X version:

...
Returns the vendor ID string of the X server of display DISPLAY.
...

x-server-vendor is defined in xfns.c, macfns.c and w32fns.c.  Both xfns.o and 
macfns.o are in SOME_MACHINE_OBJECTS in Makefile.in.   SOME_MACHINE_OBJECTS is 
given to make-docfile as arguments.  Thus, two versions for x-server-vendor 
ends up in DOC.  I don't really know what is wrong here, there are several 
possibilities:

1.  make-docfile should not read the .c file if the .o one does not exist.
2.  Emacs is supposed to find the correct entry in DOC.
3.  macfns.o should not be in SOME_MACHINE_OBJECTS when building for X.
4.  Symbols that occur in several files (x, mac, w32) should have the same doc
     string.


If someone can tell me which one is the preferred way to resolve this, I can do it.

Thanks,

	Jan D.

Re: DOC for Mac OS shown for Emacs compiled for X.

[Andreas Schwab]

"Jan D." <jan.h.d@swipnet.se> writes:

> 3.  macfns.o should not be in SOME_MACHINE_OBJECTS when building for X.

This is not a good thing to do, because the DOC file is supposed to be
system independent.

Andreas.

-- 
Andreas Schwab, SuSE Labs, schwab@suse.de
SuSE Linux AG, Maxfeldstraße 5, 90409 Nürnberg, Germany
Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: DOC for Mac OS shown for Emacs compiled for X.

[Jan D.]

>
>> 3.  macfns.o should not be in SOME_MACHINE_OBJECTS when building for 
>> X.
>
> This is not a good thing to do, because the DOC file is supposed to be
> system independent.

What does that mean exactly?  Should I be able to take a DOC produced
on a Mac and use it on GNU/Linux or W32?

	Jan D.

Re: DOC for Mac OS shown for Emacs compiled for X.

[Andreas Schwab]

"Jan D." <jan.h.d@swipnet.se> writes:

> What does that mean exactly?  Should I be able to take a DOC produced
> on a Mac and use it on GNU/Linux or W32?

Yes.  That's why it is installed below $datadir.

Andreas.

-- 
Andreas Schwab, SuSE Labs, schwab@suse.de
SuSE Linux AG, Maxfeldstraße 5, 90409 Nürnberg, Germany
Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: DOC for Mac OS shown for Emacs compiled for X.

[Jan D.]

> "Jan D." <jan.h.d@swipnet.se> writes:
>
>> What does that mean exactly?  Should I be able to take a DOC produced
>> on a Mac and use it on GNU/Linux or W32?
>
> Yes.  That's why it is installed below $datadir.

Okay, then there is trouble, because that does not work today.
If I compile and run an X, non-carbon, version of Emacs on Mac OSX, I 
get
the DOC entry for x-server-vendor that says it returns "Apple" (in
fact, "Apple Computers" is returned for carbon).  But for an X version
the return value is "The XFree86 Project, Inc".

The w32 DOC entry says x-server-vendor returns "Microsoft", but that
entry is not even in a DOC file produced when building on Mac OSX, so
I don't understand how such a DOC file can be used on w32.  Should the
w32 files also be in SOME_MACHINE_OBJECTS?

I guess a table of what object files where used to link the binary 
could be
generated and from that Emacs could find the correct DOC entry (and
the correct C file, C-h f x-server-vendor and clicking on "C source 
code"
always gives xfns.c, should be macfns.c for a carbon build).

	Jan D.

Re: DOC for Mac OS shown for Emacs compiled for X.

[Andreas Schwab]

"Jan D." <jan.h.d@swipnet.se> writes:

> The w32 DOC entry says x-server-vendor returns "Microsoft", but that
> entry is not even in a DOC file produced when building on Mac OSX, so
> I don't understand how such a DOC file can be used on w32.  Should the
> w32 files also be in SOME_MACHINE_OBJECTS?

We had this topic already 2 years ago, starting at
<http://lists.gnu.org/archive/html/emacs-devel/2002-05/msg01112.html> and
continuing at
<http://lists.gnu.org/archive/html/emacs-devel/2002-06/msg00000.html>
(it's a big thread).

Andreas.

-- 
Andreas Schwab, SuSE Labs, schwab@suse.de
SuSE Linux AG, Maxfeldstraße 5, 90409 Nürnberg, Germany
Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: DOC for Mac OS shown for Emacs compiled for X.

[Stefan]

>>> What does that mean exactly?  Should I be able to take a DOC produced
>>> on a Mac and use it on GNU/Linux or W32?
>> Yes.  That's why it is installed below $datadir.
> Okay, then there is trouble, because that does not work today.

Yes, it gets broken fairly often.  We should fix it.


        Stefan

Re: DOC for Mac OS shown for Emacs compiled for X.

[Jan D.]

> >>> What does that mean exactly?  Should I be able to take a DOC produced
> >>> on a Mac and use it on GNU/Linux or W32?
> >> Yes.  That's why it is installed below $datadir.
> > Okay, then there is trouble, because that does not work today.
> 
> Yes, it gets broken fairly often.  We should fix it.
> 

Is the approach in the attached patch OK?  I generate a list with the objects used to build Emacs and in Snarf-documentation I compare the files in DOC with that list.  If not in that list, those sections in DOC are skipped.

Probably some adjustments needs to be made for w32 and msdos, I think someone mentioned that they put .c file names into DOC, and also build files are not named .o, but .obj.  The code that finds the C source should be adjusted to look at the list also.

The tests I've done suggests this fixes the problem I originally encountered, and I have not seen any regression.  But I am not all that familiar with the help code, so I may have overlooked something obvious.

Comments?

	Jan D.

diff -c Makefile.in.~1.303.~ Makefile.in
Index: Makefile.in
*** Makefile.in.~1.303.~	2004-10-20 17:44:02.000000000 +0200
--- Makefile.in	2004-10-28 21:46:59.000000000 +0200
***************
*** 943,953 ****
  #define MAKE_PARALLEL
  #endif
  
! temacs${EXEEXT}: MAKE_PARALLEL $(LOCALCPP) $(STARTFILES) stamp-oldxmenu ${obj} ${otherobj} OBJECTS_MACHINE prefix-args${EXEEXT}
  	$(LD) YMF_PASS_LDFLAGS (${STARTFLAGS} ${TEMACS_LDFLAGS}) $(LDFLAGS) \
      -o temacs ${STARTFILES} ${obj} ${otherobj}  \
      OBJECTS_MACHINE ${LIBES}
  
  /* We don't use ALL_LDFLAGS because LD_SWITCH_SYSTEM and LD_SWITCH_MACHINE
     often contain options that have to do with using Emacs's crt0,
     which are only good with temacs.  */
--- 943,956 ----
  #define MAKE_PARALLEL
  #endif
  
! temacs${EXEEXT}: MAKE_PARALLEL $(LOCALCPP) $(STARTFILES) stamp-oldxmenu ${obj} ${otherobj} OBJECTS_MACHINE prefix-args${EXEEXT} buildobj.lst
  	$(LD) YMF_PASS_LDFLAGS (${STARTFLAGS} ${TEMACS_LDFLAGS}) $(LDFLAGS) \
      -o temacs ${STARTFILES} ${obj} ${otherobj}  \
      OBJECTS_MACHINE ${LIBES}
  
+ buildobj.lst:
+ 	echo "${obj} ${otherobj} " OBJECTS_MACHINE > buildobj.lst
+ 
  /* We don't use ALL_LDFLAGS because LD_SWITCH_SYSTEM and LD_SWITCH_MACHINE
     often contain options that have to do with using Emacs's crt0,
     which are only good with temacs.  */
diff -c doc.c.~1.108.~ doc.c
Index: doc.c
*** doc.c.~1.108.~	2004-10-28 22:22:33.000000000 +0200
--- doc.c	2004-10-29 09:59:45.000000000 +0200
***************
*** 51,56 ****
--- 51,59 ----
  
  Lisp_Object Qfunction_documentation;
  
+ /* A list of files used to build this Emacs binary.  */
+ static Lisp_Object Vbuild_files;
+ 
  extern Lisp_Object Voverriding_local_map;
  
  /* For VMS versions with limited file name syntax,
***************
*** 581,586 ****
--- 584,590 ----
    register char *p, *end;
    Lisp_Object sym;
    char *name;
+   int skip_file = 0;
  
    CHECK_STRING (filename);
  
***************
*** 617,622 ****
--- 621,656 ----
    strcpy (name, sys_translate_unix (name));
  #endif /* VMS4_4 */
  #endif /* VMS */
+   
+   {
+     size_t cp_size = 0;
+     size_t to_read;
+     int nr_read;
+     char *cp = NULL;
+ 
+     fd = emacs_open ("buildobj.lst", O_RDONLY, 0);
+     if (fd < 0)
+       report_file_error ("Opening file buildobj.lst", Qnil);
+ 
+     filled = 0;
+     for (;;)
+       {
+         cp_size += 1024;
+         to_read = cp_size - 1 - filled;
+         cp = xrealloc (cp, cp_size);
+         nr_read = emacs_read (fd, &cp[filled], to_read);
+         filled += nr_read;
+         if (nr_read < to_read)
+           break;
+       }
+ 
+     cp[filled] = 0;
+ 
+     Vbuild_files = Feval (Fcons (intern ("split-string"),
+                                  Fcons (build_string (cp), Qnil)));
+     emacs_close (fd);
+     xfree (cp);
+   }
  
    fd = emacs_open (name, O_RDONLY, 0);
    if (fd < 0)
***************
*** 640,649 ****
        if (p != end)
  	{
  	  end = (char *) index (p, '\n');
  	  sym = oblookup (Vobarray, p + 2,
  			  multibyte_chars_in_text (p + 2, end - p - 2),
  			  end - p - 2);
! 	  if (SYMBOLP (sym))
  	    {
  	      /* Attach a docstring to a variable?  */
  	      if (p[1] == 'V')
--- 674,698 ----
        if (p != end)
  	{
  	  end = (char *) index (p, '\n');
+ 
+           /* See if this is a file name, and if it is a file in build-files.  */
+           if (p[1] == 'S' && end - p > 4 && end[-2] == '.' && end[-1] == 'o')
+             {
+               int len = end - p - 2;
+               char *fromfile = alloca (len + 1);
+               strncpy (fromfile, &p[2], len);
+               fromfile[len] = 0;
+ 
+               if (EQ (Fmember (build_string (fromfile), Vbuild_files), Qnil))
+                 skip_file = 1;
+               else
+                 skip_file = 0;
+             }
+ 
  	  sym = oblookup (Vobarray, p + 2,
  			  multibyte_chars_in_text (p + 2, end - p - 2),
  			  end - p - 2);
! 	  if (! skip_file && SYMBOLP (sym))
  	    {
  	      /* Attach a docstring to a variable?  */
  	      if (p[1] == 'V')
***************
*** 919,924 ****
--- 968,977 ----
  	       doc: /* Name of file containing documentation strings of built-in symbols.  */);
    Vdoc_file_name = Qnil;
  
+   DEFVAR_LISP ("build-files", &Vbuild_files,
+                doc: /* A list of files used to build this Emacs binary.  */);
+   Vbuild_files = Qnil;
+ 
    defsubr (&Sdocumentation);
    defsubr (&Sdocumentation_property);
    defsubr (&Ssnarf_documentation);

Re: DOC for Mac OS shown for Emacs compiled for X.

[Stefan]

> Is the approach in the attached patch OK?  I generate a list with the
> objects used to build Emacs and in Snarf-documentation I compare the files
> in DOC with that list.  If not in that list, those sections in DOC
> are skipped.

I think instead that the docstring should be the same no matter what system
I'm running on.  If the behavior is not quite the same, either the docstring
should be general enough to describe the common part, or it should include
a discussion of the possible differences on various platforms.

This way I can write code on GNU/Linux and be warned if I'm using things
that might work differently on some other system.


        Stefan

Re: DOC for Mac OS shown for Emacs compiled for X.

[Jan D.]

>> Is the approach in the attached patch OK?  I generate a list with the
>> objects used to build Emacs and in Snarf-documentation I compare the 
>> files
>> in DOC with that list.  If not in that list, those sections in DOC
>> are skipped.
>
> I think instead that the docstring should be the same no matter what 
> system
> I'm running on.  If the behavior is not quite the same, either the 
> docstring
> should be general enough to describe the common part, or it should 
> include
> a discussion of the possible differences on various platforms.
>
> This way I can write code on GNU/Linux and be warned if I'm using 
> things
> that might work differently on some other system.

That is also possible, and seems to be what the previous discussion 
indicated.  More work though.  And it does not solve the error that
doing C-h f x-server-vendor and clicking on the "C source code" link
gives xfns.c when it should give macfns.c.  I think a list of what 
files where used in the link is the only way to solve this.  For a 
build on Mac OSX xfns.c or macfns.c could be used, depending on if it 
was an X build or Carbon build.

	Jan D.

Re: DOC for Mac OS shown for Emacs compiled for X.

[Stefan]

> That is also possible, and seems to be what the previous discussion
> indicated.  More work though.

But better result.

> And it does not solve the error that doing C-h f x-server-vendor and
> clicking on the "C source code" link gives xfns.c when it should give
> macfns.c.  I think a list of what files where used in the link is the only
> way to solve this.  For a build on Mac OSX xfns.c or macfns.c could be
> used, depending on if it was an X build or Carbon build.

I'd just move all those DEFUNs to a shared file.  If necessary the body of
those DEFUNs can just be a call to some function that's either in macfns.c
or xfns.c, tho ideally some actual code should be shared.


        Stefan

Re: DOC for Mac OS shown for Emacs compiled for X.

[Jan D.]

2004-10-29 kl. 23.48 skrev Stefan:

>> That is also possible, and seems to be what the previous discussion
>> indicated.  More work though.
>
> But better result.

I disagree, if I run Emacs on X I don't want to wade through lines of 
documentation that applies for W32/msdos/OSX.

>
>> And it does not solve the error that doing C-h f x-server-vendor and
>> clicking on the "C source code" link gives xfns.c when it should give
>> macfns.c.  I think a list of what files where used in the link is the 
>> only
>> way to solve this.  For a build on Mac OSX xfns.c or macfns.c could be
>> used, depending on if it was an X build or Carbon build.
>
> I'd just move all those DEFUNs to a shared file.  If necessary the 
> body of
> those DEFUNs can just be a call to some function that's either in 
> macfns.c
> or xfns.c, tho ideally some actual code should be shared.

I don't think adding two maintainence tasks (keeping doc-strings in 
sync and making sure all shared functions go into the shared file) we 
have to keep doing forever is better than solving it once and for all.  
And if the real function is in another file the benefit of clicking on 
"C source code" is reduced.

	Jan D.

Re: DOC for Mac OS shown for Emacs compiled for X.

[Stefan]

>>> That is also possible, and seems to be what the previous discussion
>>> indicated.  More work though.
>> But better result.
> I disagree, if I run Emacs on X I don't want to wade through lines of
> documentation that applies for W32/msdos/OSX.

My take on this is that if the documentation is very different for each
system, then either the function's functionality is ill-defined or the
docstring gives too much precision.

> And if the real function is in another file the benefit of clicking on "C
> source code" is reduced.

Good point.  Richard's suggestion to tweak the link-following code
so as to look for macfoo.c (or w32foo.c) is a better idea.


        Stefan

Re: DOC for Mac OS shown for Emacs compiled for X.

[Jan D.]

>
> My take on this is that if the documentation is very different for each
> system, then either the function's functionality is ill-defined or the
> docstring gives too much precision.

This is probably correct.  But most functions have been defined on X 
for Unix and then kind of adopted for the other platforms, sometimes 
with a bad fit.

>
>> And if the real function is in another file the benefit of clicking 
>> on "C
>> source code" is reduced.
>
> Good point.  Richard's suggestion to tweak the link-following code
> so as to look for macfoo.c (or w32foo.c) is a better idea.

There is also one defun (x-selection-exists-p) that is in mac.c instead 
of xselect.c (there is no macselect.c) that will be wrong.  I already 
have a modified help-fns.el (6 lines added) that can handle this my 
way, but I guess it is not important.

	Jan D.

Re: DOC for Mac OS shown for Emacs compiled for X.

[Kim F. Storm]

"Jan D." <jan.h.d@swipnet.se> writes:

> 2004-10-29 kl. 23.48 skrev Stefan:
>
>>> That is also possible, and seems to be what the previous discussion
>>> indicated.  More work though.
>>
>> But better result.
>
> I disagree, if I run Emacs on X I don't want to wade through lines of
> documentation that applies for W32/msdos/OSX.

I agree -- and I think your approach to do this is excellent.

If I ever need info about w32 or mac specific functions, I
just look in the source :-)

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: DOC for Mac OS shown for Emacs compiled for X.

[Richard Stallman]

      And it does not solve the error that
    doing C-h f x-server-vendor and clicking on the "C source code" link
    gives xfns.c when it should give macfns.c.  I think a list of what 
    files where used in the link is the only way to solve this.

I wouldn't suggest that either of you spend any time on this, but if
some Mac user wants to work on it, I'd suggest implementing
special-case code to replace xfns.c with macfns.c on the Mac.
It isn't worth doing something super-general for this.
We need to put our time into debugging the various other problems that
have just been reported, and into checking the manual.

Re: DOC for Mac OS shown for Emacs compiled for X.

[Richard Stallman]

    Is the approach in the attached patch OK?  I generate a list with
    the objects used to build Emacs and in Snarf-documentation I
    compare the files in DOC with that list.  If not in that list,
    those sections in DOC are skipped.

On further thought, I believe this is not correct.  The DOC file
should be independent of the platform, as someone else pointed out.

So the right fix is to include xfns.c and not include macfns.c.
Or else, in macfns.c, eliminate the doc strings for functions
that are documented in xfns.c, so that the only doc strings found
for those functions will the ones in xfns.c.

Sorry I led you to do some work that is a false start.

Re: DOC for Mac OS shown for Emacs compiled for X.

[Jan D.]

>     Is the approach in the attached patch OK?  I generate a list with
>     the objects used to build Emacs and in Snarf-documentation I
>     compare the files in DOC with that list.  If not in that list,
>     those sections in DOC are skipped.
>
> On further thought, I believe this is not correct.  The DOC file
> should be independent of the platform, as someone else pointed out.

Then we need to include symbols from all w32 files also.  But the patch 
doesn't make the DOC file dependent on platform, it just makes the 
Emacs binary selective of what it reads from it.

	Jan D.

Re: DOC for Mac OS shown for Emacs compiled for X.

[Richard Stallman]

    Then we need to include symbols from all w32 files also.

To make it fully platform-independent, that is necessary.

							      But the patch 
    doesn't make the DOC file dependent on platform, it just makes the 
    Emacs binary selective of what it reads from it.

I did not realize that.  In that case, I take back what I said.
However, what does the patch do?  There is nothing in the DOC file
that says what file each doc string was read from.

Re: DOC for Mac OS shown for Emacs compiled for X.

[Jan D.]

[-- Attachment #1: Type: text/plain, Size: 1661 bytes --]

Richard Stallman wrote:
>     Then we need to include symbols from all w32 files also.
> 
> To make it fully platform-independent, that is necessary.
> 
> 							      But the patch 
>     doesn't make the DOC file dependent on platform, it just makes the 
>     Emacs binary selective of what it reads from it.
> 
> I did not realize that.  In that case, I take back what I said.
> However, what does the patch do?  There is nothing in the DOC file
> that says what file each doc string was read from.

The ^_S markers in the DOC file shows the file from where the following 
doc-strings came from.  They where introduced on April 7, (revision 1.57 of 
lib-src/make-docfile.c), presumably to support the link when a 
function/variable is "defined in C source file".

The patch has been somewhat updated since I posted it last, so I add it again. 
  Here what it does:

1. When temacs is linked, output the object file names used to link it to 
buildobj.lst.
2. A new variable Vbuild_files is declared in doc.c, initialize to nil.
3. When temacs is run, Snarf_documentation checks if Vbuild_files is nil, and 
if it is, reads buildobj.lst and inserts the file names into Vbuild_files as a 
list.
4. When looking for pointers to doc strings, Snarf_documentation skips strings 
that belongs to a file not in Vbuild_list.
5. The function in help-fns.el that finds C files also skips files not in 
build-files.

The patch still does not work on W32/msdos, because from what I understand the 
file names in DOC for those platforms are the .c files, not the .o files.  Plus 
the fact that the buildobj.lst file would contain .obj extensions instead of .o.

	Jan D.



[-- Attachment #2: doc-diff --]
[-- Type: text/plain, Size: 5671 bytes --]

diff -c src/Makefile.in.~1.303.~ src/Makefile.in
Index: src/Makefile.in
*** src/Makefile.in.~1.303.~	2004-10-20 17:44:02.000000000 +0200
--- src/Makefile.in	2004-10-30 19:46:52.000000000 +0200
***************
*** 943,949 ****
  #define MAKE_PARALLEL
  #endif
  
! temacs${EXEEXT}: MAKE_PARALLEL $(LOCALCPP) $(STARTFILES) stamp-oldxmenu ${obj} ${otherobj} OBJECTS_MACHINE prefix-args${EXEEXT}
  	$(LD) YMF_PASS_LDFLAGS (${STARTFLAGS} ${TEMACS_LDFLAGS}) $(LDFLAGS) \
      -o temacs ${STARTFILES} ${obj} ${otherobj}  \
      OBJECTS_MACHINE ${LIBES}
--- 943,950 ----
  #define MAKE_PARALLEL
  #endif
  
! temacs${EXEEXT}: MAKE_PARALLEL $(LOCALCPP) $(STARTFILES) stamp-oldxmenu ${obj} ${otherobj} OBJECTS_MACHINE prefix-args${EXEEXT} buildobj.lst
! 	echo "${obj} ${otherobj} " OBJECTS_MACHINE > buildobj.lst
  	$(LD) YMF_PASS_LDFLAGS (${STARTFLAGS} ${TEMACS_LDFLAGS}) $(LDFLAGS) \
      -o temacs ${STARTFILES} ${obj} ${otherobj}  \
      OBJECTS_MACHINE ${LIBES}
***************
*** 1272,1277 ****
--- 1273,1279 ----
  	rm -f temacs${EXEEXT} prefix-args${EXEEXT} core *.core \#* *.o libXMenu11.a liblw.a
  	rm -f ../etc/DOC
  	rm -f bootstrap-emacs${EXEEXT}
+ 	rm -f buildobj.lst
  clean: mostlyclean
  	rm -f emacs-*${EXEEXT} emacs${EXEEXT}
  /**/# This is used in making a distribution.
diff -c src/doc.c.~1.108.~ src/doc.c
Index: src/doc.c
*** src/doc.c.~1.108.~	2004-10-28 22:22:33.000000000 +0200
--- src/doc.c	2004-10-30 19:25:02.000000000 +0200
***************
*** 51,56 ****
--- 51,59 ----
  
  Lisp_Object Qfunction_documentation;
  
+ /* A list of files used to build this Emacs binary.  */
+ static Lisp_Object Vbuild_files;
+ 
  extern Lisp_Object Voverriding_local_map;
  
  /* For VMS versions with limited file name syntax,
***************
*** 581,586 ****
--- 584,590 ----
    register char *p, *end;
    Lisp_Object sym;
    char *name;
+   int skip_file = 0;
  
    CHECK_STRING (filename);
  
***************
*** 617,622 ****
--- 621,657 ----
    strcpy (name, sys_translate_unix (name));
  #endif /* VMS4_4 */
  #endif /* VMS */
+   
+   if (NILP (Vbuild_files))
+   {
+     size_t cp_size = 0;
+     size_t to_read;
+     int nr_read;
+     char *cp = NULL;
+ 
+     fd = emacs_open ("buildobj.lst", O_RDONLY, 0);
+     if (fd < 0)
+       report_file_error ("Opening file buildobj.lst", Qnil);
+ 
+     filled = 0;
+     for (;;)
+       {
+         cp_size += 1024;
+         to_read = cp_size - 1 - filled;
+         cp = xrealloc (cp, cp_size);
+         nr_read = emacs_read (fd, &cp[filled], to_read);
+         filled += nr_read;
+         if (nr_read < to_read)
+           break;
+       }
+ 
+     cp[filled] = 0;
+ 
+     Vbuild_files = Feval (Fcons (intern ("split-string"),
+                                  Fcons (build_string (cp), Qnil)));
+     emacs_close (fd);
+     xfree (cp);
+   }
  
    fd = emacs_open (name, O_RDONLY, 0);
    if (fd < 0)
***************
*** 640,649 ****
        if (p != end)
  	{
  	  end = (char *) index (p, '\n');
  	  sym = oblookup (Vobarray, p + 2,
  			  multibyte_chars_in_text (p + 2, end - p - 2),
  			  end - p - 2);
! 	  if (SYMBOLP (sym))
  	    {
  	      /* Attach a docstring to a variable?  */
  	      if (p[1] == 'V')
--- 675,699 ----
        if (p != end)
  	{
  	  end = (char *) index (p, '\n');
+ 
+           /* See if this is a file name, and if it is a file in build-files.  */
+           if (p[1] == 'S' && end - p > 4 && end[-2] == '.' && end[-1] == 'o')
+             {
+               int len = end - p - 2;
+               char *fromfile = alloca (len + 1);
+               strncpy (fromfile, &p[2], len);
+               fromfile[len] = 0;
+ 
+               if (EQ (Fmember (build_string (fromfile), Vbuild_files), Qnil))
+                 skip_file = 1;
+               else
+                 skip_file = 0;
+             }
+ 
  	  sym = oblookup (Vobarray, p + 2,
  			  multibyte_chars_in_text (p + 2, end - p - 2),
  			  end - p - 2);
! 	  if (! skip_file && SYMBOLP (sym))
  	    {
  	      /* Attach a docstring to a variable?  */
  	      if (p[1] == 'V')
***************
*** 919,924 ****
--- 969,978 ----
  	       doc: /* Name of file containing documentation strings of built-in symbols.  */);
    Vdoc_file_name = Qnil;
  
+   DEFVAR_LISP ("build-files", &Vbuild_files,
+                doc: /* A list of files used to build this Emacs binary.  */);
+   Vbuild_files = Qnil;
+ 
    defsubr (&Sdocumentation);
    defsubr (&Sdocumentation_property);
    defsubr (&Ssnarf_documentation);
diff -c lisp/help-fns.el.~1.57.~ lisp/help-fns.el
Index: lisp/help-fns.el
*** lisp/help-fns.el.~1.57.~	2004-11-01 09:25:38.000000000 +0100
--- lisp/help-fns.el	2004-11-01 09:21:49.000000000 +0100
***************
*** 228,236 ****
        (if (eobp)
  	  (insert-file-contents-literally
  	   (expand-file-name internal-doc-file-name doc-directory)))
!       (search-forward (concat "\x1f" name "\n"))
!       (re-search-backward "\x1fS\\(.*\\)")
!       (let ((file (match-string 1)))
  	(if (string-match "\\.\\(o\\|obj\\)\\'" file)
  	    (setq file (replace-match ".c" t t file)))
  	(if (string-match "\\.c\\'" file)
--- 228,241 ----
        (if (eobp)
  	  (insert-file-contents-literally
  	   (expand-file-name internal-doc-file-name doc-directory)))
!       (let ((file (catch 'loop
! 		    (while t
! 		      (let ((pnt (search-forward (concat "\x1f" name "\n"))))
! 			(re-search-backward "\x1fS\\(.*\\)")
! 			(let ((file (match-string 1)))
! 			  (if (member file build-files)
! 			      (throw 'loop file)
! 			    (goto-char pnt))))))))
  	(if (string-match "\\.\\(o\\|obj\\)\\'" file)
  	    (setq file (replace-match ".c" t t file)))
  	(if (string-match "\\.c\\'" file)

[-- Attachment #3: Type: text/plain, Size: 142 bytes --]

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

Re: DOC for Mac OS shown for Emacs compiled for X.

[Richard Stallman]

    The patch has been somewhat updated since I posted it last, so I add it again. 
      Here what it does:

Ok, it sounds good.

    The patch still does not work on W32/msdos, because from what I
    understand the file names in DOC for those platforms are the .c
    files, not the .o files.  Plus the fact that the buildobj.lst file
    would contain .obj extensions instead of .o.

Those sound like easy things for a Windows expert to fix/adapt.

Re: DOC for Mac OS shown for Emacs compiled for X.

[Richard Stallman]

    1.  make-docfile should not read the .c file if the .o one does not exist.
    2.  Emacs is supposed to find the correct entry in DOC.
    3.  macfns.o should not be in SOME_MACHINE_OBJECTS when building for X.
    4.  Symbols that occur in several files (x, mac, w32) should have the same doc
	 string.

If we make sure macfns.c has only functions and variables that appear
also in xfns.c, then we can always omit macfns.o from
SOME_MACHINE_OBJECTS.  The doc strings that are really used would come
from xfns.c, regardless of the platform.  We could replace the doc
strings in macfns.c with "This is a dummy--see xfns.c", so people
won't waste time editing them.

#1 is also a possible solution.  It is more general, since it could
handle other problems too.  Maybe we should choose that.