New files url.texi and org.texi

New files url.texi and org.texi

[Luc Teirlinck]

Is there a reason why all the standard things that need to be done to
make a new .info file show up in the user's dir have not been done for
the new files url.texi and org.texi? emacs/man/Makefile.in has been
updated, but not emacs/Makefile.in, nor emacs/man/makefile.w32-in, nor
emacs/info/dir.  I could update them all, if desired.  Since this is
routine, I do not include patches for review.

In addition to the routine stuff, some further changes in url.texi and
org.texi appear necessary.

For org.texi, replacing org.info by org in the @direntry is necessary,
because otherwise, if we try to follow the link in (dir) we get:

Info-find-file: Info file org.info does not exist

For info.texi, the file name has to be changed or the .info file does
not wind up in the correct location.

Two @xref's to emacs-mime need to be replaced with @inforef's or we
get, in the hardcopy output:

See <undefined> [(emacs-mime)Top], page <undefined>.

I can install the patches if desired.

url.texi does not appear to use @copying, but I guess that is because
of the split Copyright.  Correct?

===File ~/org.texi-diff=====================================
*** org.texi	07 Dec 2004 16:17:09 -0600	1.2
--- org.texi	07 Dec 2004 20:39:26 -0600	
***************
*** 8,14 ****
  
  @dircategory Emacs
  @direntry
! * Org Mode: (org.info).	Outline-based notes management and organizer 
  @end direntry
  
  @c Version and Contact Info
--- 8,14 ----
  
  @dircategory Emacs
  @direntry
! * Org Mode: (org).	Outline-based notes management and organizer.
  @end direntry
  
  @c Version and Contact Info
============================================================

===File ~/url.texi-diff=====================================
*** url.texi	07 Dec 2004 15:13:26 -0600	1.2
--- url.texi	07 Dec 2004 21:12:09 -0600	
***************
*** 1,5 ****
  \input texinfo
! @setfilename url.info
  @settitle URL Programmer's Manual
  
  @iftex
--- 1,5 ----
  \input texinfo
! @setfilename ../info/url
  @settitle URL Programmer's Manual
  
  @iftex
***************
*** 115,122 ****
  the @var{path} component depends on the service.
  
  The library depends on MIME support provided by the @samp{mm-}
! packages from Gnus 5.8 or later.  @xref{(emacs-mime)Top, The MIME
! library}.
  
  @menu
  * Configuration::               
--- 115,122 ----
  the @var{path} component depends on the service.
  
  The library depends on MIME support provided by the @samp{mm-}
! packages from Gnus 5.8 or later.  @inforef{Top, The MIME library,
! emacs-mime}.
  
  @menu
  * Configuration::               
***************
*** 388,395 ****
  
  HTTP URLs are retrieved into a buffer containing the HTTP headers
  followed by the body.  Since the headers are quasi-MIME, they may be
! processed using the MIME library.  @xref{(emacs-mime)Top, The MIME
! library}.  The MIME library doesn't provide a clean function to do
  that, so the URL library does.
  
  @defun url-decode-text-part handle &optional coding
--- 388,395 ----
  
  HTTP URLs are retrieved into a buffer containing the HTTP headers
  followed by the body.  Since the headers are quasi-MIME, they may be
! processed using the MIME library.  @inforef{Top, The MIME library,
! emacs-mime}.  The MIME library doesn't provide a clean function to do
  that, so the URL library does.
  
  @defun url-decode-text-part handle &optional coding
============================================================

Re: New files url.texi and org.texi

[Luc Teirlinck]

>From my previous message:

   For info.texi, the file name has to be changed or the .info file does
   not wind up in the correct location.

I meant "url.texi", not "info.texi", of course.

Sincerely,

Luc.

Re: New files url.texi and org.texi

[Richard Stallman]

    emacs/man/Makefile.in has been
    updated, but not emacs/Makefile.in, nor emacs/man/makefile.w32-in, nor
    emacs/info/dir.

For org.texi, the first and the last I just forgot, sorry.  As for the
Windows files, I never look at them--I leave them to those who want to
spend time for Windows.  I don't know what happened with url.texi, but
I'd guess it was similar.

Please install your fixes for those three files.

I installed the two patches you sent, one with some change.

Re: New files url.texi and org.texi

[Dave Love]

Luc Teirlinck <teirllm@dms.auburn.edu> writes:

> Is there a reason why all the standard things that need to be done to
> make a new .info file show up in the user's dir have not been done for
> the new files url.texi and org.texi?

I can't answer that, but the URL manual may not be in a sufficiently
useful state to get installed -- as in installed for users, rather
than in CVS.  It's a long time since I did anything with it, but if I
remember correctly, it's mostly placeholders unless someone has worked
on it since.

> Two @xref's to emacs-mime need to be replaced with @inforef's or we
> get, in the hardcopy output:
>
> See <undefined> [(emacs-mime)Top], page <undefined>.

It shouldn't be replaced, according to my reading of the Texinfo
manual; there clearly could be a printed copy of the MIME manual if
there's one for URL.  I think the xrefs just need fixing.  I probably
wrote them, and I suspect it wasn't clear how to fill in all the
fields.  I suspect there were incompatible versions of emacs-mime.texi
around at the time.

By the way, I think that the emacs-mime manual to which it refers
needs work.  If I remember correctly, it mixes up library and
user-level features, and doesn't document some of the features that
URL, for instance, needs.

Re: New files url.texi and org.texi

