Question About PP Errors & Warnings

[Tristano Ajmone]

I'm working on a binary flat-file CMS that uses PP and pandoc to create HTML documentation (or websites) from markdown source files.

I need to fine-tune the handling of PP/Pandoc errors and warnings.

Could you provide me some details on how PP reports errors and warnings?

I'm currently capturing separately the Exit Code and STDERR messages from PP and pandoc process.

What values can I expect for Exit Code? (ie: is just a boolean error or no error value, or are there error-specific values returned?)

Are there only fatal errors, or can I expect also non-blocking warnings? (ie: for which my app should not abort operations but should inform the user about PP warnings).

Could you provide me some simple examples of how to raise errors and warnings by both messing up the command line arguments and the markdown source macros, so I can test if my app handles them correctly. (eg: like trying to redefine a built-in macro).

Is there a test file for errors and warning in PP's source?

PS: I've looked at the code in ErrorMessages.hs, but I couldn't gather much info from it due to lack of Haskell knowldege.

[Tristano Ajmone]

If my understanding of ErrorMessages.hs source is correct, these are the current possible PP error types:

1. unexpectedEndOfFile
2. arityError
3. invalidNameError
4. builtinRedefinition — when attempting to redifine a builtin macro (either via CLI options or macros in the MD source).
5. fileNotFound — when a non-existing file is passed as as either CLI option or as a parameter to a file-related built-in macro (eg: !include).
6. codeblockError
7. indentError

All of which ao far seem to produce an Exit Code 1 and prevent emitting any output on STDOUT.

[Christophe Delord]

The error management is very basic...

• 1 warning when deprecated macros are used => the process continues, the output is generated and the exit code is 0.
• All other errors are fatal => the process immediately stops, the output is empty (except from the potential side effects produced before the error) and the exit code is 1.
  I mainly use pp with make. Make knows when pp fails thanks to its exit code.

[Tristano Ajmone]

Thanks a lot! This was very useful and allowed me to readapt my code accordingly so I can catch them properly (ie: if exit code is 0 but STDERR produced some text I'll catch it as a warning).

I'll probably end up treating PP warnings like errors in my app (this is what I've done with pandoc warnings) -- ie: the cms app will abort all operations when a warning is returned by PP or pandoc.

My reasoning is that the presence of a warning in either of these apps indicates some malformedness in the markdown source (or other problems) which can (and should) be fixed.

Since most projects are going to be collaborative, it might be best to prevent contributors pushing sources which are not 100% compliant — even if a deprecation warning doesn't prevent the document being converted, it still poses a potential problem for the future, so it should be fixed.