ifinfo vs ifnottex

ifinfo vs ifnottex

[Luc Teirlinck]

The Emacs manual contains several pieces of one type of text inside
@ifinfo and another inside @iftex.  As a result, text is missing in
all other types of output, except plaintext, which is covered by
@ifinfo.  This concerns, for instance html output.  Is there any
objection against changing these @ifinfo's to @ifnottex.  I will be
careful not to change legitimate @ifinfo's, like references to
info.texi or text saying that you are using the Info documentation
system or such.

The Elisp manual seems free of this except for gpl.texi.  Since this
has legal implications, I explicitly provide the proposed changes.  Is
there any reason for these titles not to occur in html and other
non-tex, non-info, non-plaintext formats?  The exactly same titles
also occur inside @ifinfo in man/emacs.texi.

===File ~/gpl.texi-diff=====================================
*** gpl.texi	04 Jul 2005 19:56:08 -0500	1.6
--- gpl.texi	07 May 2006 16:34:27 -0500	
***************
*** 67,75 ****
  @iftex
  @unnumberedsec Terms and Conditions for Copying, Distribution and Modification
  @end iftex
! @ifinfo
  @center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
! @end ifinfo
  
  @enumerate 0
  @item
--- 67,75 ----
  @iftex
  @unnumberedsec Terms and Conditions for Copying, Distribution and Modification
  @end iftex
! @ifnottex
  @center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
! @end ifnottex
  
  @enumerate 0
  @item
***************
*** 292,300 ****
  @iftex
  @heading NO WARRANTY
  @end iftex
! @ifinfo
  @center NO WARRANTY
! @end ifinfo
  
  @item
  BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
--- 292,300 ----
  @iftex
  @heading NO WARRANTY
  @end iftex
! @ifnottex
  @center NO WARRANTY
! @end ifnottex
  
  @item
  BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
***************
*** 322,330 ****
  @iftex
  @heading END OF TERMS AND CONDITIONS
  @end iftex
! @ifinfo
  @center END OF TERMS AND CONDITIONS
! @end ifinfo
  
  @page
  @unnumberedsec How to Apply These Terms to Your New Programs
--- 322,330 ----
  @iftex
  @heading END OF TERMS AND CONDITIONS
  @end iftex
! @ifnottex
  @center END OF TERMS AND CONDITIONS
! @end ifnottex
  
  @page
  @unnumberedsec How to Apply These Terms to Your New Programs
============================================================

Re: ifinfo vs ifnottex

[Eli Zaretskii]

> Date: Wed, 17 May 2006 21:53:47 -0500 (CDT)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> 
> The Emacs manual contains several pieces of one type of text inside
> @ifinfo and another inside @iftex.  As a result, text is missing in
> all other types of output, except plaintext, which is covered by
> @ifinfo.  This concerns, for instance html output.  Is there any
> objection against changing these @ifinfo's to @ifnottex.  I will be
> careful not to change legitimate @ifinfo's, like references to
> info.texi or text saying that you are using the Info documentation
> system or such.

Please post the suggested changes here _before_ installing them.  I'm
not sure such a replacement should be automatic; I need to see the
surrounding context to say for sure.

(And please remember that @ifnottex affects everything except TeX,
i.e. XML and DocBook output as well.)

Re: ifinfo vs ifnottex

[Luc Teirlinck]

Eli Zaretskii wrote:

   (And please remember that @ifnottex affects everything except TeX,
   i.e. XML and DocBook output as well.)

Of course, that text or those references should not be missing from
them either.

   Please post the suggested changes here _before_ installing them.  I'm
   not sure such a replacement should be automatic; I need to see the
   surrounding context to say for sure.

===File ~/trouble.texi-diff=================================
*** trouble.texi	06 May 2006 08:33:12 -0500	1.62
--- trouble.texi	06 May 2006 18:39:51 -0500	
***************
*** 890,899 ****
  trying to fix, or why your patch should be an improvement, we mustn't
  install it.
  
! @ifinfo
  @xref{Sending Patches}, for guidelines on how to make it easy for us to
  understand and install your patches.
! @end ifinfo
  
  @item
  A guess about what the bug is or what it depends on.
--- 890,899 ----
  trying to fix, or why your patch should be an improvement, we mustn't
  install it.
  
! @ifnottex
  @xref{Sending Patches}, for guidelines on how to make it easy for us to
  understand and install your patches.
! @end ifnottex
  
  @item
  A guess about what the bug is or what it depends on.
============================================================

===File ~/text.texi-diff====================================
*** text.texi	06 May 2006 11:27:06 -0500	1.66
--- text.texi	06 May 2006 18:39:52 -0500	
***************
*** 39,47 ****
  @iftex
  mode (@pxref{TeX Mode}).
  @end iftex
! @ifinfo
  mode.
! @end ifinfo
  For input to groff or nroff, use Nroff mode.
  
    Instead of using a text formatter, you can edit formatted text in
--- 39,47 ----
  @iftex
  mode (@pxref{TeX Mode}).
  @end iftex
! @ifnottex
  mode.
! @end ifnottex
  For input to groff or nroff, use Nroff mode.
  
    Instead of using a text formatter, you can edit formatted text in
***************
*** 473,481 ****
  cannot merge lines.  So editing in the middle of a paragraph can result in
  a paragraph that is not correctly filled.  The easiest way to make the
  paragraph properly filled again is usually with the explicit fill commands.
