Take the 2-minute tour ×
TeX - LaTeX Stack Exchange is a question and answer site for users of TeX, LaTeX, ConTeXt, and related typesetting systems. It's 100% free, no registration required.

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.

share|improve this question
1  
I recently had something with very similar requirements, and the easiest (for me) was to keep each of the error messages in a separate file and define an environment to capture the info: error code, short description, long description, and any other subsections. Then a simple \foreach can iterate thru these and generate the Appendix. This also allows for easy extraction if you want to repeat any of the content in your document, and could easily be adapted to also use glossaries or some similar package. –  Peter Grill Jun 12 '12 at 20:53
1  
I think here is a very similar problem and a solution with LuaLaTeX: tex.stackexchange.com/a/41499/10570. Maybe it could be an approach for you. You can write all the error messages in a file and fill a LuaLaTeX table with it's content. Once the data is in the table you can create functions and macros to format text and (sorted) glossary/index entries. –  Holle Jun 15 '12 at 15:33
    
@Holle: Thank you. For a number of reasons I won't go into, I'm sticking with XeLaTeX at the moment. No disrespect to LuaLaTeX, I'm just not quite ready to make the move. –  Brent.Longborough Jun 15 '12 at 19:11
    
@PeterGrill: Thanks for the idea. I'm not yet at the point where I have to decide, so I'm going to leave this question for now, but if, sometime, you care to turn that into an answer, it'll probably have a very good chance of being the one. –  Brent.Longborough Jun 15 '12 at 19:13
    
@Brent.Longborough: I just thought that someone else would have a more elegant better solution, but since none have shown up I will post one this weekend. –  Peter Grill Jun 15 '12 at 19:45
show 1 more comment

1 Answer

up vote 9 down vote accepted

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:

    enter image description here

  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:

    enter image description here

    or with \ExtractDetailedMessage{ABC0000T} you get:

    enter image description here

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}
share|improve this answer
    
Peter, fantastic piece of work, so good I've accepted it before even testing! –  Brent.Longborough Jun 16 '12 at 9:53
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.