On Thursday 21 May 2009, Zach Welch wrote:
> Hi all,
>
> In thinking about user documentation, I was wondering whether we should
> think about adding doc/target/ and doc/boards directories. In it, we
> would place a documentation file for each supported target and board,
> respectively. It may be possible to consolidate some guides, but this
> would allow us to provide a nice addition to the user guide that would
> answer the example question: "what do I do to get target XX working?"
One of the last significant things-yet-to-be-done for the User's guide
is in this area. The answer I *want* to see for that question is:
- Fire up $EDITOR for "openocd.cfg"
- Add "source [find interface/...cfg]" for your
particular interface
- Add "source [find board/...cfg]" for your
particular board
- Save the file, exit $EDITOR
- Invoke "openocd" in the directory with openocd.cfg and
which holds files you want to download, and other stuff
you need to work with.
Plus the hardware connectivity steps, presumably for one of the widely
available ft2232 adapters. And a plea to submit more board config files.
Beyond that, I think that today we're realistically only at the stage
where "read the board config files" is good advice. There's too much
variability there, users need to know exactly what they're getting.
There's nothing wrong IMO with having documentation in the board.cfg
files ...
> Basically, I am suggesting target Quick Setup Guides, References, and
> FAQs. If we consider the same thing for the JTAG interfaces, this would
> allow us to move most of the part-specific text out of the main User
> Guide proper, allowing it to focus on introducing the general concepts
> that apply to all targets, boards, and interfaces.
Doesn't seem that plausible to me right now. Agree about focussing
the user's guide in that way -- it's got "issues" still -- but having
a flotilla of other docs seems very unlikely.
What does seem plausible is getting it to the point that there's less
chaos in the process of bringing up new boards, and that the docs
start to *help* that process. For two basic types of user: (a) the
person who can use one of the canned configs, since they already have
a config for their board/interface; and (b) the person who needs to
coem up with a new config.
- Dave
_______________________________________________
Openocd-development mailing list
Openocd-development@lists.berlios.de
https://lists.berlios.de/mailman/listinfo/openocd-development
