Re: [PATCH 18/18] document the new VxWorks port

[Eli Zaretskii <eliz@gnu.org>]

> From: Joel Brobecker <brobecker@adacore.com>
> Cc: Joel Brobecker <brobecker@adacore.com>
> Date: Thu, 24 Feb 2011 12:49:23 -0500
> 
> The VxWorks documentation was completely out of date, so I rewrote it
> from scratch.  I tried to organize it in a logical way, introducing
> some of the concepts about VxWorks, to make the port a little alien
> to someone who is not familiar with this OS.
> 
> I've also included a NEWS entry.

Thanks.

> +VxWorks 653			i[34567]86-*-vxworks653
> +				powerpc-*-vxworks653
> +VxWorks 6.x			i[34567]86-*-vxworks6*
> +				powerpc-*-vxworks6*
> +				e500*-*-vxworks6*
> +VxWorks 5.x (x >= 4)		i[34567]86-*-vxworks*
> +				powerpc-*-vxworks*

This part is okay.

> +a @dfn{task} (a.k.a. a thread), usually using a symbol name as the entry

You need a "@:" after "a.k.a.", to indicate to TeX that the last
period does not end a sentence.

> +To create a new task under debugger control, use the @code{run}
> +command, passing as the first parameter the name of the symbol
> +to use as the entry point (all other parameters are ignored):

This seems to piggy-back the normal "run" command with a slightly
incompatible semantics, is that right?  If so, I would mention where
"run" is described that there are additional VxWorks specific features
(imagine a user who debugs VxWorks and needs to consult the
description of "run"), with a cross-reference to here.  And I would
also add here a @kindex entry like so:

  @kindex run, with VxWorks

> +Instead of creating a new task, it is also possible to attach the
> +debugger to an already existing task, using the @code{attach} command.
> +The equivalent of the Unix process ID is the task ID on VxWorks, and
> +these IDs should be used to identify the task that needs to be
> +debugged.

Same here: add a note where "attach" is described, with reference, and
an index entry he.

> +@kindex info wtx threads
> +@item info wtx threads

Why a separate command?  Isn't it possible to use "info threads"?

> +@cindex VxWorks, Multitasks Mode Debugging
> +@item Multitasks Mode

Is this really "Multitasks", with an `s' at the end?  That sounds like
a typo to me.

> +This is a mode specific to Ada programs where the debugger simulates
> +the concept of debugging a process. This is useful when trying to debug
                                     ^^
Two spaces, please.

> +This mode is specific to Ada programs because it, because it relies
                                         ^^^^^^^^^^^^^^^^^^^^^^
Repetition.

> +@kindex set multi-tasks-mode
> +@item set multi-tasks-mode [on|off]
> +If @code{on}, activate multi-tasks mode.  The default is @code{off}.

Is "multi-tasks mode" the same as "Multitasks Mode" above?  We should
be consistent in how we spell the terminology.

> +This setting should be properly set before using the @code{attach}
> +or @code{run} command.

"setting should be set"? can we do better here?

Also, what does "properly" do here?

> +@subsubsection Debugging on VxWorks 653

A @cindex entry here will help.

> +@table @code
> +@kindex info partitions
> +@item info partitions

Why not "info wtx partitions", or some other variant to make sure this
is VxWorks specific?  "info partitions" is too general to reserve for
a niche platform.

> +@kindex partition
> +@item partition @var{id-or-name}

Same here.

> +@kindex show wtx tool-name
> +@item show wtx tool-name
> +Display the tool name used when establishing a connection with the
> +WTX server.
> [...]
> +@kindex show wtx load-timeout
> +@item show wtx load-timeout
> +Print the timeout duration used when loading modules on the target.

Sometimes "display", sometimes "print".

> +handling.  The events being traced are all the events that wtxEventGet
> +returns (Eg: breakpoint events, watchpoint events, new modules loaded,
            ^^^
"e.g.,"

> +etc@dots{}).

Either "etc" or "@dots{}", but not both.

> +to connect to a DFW server in addition to the Target Server.  The
> +@dfn{DFW server} is another server running on the host (see your

Please use @dfn the first time you mention the term.

> +that is not known for task types (e.g. ``RTP''), task states
> +(e.g. ``running''), event kinds (e.g. ``download-failed'').

Either "@:" or a comma after each "e.g.".

Thanks.