xmlroff-list

[xmlroff] Syntax for controlling warnings?

[Tony G. <Ton...@Su...>]

As threatened, I have added "warning mode" to FoLibfoContext so you can select
to suppress certain types of warnings.

xmlroff now defaults to setting "warning mode" so it suppresses "unsupported
property" messages (which makes redundant a large part of libfo-compat.xsl).

You can currently set the warning mode on the xmlroff command line using '-w
<integer>', similarly to how you can set the debug level.

Magic numbers for debug level is fine (or, at least, not too bad) since if
you're debugging, you're going to be exposed to all sorts of gory details
anyway.

Magic numbers for warning mode seems less fine, since even casual users might
want to set the warning mode.

xmlroff currently has three separate warning mode flags: 'fo', 'property', and
'unsupported property' (athough only 'unsupported property' currently modifies
any behaviour).

How should the warning mode be specified on the xmlroff command line?

Regards,


Tony.

Re: [xmlroff] Syntax for controlling warnings?

[Stefan S. <se...@sy...>]

Tony Graham wrote:
> As threatened, I have added "warning mode" to FoLibfoContext so you can select
> to suppress certain types of warnings.
> 
> xmlroff now defaults to setting "warning mode" so it suppresses "unsupported
> property" messages (which makes redundant a large part of libfo-compat.xsl).

Awesome !

> You can currently set the warning mode on the xmlroff command line using '-w
> <integer>', similarly to how you can set the debug level.
> 
> Magic numbers for debug level is fine (or, at least, not too bad) since if
> you're debugging, you're going to be exposed to all sorts of gory details
> anyway.
> 
> Magic numbers for warning mode seems less fine, since even casual users might
> want to set the warning mode.

I think this is fine, even for casual users, as long as the various levels
are well documented (for example in the 'xmlroff --help' message).

That said, I think textual mode attributes are fine, too. In particular,
if they can be accumulate, such as in 'xmlroff -w fo -w property ...'.

For the actual messages please keep in mind that these may be used for
regression tests, so it would be good to avoid any runtime data such as
process-ids, dates, etc.
In fact, if these messages have some substructure (e.g. start with the
line in the input at which the problem occured, it might be good to
formalize the message structure to allow third party tools to develop
parsers so xmlroff can be wrapped in a gui. (I'm thinking in particular
of gcc's errors / warnings, and how these can be transformed into
links in an emacs or eclipse console...)

Regards,
		Stefan

Re: [xmlroff] Syntax for controlling warnings?

[Tony G. <Ton...@Su...>]

Stefan Seefeld <se...@sy...> writes:
> Tony Graham wrote:
>> As threatened, I have added "warning mode" to FoLibfoContext so you can select
>> to suppress certain types of warnings.
>> xmlroff now defaults to setting "warning mode" so it suppresses "unsupported
>> property" messages (which makes redundant a large part of libfo-compat.xsl).
>
> Awesome !

I'm glad you think so.

>> You can currently set the warning mode on the xmlroff command line using '-w
>> <integer>', similarly to how you can set the debug level.
>> Magic numbers for debug level is fine (or, at least, not too bad) since if
>> you're debugging, you're going to be exposed to all sorts of gory details
>> anyway.
>> Magic numbers for warning mode seems less fine, since even casual users might
>> want to set the warning mode.
>
> I think this is fine, even for casual users, as long as the various levels
> are well documented (for example in the 'xmlroff --help' message).

Not there yet.

> That said, I think textual mode attributes are fine, too. In particular,
> if they can be accumulate, such as in 'xmlroff -w fo -w property ...'.

I thought someone would ask for that.  popt could be made to do that, but I
didn't have the patience on the weekend to rework xmlroff.c to make it do it:
right now, all xmlroff arguments are parsed by popt straight into variable
values, and repeating '-w' would require either looping over the popt context
or implementing a callback function.

> For the actual messages please keep in mind that these may be used for
> regression tests, so it would be good to avoid any runtime data such as
> process-ids, dates, etc.

glib puts in the process id.

See the end of the generated 'testsuite/test.sh' in the 'testing' module for a
regex for stripping the process ids.

> In fact, if these messages have some substructure (e.g. start with the
> line in the input at which the problem occured, it might be good to
> formalize the message structure to allow third party tools to develop
> parsers so xmlroff can be wrapped in a gui. (I'm thinking in particular
> of gcc's errors / warnings, and how these can be transformed into
> links in an emacs or eclipse console...)

The input line number has been lost (I think), especially if you started with
an XML file and an XSLT stylesheet.

It's not that difficult to make xmlroff give an error message if you want to
see one for yourself.

Regards,


Tony.

Re: [xmlroff] Syntax for controlling warnings?

[Stefan S. <se...@sy...>]

Tony Graham wrote:

>>For the actual messages please keep in mind that these may be used for
>>regression tests, so it would be good to avoid any runtime data such as
>>process-ids, dates, etc.
> 
> 
> glib puts in the process id.
> 
> See the end of the generated 'testsuite/test.sh' in the 'testing' module for a
> regex for stripping the process ids.

I'm aware of that. That's why I ask. :-)
I don't think the process id is particularly helpful here (and in most other
contexts, for that matter). What is the advantage of using glib for that,
as opposed to your own logger ?


