Xref: utzoo comp.emacs:6378 comp.text:4253 gnu.emacs:1153
Newsgroups: comp.emacs,comp.text,gnu.emacs
Path: utzoo!utgpu!jarvis.csri.toronto.edu!turing.toronto.edu!erlebach
From: erlebach@turing.toronto.edu (Beverly Erlebacher)
Subject: Re: texi2roff for elisp manual
Message-ID: <1989Jun27.151431.1853@jarvis.csri.toronto.edu>
Keywords: texi2roff emacs lisp texinfo
References: <23@octel.UUCP>
Distribution: na

In article <23@octel.UUCP> mike@octel.UUCP (Michael D. Crawford) writes:
>The emacs programmer's manual has some extra macros in it.  Is there a
>new version of texi2roff to support them?  I don't think there is, so I
>attempting to add them to your table.  My additions cause some
>trouble.  Here is the input file:
>
>@example
>(progn (print 'foo) (print 'bar))
>@arrow foo
>@arrow bar
>@Arrow bar
>@end example

>@arrow and @Arrow are not yet defined.  Texi2roff's stdout:

[deleted for brevity]

>... and stderr:
>bar.tex line 4 : unrecognized Texinfo command @arrow
>bar.tex line 5 : unrecognized Texinfo command @arrow
>bar.tex line 6 : unrecognized Texinfo command @Arrow

>Now I add table entries for @arrow and @Arrow:
>"@Arrow",		"",	"=>",		"",		INPARA,
>"@arrow",		"",	"->",		"",		INPARA,  

Try the following instead:

    "@Arrow",		"\n",	"\\(rh",	"\n",		CHAR,
    "@arrow",		"\n",	"\\(->",	"\n",		CHAR,

Using the troff symbols for these special characters will make the output
look nicer on the laser printer.  These lines can be added to all the table
header files - they are macro package independent. (Be careful to  preserve
the sorted condition of the table files).

(Skip to the next ====== if you aren't interested in the innards of texi2roff.)

>Now we get stderr:
>bar.tex line 7 : probably @end for unrecognized Texinfo cmd @example

>I am not sure I understand the logic of your program, but I believe
>that when an @end-able token starts, it is supposed to see the
>argument to @end and throw it away.  Instead, it does not recognize it.

The error message is misleading.

When the program finds a token which could be a Texinfo command starting
token, it looks it up in the table and if found, it emits the command's
troff starting string and pushes the table record for the command onto a
stack. When it finds what could be a Texinfo command closing string, it 
checks the top of the stack for the closing string it is expecting, and if
it matches, it emits the troff closing string and pops the stack.

Because of the way you defined @arrow and @Arrow, the program is expecting
a null-string to indicate the end of the text associated with the @[Aa]rrow
command.  This "token" can never be found, so the program chugs along until
it runs into the @end for the currently active @example.  At this point it
knows that something is wrong, and it guesses ("probably") that it has passed
some new and unrecognised command requiring an @end terminator.  In an effort
to be helpful, it includes the text following the @end in the error message. 
The record for the @example is actually one lower on the stack at this point.

The man page describes the situation that the error message is intended for:

     Unrecognized Texinfo commands may corrupt the program's com-
     mand  stack  because  it is hard to tell how to discard them
     when their closing tokens are unknown. The program may guess
     wrong  about  which command is at fault when giving an error
     message for the closing token, but  will  generally  recover
     and  translate  the  remainder  of  the  document after such
     errors.

(Here's the ====== you may have skipped to.)

Originally, these CHAR type tokens were all of the form @token{}, e.g. @dag{},
@copyright{}, @bullet{}.  This made it easy to split them into "@token{" as
the starting string and "}" as the closing string, and they can be run through
the same code as INPARA type commands that have something inside the {} such
as @file and @dfn.  Using a "\n" as a closing string and then re-emitting it
will handle these new CHAR tokens.

>If I can get it working right I will post diff's to the net.  I should
>be able to fix the -me table as well.  I do not have the -ms macros.
>The new macros needed are:
>
>@Arrow, @arrow, @defcmd, @defconst, @defmac, @defopt, and @defun

These new @def* commands can probably be added using the same strings as
the other @def* commands like @deffn, @defspec, @defvar and the corresponding
@def*x commands.  At the time I posted texi2roff, I was not able to get 
good descriptions of the @def commands, and since they were not in any
released documents at that time, I decided to do a rough job of handling them
and wait for further clarification for later releases.  They appear to be
intermediate in character between HEADING, ITEMIZING and ITEM.  I'll likely
make another type for them.

I am actively supporting texi2roff and would appreciate people writing to me 
with their problems rather than posting diffs.  I don't read the emacs
newsgroups, and don't always read comp.text. I've changed the distribution
of this article to na from usa - unlike most Canadian sites, we *do* get
usa distribution, but you can't count on it in general!

I'm working on a new release of texi2roff and will post a request for beta
testers in a little while.  The new release will generate indices with all
macro packages and tables of contents at least for -mm and -me.  It also
supports @include files.  I've added some new commands, fixed some minor bugs
and tightened up some of the code here and there.  When it is finished, I'll
post it to comp.sources.unix and the FSF people will put it up on prep for ftp.

>Michael David Crawford			Consulting for:
>Oddball Enterprises			Octel Communications Corp
>{pyramid!vsi1,aeras,uunet}!octel!mike

----
Beverly Erlebacher				uunet!utai!utcsri!erlebach
Computer Systems Research Institute		erlebach@csri.toronto.edu
University of Toronto 	Toronto, Ontario, Canada