Re: What is dnl?

[Mark D. Baushke]

eric ehlers <address@hidden> writes:

> I'm using the documentation at 
> 
> http://www.gnu.org/software/automake/manual/html_mono/automake.html
> 
> and finding it very frustrating.  For example under "A classic
> program" you start using "dnl" without explaining what it means.
> 
> In the autoconf documentation, under "8.3.1 Redefined M4 Macros", I
> find this definition of dnl:
> 
> "This macro kept its original name: no m4_dnl is defined."
> 
> Great, that clears it up.
> 
> A good rule of thumb when writing documentation is to define a new
> term before you use it.  As a very minimum you should define new terms
> SOMEWHERE.
> 
> - What is dnl?  (I gather it relates to comments - why is it sometimes
> used with no comment text, like a carriage return?  How does it differ
> from #?)
> - Will you be revising your documentation to make it more newbie-friendly?
> 
> Thanks,
> Eric

dnl is an m4 builtin rather than something added by automake itself. So,
you should also consider visiting the documentation of the m4 language
itself to get a list of everything you are using.

        -- Mark

Excerpt from the GNU m4 manual:

| 
| Deleting whitespace in input
| ============================
| 
|    The builtin `dnl' reads and discards all characters, up to and
| including the first newline:
| 
|      dnl
| 
| and it is often used in connection with `define', to remove the newline
| that follow the call to `define'.  Thus
| 
|      define(`foo', `Macro `foo'.')dnl A very simple macro, indeed.
|      foo
|      =>Macro foo.
| 
|    The input up to and including the next newline is discarded, as
| opposed to the way comments are treated (*note Comments::).
| 
|    Usually, `dnl' is immediately followed by an end of line or some
| other whitespace.  GNU `m4' will produce a warning diagnostic if `dnl'
| is followed by an open parenthesis.  In this case, `dnl' will collect
| and process all arguments, looking for a matching close parenthesis.
| All predictable side effects resulting from this collection will take
| place.  `dnl' will return no output.  The input following the matching
| close parenthesis up to and including the next newline, on whatever
| line containing it, will still be discarded.
| 
...
|
|Comments
|========
|
|   Comments in `m4' are normally delimited by the characters `#' and
|newline.  All characters between the comment delimiters are ignored,
|but the entire comment (including the delimiters) is passed through to
|the output--comments are _not_ discarded by `m4'.
|
|   Comments cannot be nested, so the first newline after a `#' ends the
|comment.  The commenting effect of the begin comment character can be
|inhibited by quoting it.
|
|   The comment delimiters can be changed to any string at any time,
|using the builtin macro `changecom'.  *Note Changecom:: for more
|information.
|