>>In fact, if these messages have some substructure (e.g. start with the
>>line in the input at which the problem occured, it might be good to
>>formalize the message structure to allow third party tools to develop
>>parsers so xmlroff can be wrapped in a gui. (I'm thinking in particular
>>of gcc's errors / warnings, and how these can be transformed into
>>links in an emacs or eclipse console...)
> 
> 
> The input line number has been lost (I think), especially if you started with
> an XML file and an XSLT stylesheet.

Right, I forgot about that. IIRC, libxml2 has some way to store line numbers
in dom nodes, I'm not sure whether that would help to trace the context back
though.

> It's not that difficult to make xmlroff give an error message if you want to
> see one for yourself.

Ok. I'm aware that I'm talking about nice-to-have stuff here. Feel free to
ignore it if it would be too hard to implement. It's just a usability issue
that may come up later again.


Regards,
		Stefan

[xmlroff] Usability issues

[Stefan S. <se...@sy...>]

Hi Tony,

as we talked about xmlroff's usability a while ago, here is an example I just ran into:

Processing some input file I just generated, I get this output:

(process:29504): libfo-CRITICAL **: fo_expr_eval: assertion `IS_CHAR (g_utf8_get_char (string))' failed

(process:29504): libfo-CRITICAL **: fo_property_id_validate: assertion `datatype != NULL' failed



I don't find this output particularly helpful, because:

* It isn't clear whether this is a warning or an error (though 'CRITICAL' certainly hints
   at an error).

* It isn't clear whether this is due to invalid input, an unimplemented feature
   in xmlroff, or something entirely different.

* It isn't clear whether there is anything I (as a user) can do to prevent this
   problem, by making changes to the input.


I'm not sure how these points should be addressed, and, whether this could
happen in the 0.4 timeframe.

Thanks,
		Stefan

Re: [xmlroff] Usability issues

[Tony G. <Ton...@Su...>]

Stefan Seefeld <se...@sy...> writes:
> as we talked about xmlroff's usability a while ago, here is an example I just ran into:
>
> Processing some input file I just generated, I get this output:
>
> (process:29504): libfo-CRITICAL **: fo_expr_eval: assertion `IS_CHAR (g_utf8_get_char (string))' failed
>
> (process:29504): libfo-CRITICAL **: fo_property_id_validate: assertion `datatype != NULL' failed
>
>
>
> I don't find this output particularly helpful, because:
>
> * It isn't clear whether this is a warning or an error (though 'CRITICAL' certainly hints
>   at an error).

It's a failed assertion.  One of the g_return_if_fail() or
g_return_val_if_fail() macro calls in the code.

> * It isn't clear whether this is due to invalid input, an unimplemented feature
>   in xmlroff, or something entirely different.

It is due to invalid input.  I am actually surprised that you managed to get
invalid UTF-8 that far into xmlroff.

> * It isn't clear whether there is anything I (as a user) can do to prevent this
>   problem, by making changes to the input.

A failed GLIB assertion macro indicates a programming error, either because
the program is doing something wrong or because the programmer didn't
anticipate that the user would do something wrong.

For example, I had assumed that libxml2 would have caught the invalid UTF-8
when your input XML was parsed to make an FoXmlDoc.  If it didn't, then I (or
someone else) should add checks for valid UTF-8 and give human-readable error
messages, and if there isn't a problem with your input XML, then there's a bug
somewhere that should be fixed.

> I'm not sure how these points should be addressed, and, whether this could
> happen in the 0.4 timeframe.

Firstly, we can document the meaning of 'assertion ... failed' messages.

Secondly, you can run 'xmllint' on your input document and stylesheet to see
if you can find any invalid UTF-8.

Thirdly, you can file a SourceForge bug report and attach your input XML to
it.

Regards,


Tony.