On Thu, 2009-05-14 at 09:17 +0200, Nico Coesel wrote: > > > -----Oorspronkelijk bericht----- > > Van: Zach Welch [mailto:z...@superlucidity.net] > > Verzonden: woensdag 13 mei 2009 13:17 > > Aan: Nico Coesel > > CC: openocd-development > > Onderwerp: jtag driver tutorial (was RE: > > [Openocd-development] doxygen update) > > > > On Tue, 2009-05-12 at 00:19 +0200, Nico Coesel wrote: > > [snip] > > > Allright! I need to write a driver somewhere in the next couple of > > > weeks/months (when the JTAG programmer hardware arrives). Perhaps I > > > can sketch/write some outlines on putting a driver together. I just > > > don't know how this would work with the current version of > > OpenOCD. A > > > lot seems to be happening lately (which is good!) but I'm > > not sure the > > > current driver model is still the same as version 0.1.0. > > > > Excellent. :) We definitely need more documentation writers! > > > > I recommend writing documentation for the current trunk. I > > just added "doc/manual/" in r1771 to provide the basic > > skeleton for OpenOCD's high-level doxygen documentation > > (which others can flesh out over time). > > I think what you describe should be a stand-alone document > > that reads more like a tutorial that a reference, and I have > > realized the need for more of such works by incorporating a > > "Technical Primers" section in the doxygen output. > > > > Please consider writing it iteratively and incrementally as > > you develop the driver, posting revisions for community to > > review just as you might the code. I think this work could > > produce common driver standards and then catalyze development > > to clean-up the existing drivers to meet them. > > > > I would suggest starting the file, > > "doc/manual/primer/jtag-driver.txt". > > Write a doxygen comment block to contain the tutorial, > > similar to the skeleton files now in the tree. Using > > doxygen's own documentation, you should be able to make your > > content appear in the proper section of the new OpenOCD > > Technical Primers page. > > Zach, > I have two issues with that: > First the document will probably in Word (.doc) format to include both > text and pictures. Plain text is just too limited. I suppose I can > provide the images in a different format as well. Text is easy to > extract / Word documents can be read by OpenOffice. My document layout > doesn't contain fancy stuff anyway.
Doxygen can embed images. It can do pretty looking formatting too. It is text with mark-up, so don't discard it out of hand. Plain text is the universal data format (particularly from a version control perspective), so will you still allow the community to extract any relevant information and absorb it into the doxygen manual? > Secondly I'm planning to use version 0.1.0 with the patches I made. I > need to push 'my' JTAG programmer project forward as fast as possible. I > don't want to skip documentation, but I can't spend time on debugging > OpenOCD at this moment. I'm willing to give r1771 a try (or any other > revision that is 'guaranteed' to work), but if it doesn't work from the > box I have to stick with version 0.1.0. >From what it sounds like, most folks have their platforms working as well as they did at 0.1.0, with perhaps a few exceptions. If you are writing a new driver, I think you will be much better off writing against the trunk, but you know your project better than I do. I can definitely understand your concern with using a stable branch,but I hope that we can regain your trust with the trunk. Hearing that a developer writing new device support does not want to use the latest version of the code for new development shows we have room to improve. Cheers, Zach _______________________________________________ Openocd-development mailing list Openocd-development@lists.berlios.de https://lists.berlios.de/mailman/listinfo/openocd-development
