Date: Sun, 23 Jan 2000 10:04:19 +0200 (IST) From: Eli Zaretskii To: Richard Dawe cc: djgpp-workers@delorie.com Subject: Re: docs for symify On Sat, 22 Jan 2000, Richard Dawe wrote: > Please find attached a context diff against djlsr203 that adds a > description of symify to src/utils/utils.tex. Thanks! Allow me a few comments about the markup: > + When a DJGPP program crashes, it (usually) produces some diagnostic > + information. This is called a traceback and shows the processor's registers Whenever you introduce a new term, like ``traceback'' here, it is usually a good idea to say @dfn{traceback}. > + @example > + Exiting due to signal SIGSEGV > + General Protection Fault at eip=0000158a > + eax=ffffffff ebx=00008268 ecx=00000000 edx=0000033f esi=00000054 edi=0000c2f4 An @example whose lines are this long should use @smallexample, otherwise TeX will yell bloody murder. (@smallexample typesets with a smaller font, and so has better chances not to overflow into the right margin of the page.) > + @item > + compiled with debugging, i.e. the @code{-g} option passed to gcc; Command-line options should use the @samp markup (Texinfo 4.0 introduces the new @option command which produces the same result as @samp, but makes it easier to remember). > + To analyse the traceback off the screen for a program that has just crashed, > + run symify like: Names of programs should use @code (unless program's name became a proper name, like GCC or GDB). > + symify can also analyse a saved traceback. The traceback can be saved by > + input redirection (e.g. via @pxref{redir}) ^^^^^^^^^^^^^^^^^ Don't do that: it might look neat in the Texinfo source, but produces awkward results in Info: input redirection (e.g. via *Note redir::) and something utterly unreadable in the printed output: input redirection (e.g. via see Section 6.7 [redir], page 123) Resist the temptation and use the normal "(e.g. via @code{redir}, @pxref{redir})" instead.