! @ifinfo
  @xref{Fill Commands}.
! @end ifinfo
  
    Many users like Auto Fill mode and want to use it in all text files.
  The section on init files says how to arrange this permanently for yourself.
--- 473,481 ----
  cannot merge lines.  So editing in the middle of a paragraph can result in
  a paragraph that is not correctly filled.  The easiest way to make the
  paragraph properly filled again is usually with the explicit fill commands.
! @ifnottex
  @xref{Fill Commands}.
! @end ifnottex
  
    Many users like Auto Fill mode and want to use it in all text files.
  The section on init files says how to arrange this permanently for yourself.
***************
*** 934,940 ****
  @code{text-mode-hook} can look at the value of @code{major-mode} to see
  which of these modes is actually being entered.  @xref{Hooks}.
  
! @ifinfo
    Emacs provides two other modes for editing text that is to be passed
  through a text formatter to produce fancy formatted printed output.
  @xref{Nroff Mode}, for editing input to the formatter nroff.
--- 934,940 ----
  @code{text-mode-hook} can look at the value of @code{major-mode} to see
  which of these modes is actually being entered.  @xref{Hooks}.
  
! @ifnottex
    Emacs provides two other modes for editing text that is to be passed
  through a text formatter to produce fancy formatted printed output.
  @xref{Nroff Mode}, for editing input to the formatter nroff.
***************
*** 945,951 ****
  headings alone or both headings and text; you can also hide some of the
  headings at lower levels from view to make the high level structure more
  visible.  @xref{Outline Mode}.
! @end ifinfo
  
  @node Outline Mode
  @section Outline Mode
--- 945,951 ----
  headings alone or both headings and text; you can also hide some of the
  headings at lower levels from view to make the high level structure more
  visible.  @xref{Outline Mode}.
! @end ifnottex
  
  @node Outline Mode
  @section Outline Mode
============================================================

===File ~/search.texi-diff==================================
*** search.texi	12 Apr 2006 16:57:15 -0500	1.76
--- search.texi	06 May 2006 18:39:52 -0500	
***************
*** 372,380 ****
  useless.)  But it does not call @code{search-forward} right away.  First
  it checks the next input character to see if is @kbd{C-w},
  which specifies a word search.
! @ifinfo
  @xref{Word Search}.
! @end ifinfo
  @kbd{C-r @key{RET}} does likewise, for a reverse incremental search.
  
  @findex search-forward
--- 372,380 ----
  useless.)  But it does not call @code{search-forward} right away.  First
  it checks the next input character to see if is @kbd{C-w},
  which specifies a word search.
! @ifnottex
  @xref{Word Search}.
! @end ifnottex
  @kbd{C-r @key{RET}} does likewise, for a reverse incremental search.
  
  @findex search-forward
============================================================

===File ~/rmail.texi-diff===================================
*** rmail.texi	07 Feb 2006 18:27:55 -0600	1.32
--- rmail.texi	06 May 2006 18:39:52 -0500	
***************
*** 550,558 ****
  message.  A few label names have standard meanings and are given to
  messages automatically by Rmail when appropriate; these special labels
  are called @dfn{attributes}.
! @ifinfo
  (@xref{Rmail Attributes}.)
! @end ifinfo
  All other labels are assigned only by users.
  
  @table @kbd
--- 550,558 ----
  message.  A few label names have standard meanings and are given to
  messages automatically by Rmail when appropriate; these special labels
  are called @dfn{attributes}.
! @ifnottex
  (@xref{Rmail Attributes}.)
! @end ifnottex
  All other labels are assigned only by users.
  
  @table @kbd
============================================================

===File ~/mule.texi-diff====================================
Index: mule.texi
===================================================================
RCS file: /sources/emacs/emacs/man/mule.texi,v
retrieving revision 1.91
diff -c -r1.91 mule.texi
*** mule.texi	12 May 2006 17:41:17 -0000	1.91
--- mule.texi	18 May 2006 03:57:33 -0000
***************
*** 429,437 ****
    Another method, more general but not quite as easy to type, is to use
  @kbd{C-\ C-\} between two characters to stop them from combining.  This
  is the command @kbd{C-\} (@code{toggle-input-method}) used twice.
! @ifinfo
  @xref{Select Input Method}.
! @end ifinfo
  
  @cindex incremental search, input method interference
    @kbd{C-\ C-\} is especially useful inside an incremental search,
--- 429,437 ----
    Another method, more general but not quite as easy to type, is to use
  @kbd{C-\ C-\} between two characters to stop them from combining.  This
  is the command @kbd{C-\} (@code{toggle-input-method}) used twice.
! @ifnottex
  @xref{Select Input Method}.
! @end ifnottex
  
  @cindex incremental search, input method interference
    @kbd{C-\ C-\} is especially useful inside an incremental search,
***************
*** 563,571 ****
  @iftex
  (see above).
  @end iftex
! @ifinfo
  (@pxref{Language Environments}).
! @end ifinfo
  If you do not specify a choice, the default is Latin-1.
  
    If you insert a character in the range 0200 through 0237, which
--- 563,571 ----
  @iftex
  (see above).
  @end iftex
! @ifnottex
  (@pxref{Language Environments}).
! @end ifnottex
  If you do not specify a choice, the default is Latin-1.
  
    If you insert a character in the range 0200 through 0237, which
============================================================

