Known Issues
============

Error Handling [case 55]
------------------------
Error handling (particularly for errors occurring deep in nested
templates) isn't as useful as one might wish.  Errors tend to give you
a Ruby backtrace, and leave it to the user to decipher that and figure
out what went wrong.

This is particularly a challenge when you're dealing with nested
templates (where one template invokes another via "apply_idiom" or
"apply_by_node", for example).  The standard error generally only
identifies the template that the error actually occurred in (the
deepest of the nested templates), without identifying the calling
templates leading up to that one; that can make it difficult to
figure out how you got to the deeply nested template where the
error occurred.

WORKAROUND: Use the "-E" command line argument to 'ncg' to specify
a basename for error dump files.  Then, if an error occurs while
generating a config, a separate error dump file should be created
for each template, if there are nested templates.  If you specify
a "-E errfile" argument, the files will be named errfile.0, errfile.1,
and so forth. The deepest and most specific error will generally
be found in errfile.0, while the other error files may provide more
context to help you understand how you got to the point where that
deepest error occurred.

Self-Referential Loops [case 23]
--------------------------------
Self-referential loops are not detected; they'll simply send the
system off into an infinite loop, trying to resolve them.

The following in a .neto file would be an example of a self-referential
loop, whereby the system keeps trying to define "domain" in terms of itself:

	domain = [% "mgmt." + @target["(...)!domain"] %]

There is currently no workaround, other than to avoid creating self-
referential loops... ;-) In a future release, we'll figure out a way
to detect and deal with them.

Lack of Quoting Mechanisms [case 35, case 73]
---------------------------------------------
Currently, there is no quoting mechanism for strings in .neto or
.neto_table files.  For example, you can't do the following:
	name = Ext#123
because the system will treat '#123' as a comment, and you'll wind
up with simply "name = Ext".

WORKAROUND: you can work around this with ERB template blocks, because
comments are not stripped with then '#' is within an ERB block.
For instance, the following will work:
	name = [%= "Ext#123" %]

However, it's still possible to confuse the parser, even with this
workaround.  For instance, the following should work:
	name = [%= "foo" %] # [%= "bar" %]
and should result in "name = foo" (the "#" and everything following it
should be stripped as a comment, since the "#" is NOT inside an ERB block).
Unfortunately, it currently results in an error.

We'll look at improving this and adding a proper quoting mechanism
in a future release.

# $Id: ISSUES 338 2009-04-13 23:43:36Z brent $
# Copyright (C) 2008, 2009 Netomata, Inc.  All Rights Reserved. 
# Please review accompanying 'LICENSE' file or
# http://www.netomata.com/docs/licenses/ncg for important notices,
# disclaimers, and license terms.