> Hmm. Actually, afaik we were the first large open source project to
> successfully use the jade toolset for docs. Others have used our project
> as an example to help get them going, since as you have already found
> out getting the tool chain completely set up is not trivial.
>
> There are at least a few reasons why automatically generating hardcopy
> without a final adjustment step is not currently feasible:
>
> 1) Table column alignment is not ideal. Many tables are generated with
> same-width columns and some end up with large indents on each column.
> They just don't fit on the page without adjustments. That is for RTF;
> table support in jadetex has always been problematic.
>
> 2) Reference pages have a problem. It has *always* been the case that
> our reference pages do not format correctly. afaict it is is a problem
> with jade->RTF (since the problem shows up in both Applixware and
> M$Word) but I do not have much insight into RTF conventions so have not
> tracked it down. Very time-consuming hand-editing is required :(
>
> 3) Page breaks are not always ideal. Some hand adjustments are desirable
> to get a better flow to the docs, especially wrt examples and lists; you
> don't want them breaking between pages if you can avoid it, especially
> with short examples.
>
> 4) Table of contents page numbers are not correct in the RTF output, so
> a new ToC must be generated in Applixware or Word.
Can I add one more issue:
5) We have been working for translating docs into Japanese using EUC_JP encoding. Converting to HTML is no problem,
butwe cannot get correct results for sgml-> RTF conversion at all. The translated docs are just not be able to read,
showingrandom characters. It seems that openjade supports multibyte encodings at least according to their manuals,
butI can not get it working. I have asked to dssslist but I have not gotten usefull helps yet.
A qustion comes to my mind: Is really sgml is an appropriate doc format for us? For me, LaTeX seems more handy. It
cangenerate HTML using latex2html, and of course can produce beautiful hard copies AUTOMATICALLY for English and
otherlanguages including Japanese.
BTW, I see some odd results from the 7.1 HTML docs. For example, in
parser-stage.html,
"Figure \ref{parsetree} shows the parse tree..."
What is the "\ref{parsetree}"?
--
Tatsuo Ishii