===File ~/misc.texi-diff====================================
Index: misc.texi
===================================================================
RCS file: /sources/emacs/emacs/man/misc.texi,v
retrieving revision 1.84
diff -c -r1.84 misc.texi
*** misc.texi	6 May 2006 20:27:14 -0000	1.84
--- misc.texi	18 May 2006 03:56:36 -0000
***************
*** 30,38 ****
  number of other sources---mail, remote directories, digests, and so on.
  
  Here we introduce Gnus and describe several basic features.
! @ifinfo
  For full details, see @ref{Top, Gnus,, gnus, The Gnus Manual}.
! @end ifinfo
  @iftex
  For full details on Gnus, type @kbd{M-x info} and then select the Gnus
  manual.
--- 30,38 ----
  number of other sources---mail, remote directories, digests, and so on.
  
  Here we introduce Gnus and describe several basic features.
! @ifnottex
  For full details, see @ref{Top, Gnus,, gnus, The Gnus Manual}.
! @end ifnottex
  @iftex
  For full details on Gnus, type @kbd{M-x info} and then select the Gnus
  manual.
***************
*** 1503,1511 ****
  can be customized in group @code{handwrite}.  This function only
  supports ISO 8859-1 characters.
  
! @ifinfo
    The following section describes variables for customizing these commands.
! @end ifinfo
  
  @node PostScript Variables, Printing Package, PostScript, Printing
  @section Variables for PostScript Hardcopy
--- 1503,1511 ----
  can be customized in group @code{handwrite}.  This function only
  supports ISO 8859-1 characters.
  
! @ifnottex
    The following section describes variables for customizing these commands.
! @end ifnottex
  
  @node PostScript Variables, Printing Package, PostScript, Printing
  @section Variables for PostScript Hardcopy
============================================================

===File ~/maintaining.texi-diff=============================
*** maintaining.texi	06 May 2006 08:33:10 -0500	1.44
--- maintaining.texi	06 May 2006 18:39:54 -0500	
***************
*** 355,363 ****
  @iftex
  the previous section.
  @end iftex
! @ifinfo
  @ref{Tag Syntax}.
! @end ifinfo
  Here is how to run @code{etags}:
  
  @example
--- 355,363 ----
  @iftex
  the previous section.
  @end iftex
! @ifnottex
  @ref{Tag Syntax}.
! @end ifnottex
  Here is how to run @code{etags}:
  
  @example
============================================================

===File ~/indent.texi-diff==================================
*** indent.texi	05 Feb 2006 16:45:32 -0600	1.19
--- indent.texi	06 May 2006 18:39:54 -0500	
***************
*** 154,162 ****
  An indentation point is the end of a sequence of whitespace or the end of
  the line.  If point is farther right than any indentation point in the
  previous line, @code{indent-relative} runs @code{tab-to-tab-stop}
! @ifinfo
  (@pxref{Tab Stops}),
! @end ifinfo
  @iftex
  (see next section),
  @end iftex
--- 154,162 ----
  An indentation point is the end of a sequence of whitespace or the end of
  the line.  If point is farther right than any indentation point in the
  previous line, @code{indent-relative} runs @code{tab-to-tab-stop}
! @ifnottex
  (@pxref{Tab Stops}),
! @end ifnottex
  @iftex
  (see next section),
  @end iftex
============================================================

===File ~/fixit.texi-diff===================================
*** fixit.texi	05 Feb 2006 16:45:32 -0600	1.25
--- fixit.texi	06 May 2006 18:39:55 -0500	
***************
*** 267,275 ****
    This section describes the commands to check the spelling of a single
  word or of a portion of a buffer.  These commands work with the spelling
  checker programs Aspell and Ispell, which are not part of Emacs.
! @ifinfo
  @xref{Top, Aspell,, aspell, The Aspell Manual}.
! @end ifinfo
  
  @table @kbd
  @item M-x flyspell-mode
--- 267,275 ----
    This section describes the commands to check the spelling of a single
  word or of a portion of a buffer.  These commands work with the spelling
  checker programs Aspell and Ispell, which are not part of Emacs.
! @ifnottex
  @xref{Top, Aspell,, aspell, The Aspell Manual}.
! @end ifnottex
  
  @table @kbd
  @item M-x flyspell-mode
============================================================

===File ~/emacs.texi-diff===================================
*** emacs.texi	06 May 2006 08:33:06 -0500	1.133
--- emacs.texi	06 May 2006 18:24:02 -0500	
***************
*** 1227,1235 ****
  @iftex
  @unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
  @end iftex
! @ifinfo
  @center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
! @end ifinfo
  
  @enumerate 0
  @item
--- 1227,1235 ----
  @iftex
  @unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
  @end iftex
! @ifnottex
  @center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
! @end ifnottex
  
  @enumerate 0
  @item
***************
*** 1452,1460 ****
  @iftex
  @heading NO WARRANTY
  @end iftex
! @ifinfo
  @center NO WARRANTY
! @end ifinfo
  
  @item
  BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
--- 1452,1460 ----
  @iftex
  @heading NO WARRANTY
  @end iftex
! @ifnottex
  @center NO WARRANTY
! @end ifnottex
  
  @item
  BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
***************
*** 1482,1490 ****
  @iftex
  @heading END OF TERMS AND CONDITIONS
  @end iftex
! @ifinfo
  @center END OF TERMS AND CONDITIONS
! @end ifinfo
  
  @page
  @unnumberedsec How to Apply These Terms to Your New Programs
--- 1482,1490 ----
  @iftex
  @heading END OF TERMS AND CONDITIONS
  @end iftex
