Automating error message references

Question

I'm writing a book which will include error messages and codes from a strange computer system. What I need to do is this:

Maintain a list of error message codes:

ABC0000T

For each code, have a sample message text:

ABC0000T Badgers detected - code xx

And a descriptive text:

If the current daily badger access code doesn't match xx, badger access control has failed and you should call out support immediately.

If the code is 99, then these are zombie badgers and you should fly for your life.

The way I see this working is this: at some point in the book (probably an appendix), all this stuff is printed, probably in alphabetical order of message code (though I may need to split things into two or three sections/groups. In the body of the book, I write turgid stuff like:

If any problems occur with badger access, message ABC0000T is issued and the system halts.

where the message text is also a hyperlink into the messages appendix.

Here's the question: I think the glossaries package is probably up to this, but before I start investing time, can you provide better suggestions?

Improvements to the title and the tagging (or indeed, anywhere) are cordially invited.

Answer 1

Here is my suggestion, and hopefully this will useful to you. It is a simplified version of what I am using for my work, but still should contain enough to illustrate how it works and get you going. I have not addressed the spacing issues with environments/commands, etc as that is not the thrust of this question.

The complete MWE example is at the end (and included MyPreamble.sty), but will explain in pieces first.

1. Each error message is stored in a separate file and can be compiled standalone. This can easily be extended much further depending on how much flexibility is required. So the following would be ABC0000T.tex:

   \documentclass{article}
   \usepackage{MyPreamble}
   
   \begin{document}
   \begin{ErrorMessage}
   \BriefMessage{%
      ABC0000T Badgers detected - code xx.
   }
   
   \DetailedMessage{%
     If the current daily badger access code doesn't match xx, badger access control 
     has failed and you should call out support immediately.
   
     If the code is 99, then these are zombie badgers and you should fly for your life.
   }
   \end{ErrorMessage}
   \end{document}
   

   Keeping each of the messages in a separate file will ensure that each error code is unique, and allow you to easily locate and edit a specific error code. Compiling the above file you get:

   

2. Once you have the above set of files you can use a \foreach type of loop to include all the files to generate

   • an Appendix with the error codes, brief message, detailed message
   • an index of all the error codes, etc.

   This is not covered in the MWE provided.

3. Then, to access these you can use \ExtractBriefMessage{ABC0000T} and that will produce:

   

   or with \ExtractDetailedMessage{ABC0000T} you get:

   

Warning:

• The MWE below will overwrite the files MyPreamble.sty and ABC0000T.tex in the directory where you run this.

Further Enhancements

• The error message should probably be stored in a separate directory.
• Different types of messages such as: Info, Warning, Error, etc..
• Allow for the error name to be different than the file name. This can be done by providing an optional parameter to the ErrorMessage environment. For instance, you can use \begin{ErrorMessage}[\textcolor{red}{ABC}\textcolor{blue}{0000}T].

Code

Here is the complete MWE.

\documentclass{article}

\usepackage{filecontents}
\begin{filecontents*}{MyPreamble.sty}
    \usepackage{standalone}
    \usepackage{xcolor}
    \usepackage{mdframed}
    \mdfdefinestyle{MdframedErrorMessageStyle}{%
        skipabove=\baselineskip plus 2pt minus 1pt,%
        skipbelow=\baselineskip plus 2pt minus 1pt,%
        frametitlerule=true,%
        leftmargin=-3pt,%
        rightmargin=-3pt,
        outerlinewidth=1.5pt,%
        roundcorner=3pt,%
        nobreak=true,% do not split across pages
        frametitle={Error Message},%
        frametitlebackgroundcolor=gray!20,%
        backgroundcolor=blue!90!red!5,%
    }%
    \newcommand{\BriefMessage}[1]{%
        \addvspace{\baselineskip}\par\noindent%
        \textbf{Brief Message:} #1%
    }%
    \newcommand{\DetailedMessage}[1]{%
        \addvspace{\baselineskip}\par\noindent%
        \textbf{Detailed Message:} #1%
    }%
    \newenvironment{ErrorMessage}{%
        \begin{mdframed}[%
            style=MdframedErrorMessageStyle,%
            frametitle={Error Message: \jobname}%
            ]%
    }{%
        \end{mdframed}%
    }%

    % If new environemnts/commands to be used within an ErrorMessage
    % they shuld be disabled in this macro.
    \newcommand{\DisableAllErrorMessageMacros}{%
        \let\ErrorMessage\relax%    Disable mdframed environemnt
        \let\endErrorMessage\relax%
        \newenvironment{ErrorMessage}{}{}%
        \renewcommand{\BriefMessage}[1]{}% ignore brief message
        \renewcommand{\DetailedMessage}[1]{}% ignore detailed message
    }%
\end{filecontents*}


\begin{filecontents*}{ABC0000T.tex}
    \documentclass{article}% Each error message is a complete standalone document
    \usepackage{MyPreamble}

    \begin{document}
    \begin{ErrorMessage}
    \BriefMessage{%
        ABC0000T Badgers detected - code xx.
    }

    \DetailedMessage{%
        If the current daily badger access code doesn't match xx, badger access control has failed and you should call out support immediately.

        If the code is 99, then these are zombie badgers and you should fly for your life.
    }
    \end{ErrorMessage}
    \end{document}
\end{filecontents*}

    \usepackage{MyPreamble}
    \newcommand{\ExtractBriefMessage}[1]{% #1 = error message id
        \DisableAllErrorMessageMacros%
        \renewcommand{\BriefMessage}[1]{##1}%
        \input{#1}%
    }%
    \newcommand{\ExtractDetailedMessage}[1]{% #1 = error message id
        \DisableAllErrorMessageMacros%
        \renewcommand{\DetailedMessage}[1]{##1}%
        \input{#1}%
    }%

\begin{document}
The brief message is:
\ExtractBriefMessage{ABC0000T}

\medskip\hrule\medskip

The detailed message is:
\ExtractDetailedMessage{ABC0000T}
\end{document}