Documentation of AC_PROG_LEX -- incomprehensible!

[Norman Gray]

Greetings,

The autoconf manual includes the following text documenting AC_PROG_LEX:

> You are encouraged to use Flex in your sources, since it is both
> more pleasant to use than plain Lex and the C source it produces is
> portable. In order to ensure portability, however, you must either
> provide a function yywrap or, if you don't use it (e.g., your
> scanner has no `#include'-like feature), simply include a
> `%noyywrap' statement in the scanner's source. Once this done, the
> scanner is portable (unless you felt free to use nonportable
> constructs) and does not depend on any library. In this case, and
> in this case only, it is suggested that you use this Autoconf
> snippet:

Eh?  This explanation seems rather poorly written, to the point of  
being largely incomprehensible, I fear.  After some discussion within  
our group we _believe_ that this means:

  1. Flex is better than lex for the given (and clear) reasons
  2. If and only if you use Flex, then you must
        (a) provide yywrap or use %option noyywrap, and
        (b) include the Autoconf snippet

(that is, it's ambiguous what `this case' is referring to).

Second, we are unable to attach a meaning to `your scanner has no  
`#include'-like feature' -- if this remark is important, perhaps it  
needs a little unpacking.

Third, the Flex manual  
<http://www.gnu.org/software/flex/manual/html_chapter/ 
flex_10.html#SEC10> mentions a `%option noyywrap', but no `%noyywrap'.   
Is this a typo?

If this is correct, then can I suggest the following wording:

We encourage you to use Flex for your sources, since it is both more  
pleasant to use than plain Lex, and the C source it produces is more  
portable.  If you do decide to use Flex, then in order to ensure that  
the generated scanner is portable in fact, you must either provide a  
function yywrap, or include a `%option noyywrap' statement in the flex  
source file.  Once this is done, the scanner is portable amongst C  
compilers (unless you felt free to use nonportable C constructs), and  
does not depend on any library.  If you use Flex, then we suggest that  
you also include the following Autoconf snippet, which detects when the  
Flex program is not available, and [???]:

...and what?  At the end, there, some explanation of _why_ this snippet  
is useful would be very valuable.  The snippet appears to simply  
disable flex/lex processing unless specifically flex is found.

Best wishes,

Norman


--
----------------------------------------------------------------------
Norman Gray  :  Physics & Astronomy, Glasgow University, UK
http://www.astro.gla.ac.uk/users/norman/  :  www.starlink.ac.uk