! @ifnottex
  @center END OF TERMS AND CONDITIONS
! @end ifnottex
  
  @page
  @unnumberedsec How to Apply These Terms to Your New Programs
============================================================

===File ~/custom.texi-diff==================================
Index: custom.texi
===================================================================
RCS file: /sources/emacs/emacs/man/custom.texi,v
retrieving revision 1.117
diff -c -r1.117 custom.texi
*** custom.texi	8 May 2006 05:16:29 -0000	1.117
--- custom.texi	18 May 2006 03:53:34 -0000
***************
*** 2111,2120 ****
  
    If you are going to write actual Emacs Lisp programs that go beyond
  minor customization, you should read the @cite{Emacs Lisp Reference Manual}.
! @ifinfo
  @xref{Top, Emacs Lisp, Emacs Lisp, elisp, the Emacs Lisp Reference
  Manual}.
! @end ifinfo
  
  @menu
  * Init Syntax::	        Syntax of constants in Emacs Lisp.
--- 2111,2120 ----
  
    If you are going to write actual Emacs Lisp programs that go beyond
  minor customization, you should read the @cite{Emacs Lisp Reference Manual}.
! @ifnottex
  @xref{Top, Emacs Lisp, Emacs Lisp, elisp, the Emacs Lisp Reference
  Manual}.
! @end ifnottex
  
  @menu
  * Init Syntax::	        Syntax of constants in Emacs Lisp.
============================================================

Re: ifinfo vs ifnottex

[Eli Zaretskii]

> Date: Wed, 17 May 2006 23:15:20 -0500 (CDT)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> CC: emacs-devel@gnu.org
> 
> Eli Zaretskii wrote:
> 
>    (And please remember that @ifnottex affects everything except TeX,
>    i.e. XML and DocBook output as well.)
> 
> Of course, that text or those references should not be missing from
> them either.

I'm not sure: DocBook is a format for printed books, so perhaps it
should be treated as TeX.  Karl, could you please advise?

Re: ifinfo vs ifnottex

[Karl Berry]

    I'm not sure: DocBook is a format for printed books, so perhaps it
    should be treated as TeX.  Karl, could you please advise?

What's the question?

Re: ifinfo vs ifnottex

[Luc Teirlinck]

This concerns some @ifinfo-> @ifnottex changes I proposed.  Richard
has already asked me to install these changes, but I will wait till
this remaining issue is resolved.

I have the impression that my changes are clearly the right thing for
info and HTML and, as one should be able to use XML to read and
display .info files, most of what is right for info should be right
for XML as well.  _If_ one should also be able to use docbook to read
.info files, then I believe that this pretty much settles the issue,
by the same argument as for XML.

I have the impression that after my changes, the docbook output will
be in acceptable form.  If this is good enough, then this settles the
issue, as treating docbook separately will make things more complex.
If we want the docbook output to look as perfect as possible, assuming
that it should look more like Tex than like any of the other outputs,
then not only my changes, but all other occurrences of @tex vs
@ifnottex in the Emacs and Elisp manual might have to be reconsidered.
(That is a _lot_ more occurrences than just my proposed changes and
hence quite some work.)  If we want the plain text output to look as
close as possible to perfect too, rather than just acceptable, even
more complexity and changes are needed.

There are essentially five types of situations in my patches where
this question arises, all listed below, *but* there are _many_
additional types of situations, some more complex, in other places.

1.  The "@unnumberedsec" and "@heading" vs "@center" issue in the GPL
   doc.  (See my patches to gpl.texi.)  Richard has already asked me to
   install this, but I will wait to allow for counterarguments concerning
   docbook.  The current @iftex vs @ifinfo is clearly wrong as _nothing_
   gets output in any other format except plain text.

2.  One single instance where my changes might not be really the best
    thing for plain text (but does that matter a lot?) and maybe not
    for docbook:

  If you are going to write actual Emacs Lisp programs that go beyond
minor customization, you should read the @cite{Emacs Lisp Reference Manual}.
@ifinfo
@xref{Top, Emacs Lisp, Emacs Lisp, elisp, the Emacs Lisp Reference
Manual}.
@end ifinfo

3.  Situations like:

@ifinfo
(@pxref{Tab Stops}),
@end ifinfo
@iftex
(see next section),
@end iftex

Again, we could try to be more perfect here for plain text and maybe
docbook by making them go with Tex.  Worth the trouble?

4. Situations like:

  This section describes the commands to check the spelling of a single
word or of a portion of a buffer.  These commands work with the spelling
checker programs Aspell and Ispell, which are not part of Emacs.
@ifinfo
@xref{Top, Aspell,, aspell, The Aspell Manual}.
@end ifinfo

I guess the @ifinfo is there to save place in the _published_ Emacs
manual.  The reference is appropriate for plain text and docbook.

5.  Situations like:

@iftex
mode (@pxref{TeX Mode}).
@end iftex
@ifinfo
mode.
@end ifinfo

I do not understand this one and similar ones at all.  Why is there a
reference in the one situation where space is at a premium and none in
all other situations?  (This would remain true even after my changes.
But after my changes "mode." will no longer be missing in many
formats.)

Sincerely,

Luc.

Re: ifinfo vs ifnottex

[Eli Zaretskii]

