On Sep 2, 2009, at 11:20 AM, Alan W. Irwin wrote: > On 2009-09-02 12:00-0500 Hezekiah M. Carty wrote: > >> I'm still not entirely familiar with how Docbook markup works, but >> the >> PDF output looks good here and I think it gets the information across >> appropriately. Suggestions for improvement in the Docbook code as >> well as the actual documentation are welcome as always. > > Hi Hez: > > Thanks very much for your documentation update. > > The principal issue to be careful of is "make validate" finds no > errors. > (Your latest commit passes this test.) That is a fast and easy > method (which > requires the onsgmls application be installed but which does not > require > special configuration of the build) of checking that you haven't > introduced > some DocBook XML syntax error that will kill everybody's > documentation build > including the one that Hazen does for releases. > > It's that potential to kill the build that leads me to give "make > validate" > results the highest priority when evaluating patches to or commits > of files > in doc/docbook/src. The actual content of documentation upgrades is > a second > priority after that primary one. Basically, I believe we should be > happy to > take anything that we can get as the first try for documenting some > aspect > of PLplot; if necessary we can always refine the > wording/organization/consistency of form later. Of course, as you have > found, DocBook XML is not that hard to learn since you can do a lot > simply > by analogy with other aspects of the files in doc/docbook/src. > Thus, I > strongly encourage everybody on this list to send patches or make > commits to > those files to improve our DocBook documentation. And if some of you > don't > have onsgmls installed on your system, I am happy to try "make > validate" > here and correct any syntax errors it finds in your updates to the > documentation. > > Alan
Alan, I found some open-source (and commercial) docbook editors (OS X) that are pretty WYSIWYG--apparently they use some form of rules (schema?) to interpret the code as you edit, so that what you see is similar to what you get when you apply your own rules at rendering time. (Actually, I think OpenOffice.org is supposed to handle Docbook but my version doesn't render anything to the screen; I think I'm missing a plug-in or something.) But I was afraid to try any of them on the PLplot stuff for the very reason you mention--I was afraid it would trash something. Maybe I'll play with them more later. Jerry ------------------------------------------------------------------------------ Let Crystal Reports handle the reporting - Free Crystal Reports 2008 30-Day trial. Simplify your report design, integration and deployment - and focus on what you do best, core application coding. Discover what's new with Crystal Reports now. http://p.sf.net/sfu/bobj-july _______________________________________________ Plplot-devel mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/plplot-devel