[Luc Teirlinck]

Dave Love wrote:

   I can't answer that, but the URL manual may not be in a sufficiently
   useful state to get installed -- as in installed for users, rather
   than in CVS.  It's a long time since I did anything with it, but if I
   remember correctly, it's mostly placeholders unless someone has worked
   on it since.

There are still plenty of placeholders and empty nodes.

   > Two @xref's to emacs-mime need to be replaced with @inforef's or we
   > get, in the hardcopy output:
   >
   > See <undefined> [(emacs-mime)Top], page <undefined>.

   It shouldn't be replaced, according to my reading of the Texinfo
   manual; there clearly could be a printed copy of the MIME manual if
   there's one for URL.  I think the xrefs just need fixing.  I probably
   wrote them, and I suspect it wasn't clear how to fill in all the
   fields.  I suspect there were incompatible versions of emacs-mime.texi
   around at the time.

Are there _published_ printed versions of the MIME and URL manuals
available?  To me, @xref would suggest that there are.  The user can
always produce hardcopy _himself_ using texi2dvi.  (Which is one of
the reasons why we care about hardcopy even if there is no published
manual.)  As I see it, @inforef means that there is no published
manual, so we refer to the info file.  If the user has access to the
.texi file, he can then decide whether he wants to print it out.

Sincerely,

Luc.

Re: New files url.texi and org.texi

[Dave Love]

Luc Teirlinck <teirllm@dms.auburn.edu> writes:

> Are there _published_ printed versions of the MIME and URL manuals
> available?  To me, @xref would suggest that there are.

I don't understand why.

> The user can always produce hardcopy _himself_ using texi2dvi.
> (Which is one of the reasons why we care about hardcopy even if
> there is no published manual.)

Of course, but I've no idea why that means you shouldn't use
@{x,px,}ref.  I'm pretty sure I confirmed with rms that external
references should use the five-arg version of the @*ref commands when
I was linking the extra manuals from the Emacs manual.

> As I see it, @inforef means that there is no published
> manual, so we refer to the info file. 

That's not what the manual says about it, and as it refers to an
Info-only file, it isn't appropriate if you're producing HTML manuals.
(I assume @inforef was intended for stuff that wasn't produced from
Texinfo source.)

Re: New files url.texi and org.texi

[Luc Teirlinck]

Dave Love wrote:

   > As I see it, @inforef means that there is no published
   > manual, so we refer to the info file. 

   That's not what the manual says about it, and as it refers to an
   Info-only file,

The Texinfo manual looks ambiguous in as far as this problem is
concerned.  I will ask the maintainers of that manual to clarify.

   it isn't appropriate if you're producing HTML manuals.

I produced HTML versions of both the URL and emacs-mime manuals.  The
particular inforef we are talking about worked perfectly.  It produces
a working hyperlink to the HTML version of the emacs-mime manual, and
does not refer to the Info manual.

Sincerely,

Luc.

Re: New files url.texi and org.texi

[Robert J. Chassell]

Dave Love <fx@gnu.org> wrote,

    Of course, but I've no idea why that means you shouldn't use
    @{x,px,}ref.  I'm pretty sure I confirmed with rms that external
    references should use the five-arg version of the @*ref commands
    when I was linking the extra manuals from the Emacs manual.

Yes, that is how you are supposed to do it.  After all, someone else,
a user perhaps, may print a hard copy.

    (I assume @inforef was intended for stuff that wasn't produced
    from Texinfo source.)

That was a major purpose in the 1980s, when Texinfo was just being
invented.  At that time, most Info files were written directly, rather
than be produced as one of the surface expressions of a Texinfo deep
representation.

Nowadays, some people try to second guess those who read their work.
They refer to what is supposed to be readily available via an
@inforef, forgetting that a reader might have a printed surface
expression at hand and prefer that.  Or that someone might want to
print and hand out a copy to tell others about Emacs ....  The Emacs
FAQ is especially egregious.

Also, as Eli Zaretskii says

    @inforef exists for those situations where you, for some reason,
    want to point to the Info manual .... ... it's possible that only
    an Info version contains some text ... that was in @ifinfo..@end
    ifinfo ....

As far as I can see, nowadays, @inforef should be devalued and people
encouraged to use @{x,px,}ref.  The Texinfo manual should be clarified
to explain its historical origins, its occasional contemporary use,
and why it does not fit a `single deep representation/multiple surface
expressions' format.

-- 
    Robert J. Chassell                         
    bob@rattlesnake.com                         GnuPG Key ID: 004B4AC8
    http://www.rattlesnake.com                  http://www.teak.cc

Re: New files url.texi and org.texi

[Dave Love]

Luc Teirlinck <teirllm@dms.auburn.edu> writes:

> The Texinfo manual looks ambiguous in as far as this problem is
> concerned.  I will ask the maintainers of that manual to clarify.

I don't see how this is ambiguous:

  `@inforef' is used for cross references to Info files for which there
  are no printed manuals.

>    it isn't appropriate if you're producing HTML manuals.
>
> I produced HTML versions of both the URL and emacs-mime manuals.  The
> particular inforef we are talking about worked perfectly.  It produces
> a working hyperlink to the HTML version of the emacs-mime manual, and
> does not refer to the Info manual.

Then it doesn't work according to the documentation above, and it's
presumably a bug.  An HTML file isn't an Info file.

Anyhow, I'm pretty sure you're arguing with what rms said about how to
make external links; it would be good to allow him to comment.