> Date: Thu, 18 May 2006 22:32:48 -0500 (CDT)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> CC: eliz@gnu.org, emacs-devel@gnu.org
> 
> I have the impression that after my changes, the docbook output will
> be in acceptable form.  If this is good enough, then this settles the
> issue, as treating docbook separately will make things more complex.
> If we want the docbook output to look as perfect as possible, assuming
> that it should look more like Tex than like any of the other outputs,
> then not only my changes, but all other occurrences of @tex vs
> @ifnottex in the Emacs and Elisp manual might have to be reconsidered.
> (That is a _lot_ more occurrences than just my proposed changes and
> hence quite some work.)  If we want the plain text output to look as
> close as possible to perfect too, rather than just acceptable, even
> more complexity and changes are needed.

IMO, the complexities are not relevant.  What is relevant, IMO, is
whether we want to support any formats other than Info and DVI in the
documentation directories.  (Note that the Makefile's currently don't
support anything beyond these two formats.)  If we want to support
DocBook, then we need to do whatever it takes to do it properly.  If
we don't want to support it, we should at least add some error
directive to that effect, conditioned on @ifdocbook.

> 3.  Situations like:
> 
> @ifinfo
> (@pxref{Tab Stops}),
> @end ifinfo
> @iftex
> (see next section),
> @end iftex
> 
> Again, we could try to be more perfect here for plain text and maybe
> docbook by making them go with Tex.  Worth the trouble?

I don't see any trouble, just a few more @ifSOMETHING blocks.

> 4. Situations like:
> 
>   This section describes the commands to check the spelling of a single
> word or of a portion of a buffer.  These commands work with the spelling
> checker programs Aspell and Ispell, which are not part of Emacs.
> @ifinfo
> @xref{Top, Aspell,, aspell, The Aspell Manual}.
> @end ifinfo
> 
> I guess the @ifinfo is there to save place in the _published_ Emacs
> manual.  The reference is appropriate for plain text and docbook.

I don't understand why you consistently speak about DocBook as if it
were an on-line format.  It isn't, AFAIK; it is a format used to write
technical documentation that is intended to be published as a book.
AFAIK, many publishing houses use this format.  For example, the Gawk
documentation, maintained in Texinfo, was published by O'Reilly by
generating the DocBook format using makeinfo, then the result was
edited by hand to add typographic sugar not supported by Texinfo, and
finally, printed as a beautifully typeset book.

> 5.  Situations like:
> 
> @iftex
> mode (@pxref{TeX Mode}).
> @end iftex
> @ifinfo
> mode.
> @end ifinfo
> 
> I do not understand this one and similar ones at all.

I don't understand this, either; looks like a bug.  FWIW, it was in
the CVS since day one.

Re: ifinfo vs ifnottex

[Luc Teirlinck]

Eli Zaretskii wrote:

   What is relevant, IMO, is whether we want to support any formats
   other than Info and DVI in the documentation directories.  (Note
   that the Makefile's currently don't support anything beyond these
   two formats.)

The basic problem is solved now and I installed my changes.  But I do
not immediately understand the above quote.  The Makefiles
automatically build .info files from the .texi files and install them.
I do _not_ consider the changes I just made to be a prelude for the
Makefiles to automatically build and install .html files.  What I was
worrying about was a user running `makeinfo --html' himself, maybe a
sysadmin who wants to provide links to manuals from a webpage.  I do
not believe that any support from the Makefiles is necessary for that.

Sincerely,

Luc.

Re: ifinfo vs ifnottex

[Luc Teirlinck]

Eli Zaretskii wrote:

   (Note that the Makefile's currently don't support anything beyond
   these two formats.)

I now believe that you meant allowing users to build the HTML manuals
using something like `make elisp.html' in analogy with `make elisp.dvi'.
Since running makeinfo directly is not that difficult, I do not
believe that the lack of support from the Makefiles is a major
impediment for generating other output formats.

Sincerely,

Luc.

Re: ifinfo vs ifnottex

[Eli Zaretskii]

> Date: Fri, 19 May 2006 21:40:28 -0500 (CDT)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> CC: emacs-devel@gnu.org, karl@freefriends.org
> 
> Eli Zaretskii wrote:
> 
>    (Note that the Makefile's currently don't support anything beyond
>    these two formats.)
> 
> I now believe that you meant allowing users to build the HTML manuals
> using something like `make elisp.html' in analogy with `make elisp.dvi'.

Yes.  Or, better, just "make HTML" to produce HTML versions of _all_
the manuals.  And similarly for XML, DocBook, and PDF.

> Since running makeinfo directly is not that difficult, I do not
> believe that the lack of support from the Makefiles is a major
> impediment for generating other output formats.

For someone who has good knowledge of makeinfo, it's not an
impediment.  For others, it is.

Similarly, for someone who knows how to run GCC, it won't be a
problem to compile Emacs by hand, but we still supply special Makefile
targets for that.

Quite a few of other GNU packages have such special targets in their
doc directories, so the idea occurred to others as well.

Re: ifinfo vs ifnottex

[Karl Berry]

    Yes.  Or, better, just "make HTML" to produce HTML versions of _all_
    the manuals.  And similarly for XML, DocBook, and PDF.

We added html/ps/pdf targets in standards.texi a while ago.  They'll be
supported in the next version of Automake.  It would be good to add
those to the Emacs Makefiles.

The consensus was not to add (Texinfo)XML and DocBook targets, since
they are far less widely used.  Among other reasons, which are vague in
my memory at this point.

If you feel like adding targets for them too, though, I see no harm in
it -- personally, it's not something I would see as a high priority.

