On 2009-09-04 01:03-0700 Jerry wrote: > On Sep 2, 2009, at 11:20 AM, Alan W. Irwin wrote: >> 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.
> 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. Hi Jerry: By all means go ahead and try any DocBook editor you like. Just be sure to run "make validate" and "svn diff" to check your changes before you commit anything, and you should be okay. Even if a screwup somehow gets committed despite those recommended checks, we can always revert the commit. However, one potential issue you should be aware of is our DocBook source is spread over a number of different files. For example, we define most/all entities in the configuration template file doc/docbook/src/plplotdoc.xml.in. Thus, for perfect syntax checking and display of the whole document, your editor will have to start with the configured version of that file (which will appear as doc/docbook/src/plplotdoc.xml in the build tree after cmake is run) and follow all the SYSTEM directives to files such as api.xml which contain bits and pieces of the DocBook source for the whole document. The onsgmls application used by "make validate" and the DocBook documentation build tools automatically treat all those separate files as one document source, but it is a bit of a stretch for DocBook editors to do that as well. So you will likely have trouble with WYSIWYG editors unless they can deal with multiple files as a unified DocBook source. Here is what works for me for DocBook editing. I used to use a light-weight editor (jed) to edit our DocBook source, but typing in those XML tags got a little tiresome so now I have switched to the emacs editor in nxml/DocBook mode for editing our DocBook source. I am just learning this mode of emacs, but I like what I see so far. It is not WYSIWYG, but only a small number of keystrokes are required to create the necessary XML tags since there are useful commands for completing XML tags with a choice of all the possibilities in that context (see the nxml documentation at http://infohost.nmt.edu/tcc/help/pubs/nxml/ for more information). Also, everything is continuously validated so if you have introduced some XML nesting issue or you are attempting to use the wrong DocBook XML tag for the particular context, it lets you know about it (by highlighting the problem). As far as I know, this emacs mode does not have the capability of treating separate source files as one unified DocBook source. Thus, when I edit a single file of our source (such as api.xml), emacs highlights all the entities as syntax errors because it is unware of plplotdoc.xml where they are defined. This is the only downside I have seen so far for using this mode of emacs to edit our DocBook source, and I expect (as stated above) this will probably be an issue for all DocBook editors. In any case, when editing some of our DocBook source, I always periodically run "make validate" to provide near-instantaneous validity checking of my changes in the context of our entire DocBook source, and I think that is a good idea no matter what DocBook editor you decide to use. Alan __________________________ Alan W. Irwin Astronomical research affiliation with Department of Physics and Astronomy, University of Victoria (astrowww.phys.uvic.ca). Programming affiliations with the FreeEOS equation-of-state implementation for stellar interiors (freeeos.sf.net); PLplot scientific plotting software package (plplot.org); the libLASi project (unifont.org/lasi); the Loads of Linux Links project (loll.sf.net); and the Linux Brochure Project (lbproject.sf.net). __________________________ Linux-powered Science __________________________ ------------------------------------------------------------------------------ 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
