be good long-term.
WRT xml editor, depends how graphical you want it. I just want color coding to show
me whether things are well-formed or not, and vim does that just fine.
vim filename.xml
(make sure to copy the sample .vimrc file into place or you won't get the filetype-
specific smarts).
The costs of DocBook are the setup (which you've already conquered), and working
with XML (for those who don't like to). The benefits are
clear division between content and presentation. Documenters need to use the
standard DocBook tags consistently, with minimal regard to how it will be
displayed. Style sheets and build options control what the output will look like.
The look of the docs in HTML, pdf, wml, etc. can be completely renovated
by modifying stylesheets and not touching the source *.xml files. (I'm talking
about section layouts, page navigation, TOC, lots of display things beyond
the scope of css).
Complete consistency in the output. The layout is enforced to be as technical
documentat should be-- this is way beyond what HTML editors are intended
to do.
Our remaining DocBook glitches have to do with index generation, and a simpler "include" mechanism. The best include mechanism, unfortunately, doesn't work well with the Java build systems, so we have to use XML entities for this purpose... (I'm also thinking that "<textobject fileref=...." could do most of what we need). Neither is a big deal. I'll deal with these limitations rather than trying to enforce style conventions on a bunch of developers using HTML editors any time.
As I've said before, the standard upgrade path for DocBook is to modify style sheets (not css, but the sheets that transform the source XML file to other formats). Seeing that Fred sees the need for additional documentation system features, I don't think HTML's going to do the job here (speaking only about the guide here).
Several times now, I've spent a couple hundred technical hours and a dozen DocBook hours on a commercial project. When I'm finished, the end user has nothing to say about the product but asks me what doc system I use because the documentation looks really good.
Thomas Mueller wrote:
Hi,
I would like to contribute to the documentation of HSQLDB and have some questions:
- I didn't find the files on web site in the CVS. Is is under version control? If I want to contribute to that part, what should I do?
- I had some problems when 'compiling' the docs (docbooks). I commited this to the file readmedocbook.txt (Sun JDK 1.4 Xerces / Xalan problem). Was that the correct way doing it? Did it actually work? I better as because I so far never commited anything to the HSQLDB project...
- When reading the existing documentation, I think the html docs should all use the same style (font and such). Do you agree when I create a stylesheet and try to link all html files to that one?
- I'm new to 'docbooks'. It sounds quite interesting to be able to create html and pdf files! So far, I did find it hard to get the build working (downloading 5 different libraries), but I can now create the pdf / hmtl files... But how should I edit the documentation? I use Windows XP. I don't have a problem using a text editor for xml files, but how do you edit the files? Is there a good editor (open source / free of course :-).
- (Maybe because I'm new to docbooks, and because I had trouble installing
it) I find it is simpler to just write html docs (using some html editor
like NVU or OpenOffice). I mean, at some point we should probably have some
Wiki system for the docs, and I guess html would be just the 'simpler'
format from a practical view... The pdf file can still be created using
OpenOffice, or a html to pdf converter like HTMLDOC. What is your experience
with docbooks? What is your position? I don't want to alienate anybody, but
I'm just writing directly what I think...
- Is it ok if I reorganize / link the docs a little? For me, all the html
files should be linked in some consistent way. Should we not convert all the
.txt files to proper html files and link them in some consistent way?
Thanks for your input, Thomas
-- ICF: 703-934-3692 Cell: 703-944-9317
------------------------------------------------------- This SF.net email is sponsored by: IT Product Guide on ITManagersJournal Use IT products in your business? Tell us what you think of them. Give us Your Opinions, Get Free ThinkGeek Gift Certificates! Click to find out more http://productguide.itmanagersjournal.com/guidepromo.tmpl _______________________________________________ hsqldb-developers mailing list [EMAIL PROTECTED] https://lists.sourceforge.net/lists/listinfo/hsqldb-developers