Re: ifinfo vs ifnottex

[Eli Zaretskii]

> Date: Sat, 20 May 2006 12:55:00 -0500
> From: karl@freefriends.org (Karl Berry)
> Cc: teirllm@dms.auburn.edu, emacs-devel@gnu.org
> 
> If you feel like adding targets for them too, though, I see no harm in
> it -- personally, it's not something I would see as a high priority.

It's up to Richard.  Personally, I don't think we should bother before
the release of v22.1.

Thanks for the input.

Re: ifinfo vs ifnottex

[Richard Stallman]

    It's up to Richard.  Personally, I don't think we should bother before
    the release of v22.1.

Since this is now a GNU standard, I think they should be added now.
It is easy and safe to add them.

Re: ifinfo vs ifnottex

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> CC: karl@freefriends.org, teirllm@dms.auburn.edu, emacs-devel@gnu.org
> Date: Sun, 21 May 2006 13:08:09 -0400
> 
>     It's up to Richard.  Personally, I don't think we should bother before
>     the release of v22.1.
> 
> Since this is now a GNU standard, I think they should be added now.
> It is easy and safe to add them.

How does one test the XML output?

Also, what should "make install" do to those additional output
formats? nothing at all?

Re: ifinfo vs ifnottex

[Karl Berry]

    How does one test the XML output?

My advice is, don't.

But if you feel the need to do so, you'd need some xml-parsing program,
e.g., xmllint.  There are known bugs in the 4.8 XML output, too, so any
such tests would probably fail anyway ...

    Also, what should "make install" do to those additional output
    formats? nothing at all?

I don't advise installing XML or Docbook.  As I said, those targets were
not added to the standards.  Only HTML, PDF, and PS.

If you do want to build/install XML, I highly recommend not calling the
target or the output directory plain `xml' -- it's too generic (Docbook
is also XML, among thousands of other things).  Perhaps `texinfoxml'.

Best,
Karl

Re: ifinfo vs ifnottex

[Eli Zaretskii]

> Date: Sun, 21 May 2006 16:07:26 -0500
> From: karl@freefriends.org (Karl Berry)
> Cc: rms@gnu.org, teirllm@dms.auburn.edu, emacs-devel@gnu.org
> 
>     How does one test the XML output?
> 
> My advice is, don't.

Sorry, I thought XML was on the list of the targets mentioned in the
GNU standards.  If it isn't, we shouldn't add it.

>     Also, what should "make install" do to those additional output
>     formats? nothing at all?
> 
> I don't advise installing XML or Docbook.  As I said, those targets were
> not added to the standards.  Only HTML, PDF, and PS.

Okay, so how to "install" PDF and PS?

Thanks.

Re: ifinfo vs ifnottex

[Karl Berry]

    Okay, so how to "install" PDF and PS?

pdfdir = $(docdir)
...
	$(INSTALL_DATA) foo.pdf $(pdfdir)/foo.pdf

Unless you're using CVS Autoconf, then you can use @pdfdir@, I believe.

Re: ifinfo vs ifnottex

[Karl Berry]

    Again, we could try to be more perfect here for plain text and maybe
    docbook by making them go with Tex.  Worth the trouble?

Not in my opinion.  Personally, I sometimes write "see next section"
even in Info -- after all, "n" is a perfectly natural Info operation.

Re: ifinfo vs ifnottex

[Eli Zaretskii]

> Date: Thu, 18 May 2006 15:29:30 -0500
> From: karl@freefriends.org (Karl Berry)
> Cc: teirllm@dms.auburn.edu, emacs-devel@gnu.org
> 
>     I'm not sure: DocBook is a format for printed books, so perhaps it
>     should be treated as TeX.  Karl, could you please advise?
> 
> What's the question?

Sorry, I thought that was clear.  Here's the missing info: In the
Emacs manuals there are portions conditioned on @ifinfo, and we want
to change that so that _all_ on-line formats pick up those portions.
The question is, should DocBook output be treated as Info, HTML, and
XML (in which case @ifinfo should be replaced by @ifnottex), or should
DocBook be treated as printed output similar to TeX, in which case the
conditions should be such that TeX and DocBook pick up the same text.

TIA

Re: ifinfo vs ifnottex

[Karl Berry]

    The question is, should DocBook output be treated as Info, HTML, and
    XML (in which case @ifinfo should be replaced by @ifnottex)

That seems best to me.  I don't see any good reason to do otherwise, and
trying to merge Docbook and TeX parts seems unnecessarily problematic.

Docbook is definitely used online as well as printed books.  Many free
documentation projects use it.

Of course, it's best to avoid these Texinfo conditionals entirely,
whenever possible.

karl

Re: ifinfo vs ifnottex

[Eli Zaretskii]

> Date: Fri, 19 May 2006 12:43:16 -0500
> From: karl@freefriends.org (Karl Berry)
> Cc: teirllm@dms.auburn.edu, emacs-devel@gnu.org
> 
>     The question is, should DocBook output be treated as Info, HTML, and
>     XML (in which case @ifinfo should be replaced by @ifnottex)
> 
> That seems best to me.  I don't see any good reason to do otherwise, and
> trying to merge Docbook and TeX parts seems unnecessarily problematic.

Thanks.

Luc, I withdraw my reservations.  Please go ahead and commit your
changes.

Re: ifinfo vs ifnottex

