Date: Sun, 23 Jan 2000 10:04:19 +0200 (IST)
From: Eli Zaretskii <eliz AT is DOT elta DOT co DOT il>
X-Sender: eliz AT is
To: Richard Dawe <richdawe AT bigfoot DOT com>
cc: djgpp-workers AT delorie DOT com
Subject: Re: docs for symify
In-Reply-To: <38897875.F4C5E782@tudor21.net>
Message-ID: <Pine.SUN.3.91.1000123100359.26609M-100000@is>
MIME-Version: 1.0
Content-Type: TEXT/PLAIN; charset=US-ASCII
Reply-To: djgpp-workers AT delorie DOT com
Errors-To: dj-admin AT delorie DOT com
X-Mailing-List: djgpp-workers AT delorie DOT com
X-Unsubscribes-To: listserv AT delorie DOT com
Precedence: bulk


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.