[Richard Stallman]

    Sorry, I thought that was clear.  Here's the missing info: In the
    Emacs manuals there are portions conditioned on @ifinfo, and we want
    to change that so that _all_ on-line formats pick up those portions.
    The question is, should DocBook output be treated as Info, HTML, and
    XML (in which case @ifinfo should be replaced by @ifnottex), or should
    DocBook be treated as printed output similar to TeX, in which case the
    conditions should be such that TeX and DocBook pick up the same text.

I think two separate issues are being confused here.

The problem that Luc discovered is that TeX output gets one version
of the text, Info output gets another version, and HTML gets NO version.
His change replaces @ifinfo with @ifnottex, so that HTML output gets
the same version as Info.

With his change, every output format gets one version of that text or
the other.  In particular, DocBook gets one version or the other -- instead
of NO version, as now.  That has to be an improvement.

How @iftex and @ifnottex should treat DocBook output format is a
separate question.  Whatever the answer to this question, Luc's change
is still an improvement.  We don't want the old conditionals, which
put NO version of this text into DocBook output.

Re: ifinfo vs ifnottex

[Luc Teirlinck]

To avoid confusion, I fixed the @ifinfo's in the Elisp and Emacs manuals
(including the "extra" parts).  I just come to fix similar problems
for the dired-x manual.  I did however not fix all potential problems
in the man directory.  Potential problems _may_ remain for the
ada-mode.texi calc.texi cc-mode.texi cl.texi gnus.texi idlwave.texi
mh-e.texi reftex.texi sc.texi tramp.texi vip.texi and org.texi
manuals.  (They contain @ifinfo's which I did not check for
problems.)  Of these, cl.texi seems quite simply hopeless: large parts
seem to be partly written text that is left unfinished.  I believe
that the other manuals have their own maintainers and therefore I am
more hesitant to mess around with them.

Sincerely,

Luc.

Re: ifinfo vs ifnottex

[Luc Teirlinck]

Here is a new diff for misc.texi with a few additional changes.  The
additional changes are actually irrelevant, since they are inside
@ignore.  However, we might quite as well make them, should the
@ignore ever be removed.

===File ~/misc.texi-diff-2==================================
Index: misc.texi
===================================================================
RCS file: /sources/emacs/emacs/man/misc.texi,v
retrieving revision 1.84
diff -c -r1.84 misc.texi
*** misc.texi	6 May 2006 20:27:14 -0000	1.84
--- misc.texi	18 May 2006 04:43:21 -0000
***************
*** 30,38 ****
  number of other sources---mail, remote directories, digests, and so on.
  
  Here we introduce Gnus and describe several basic features.
! @ifinfo
  For full details, see @ref{Top, Gnus,, gnus, The Gnus Manual}.
! @end ifinfo
  @iftex
  For full details on Gnus, type @kbd{M-x info} and then select the Gnus
  manual.
--- 30,38 ----
  number of other sources---mail, remote directories, digests, and so on.
  
  Here we introduce Gnus and describe several basic features.
! @ifnottex
  For full details, see @ref{Top, Gnus,, gnus, The Gnus Manual}.
! @end ifnottex
  @iftex
  For full details on Gnus, type @kbd{M-x info} and then select the Gnus
  manual.
***************
*** 238,247 ****
  
  @c Too many references to the name of the manual if done with xref in TeX!
  Gnus is powerful and customizable.  Here are references to a few
! @ifinfo
  additional topics:
  
! @end ifinfo
  @iftex
  additional topics in @cite{The Gnus Manual}:
  
--- 238,247 ----
  
  @c Too many references to the name of the manual if done with xref in TeX!
  Gnus is powerful and customizable.  Here are references to a few
! @ifnottex
  additional topics:
  
! @end ifnottex
  @iftex
  additional topics in @cite{The Gnus Manual}:
  
***************
*** 274,280 ****
  See section ``Composing Messages.''
  @end itemize
  @end iftex
! @ifinfo
  @itemize @bullet
  @item
  Follow discussions on specific topics.@*
--- 274,280 ----
  See section ``Composing Messages.''
  @end itemize
  @end iftex
! @ifnottex
  @itemize @bullet
  @item
  Follow discussions on specific topics.@*
***************
*** 304,310 ****
  Send an article to a newsgroup.@*
  @xref{Composing Messages, , , gnus, The Gnus Manual}.
  @end itemize
! @end ifinfo
  @end ignore
  
  @node Shell, Emacs Server, Gnus, Top
--- 304,310 ----
  Send an article to a newsgroup.@*
  @xref{Composing Messages, , , gnus, The Gnus Manual}.
  @end itemize
! @end ifnottex
  @end ignore
  
  @node Shell, Emacs Server, Gnus, Top
***************
*** 1503,1511 ****
  can be customized in group @code{handwrite}.  This function only
  supports ISO 8859-1 characters.
  
! @ifinfo
    The following section describes variables for customizing these commands.
! @end ifinfo
  
  @node PostScript Variables, Printing Package, PostScript, Printing
  @section Variables for PostScript Hardcopy
--- 1503,1511 ----
  can be customized in group @code{handwrite}.  This function only
  supports ISO 8859-1 characters.
  
! @ifnottex
    The following section describes variables for customizing these commands.
! @end ifnottex
  
  @node PostScript Variables, Printing Package, PostScript, Printing
  @section Variables for PostScript Hardcopy
============================================================

Re: ifinfo vs ifnottex

[Luc Teirlinck]

Eli Zaretskii wrote:

   I'm not sure such a replacement should be automatic; I need to see
   the surrounding context to say for sure

I did not make any automatic replacements.  I looked at the
surrounding context.  I left a few legitimate @ifinfo's in.

Sincerely,

Luc.

Re: ifinfo vs ifnottex

[Richard Stallman]

    The Emacs manual contains several pieces of one type of text inside
    @ifinfo and another inside @iftex.  As a result, text is missing in
    all other types of output, except plaintext, which is covered by
    @ifinfo.  This concerns, for instance html output.  Is there any
    objection against changing these @ifinfo's to @ifnottex.  I will be
    careful not to change legitimate @ifinfo's, like references to
    info.texi or text saying that you are using the Info documentation
    system or such.

Please install these changes.

    The Elisp manual seems free of this except for gpl.texi.  Since this
    has legal implications, I explicitly provide the proposed changes.

These changes are clearly the right thing to do.
We just need to get them installed in all the right places.
I will take care of that.  Would you please install them in Emacs?

Re: ifinfo vs ifnottex

[Luc Teirlinck]

Richard Stallman wrote:

       The Elisp manual seems free of this except for gpl.texi.  Since this
       has legal implications, I explicitly provide the proposed changes.

   These changes are clearly the right thing to do.
   We just need to get them installed in all the right places.
   I will take care of that.  Would you please install them in Emacs?

I will install them in the Emacs and Elisp manuals.  I will however
wait a little longer before doing it, until the last remaining issue
that Eli mentioned (docbook) is cleared up.

Sincerely,

Luc.

Re: ifinfo vs ifnottex

[Robert J. Chassell]

Luc Teirlinck <teirllm@dms.auburn.edu> is right and I am glad of his
offer.  With more output formats, seven direct, last I counted, the
Texinfo source files must change.

Texinfo source files should use `@ifxml ... @end ifxml' for conversion
to XML with a Texinfo DTD and `@ifdocbook ... @end ifdocbook' for
conversion to DocBook.

The two are different since XML with a Texinfo DTD can be converted to
either an on-line viewing format, Info or an off-line viewing format
such as DVI.  The XML with a Texinfo DTD output should enjoy `maximum'
information.  (It is really better to conceive of the XML formats as
being an `intermediate' rather than a `final output' format.)

As far as I know, you can only view DocBook pages on-line; it is not
as if they are designed for on-line viewing.

As it happens, both those output formats, XML with a Texinfo DTD and
DocBook, have the same file extension although they are different
internally.


In more detail:

Luc has offered to insert four more `@if...' commands into the deep
representations, the Texinfo source files.  At the moment, the
documentation is broken.  It includes only `@ifinfo...' and 
`@iftex...'.

`@ifinfo' handles both Info and Plain Text.  In addition there is an
`@ifplaintext' command.  There is no `@ifpdf' command.  (This lack is
explained in  (texinfo)PDF Output .  Also, there are corresponding
`@ifnot...' commands.)

    `@ifinfo ... @end ifinfo'
         Text to appear only in the Info and Plain Text output.

    `@ifplaintext ... @end ifplaintext'
         Text to appear only in the plain text output.

    `@ifhtml ... @end ifhtml'
         Text to appear only in the HTML output.

    `@iftex ... @end iftex'
         Text to appear only in the printed manual.

    `@ifdocbook ... @end ifdocbook'
         Text to appear only in the Docbook output.

    `@ifxml ... @end ifxml'
         Text to appear only in the XML output.

The output formats for both DocBook and XML with a Texinfo DTD have
the same extension: .xml   `makeinfo' chooses which to output
depending on its flag:

    makeinfo --docbook ...
    makeinfo --xml     ...



Incidently, the seven direct output formats for a single Texinfo
source file are:  Info, HTML, plain text, DVI, PDF, DocBook, and
Texinfo XML.  For example:

    ## Info
    makeinfo --no-split --fill-column=70 --paragraph-indent=0 --verbose \
    foo.texi

    ## Plain text
    makeinfo --no-split --fill-column=70 --paragraph-indent=0 --verbose \
    --no-headers --output=foo.txt foo.texi

    ## HTML
    makeinfo --no-split --html foo.texi

    ## DVI
    texi2dvi foo.texi

    ## PDF
    texi2dvi --pdf foo.texi

    ## DocBook
    makeinfo --docbook --no-split --paragraph-indent=0 --verbose foo.texi

    ## XML
    makeinfo --xml --no-split --paragraph-indent=0 --verbose foo.texi

Also, you can create PostScript and RTF in two steps and LaTeX in
three steps:

    ## PostScript (needs DVI)
    dvi2ps foo.dvi > foo.ps

    ## RTF (needs HTML)
    /usr/local/src/html2rtf.pl foo.html

    ## LaTex (needs RTF)
    /usr/bin/rtf2latex foo.rtf


Even though the files extensions are similar, the headers for DocBook
and XML with a Texinfo DTD are different:

    DocBook

        <?xml version="1.0"?>
        <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
          <!ENTITY tex "TeX">
          <!ENTITY latex "LaTeX">
        ]>
        <book lang="en">


    XML with a Texinfo DTD

        <?xml version="1.0"?>
        <!DOCTYPE texinfo PUBLIC "-//GNU//DTD TexinfoML V4.8//EN" "http://www.gnu.org/software/texinfo/dtd/4.8/texinfo.dtd">
        <texinfo xml:lang="en">

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