From: David P. <pr...@sf...> - 2003-07-21 19:14:54
|
It's been a while since I posted, so let me state my background again: I'm writing user manuals for some hardware/software products. These manuals were previously created using Ventura Publisher, which is a long-document application rather like Framemaker (but with a far better UI). I have completed a fifty-odd page hardware reference manual and am in the process of finishing a two-hundred-odd page software reference manual. These manuals are published to PDF through DocUtils XML and a set of XSL:FO transformations that I have written over the past two months. The Apache FOP renderer is used to publish XML:FO to PDF. I would like to share the XML:FO transformation sheets with DocUtils users. I believe I shall generally do this by writing a web tutorial, so that users can customize the sheets as needed for their own particular application. I'll do this when I get a chance, probably starting in September. DocUtils has been mostly very good for my needs. I do, however, find that it has a few gaping holes that are very likely to pose a problem for most authors. These are as follows: - there is no support for UI element tagging. No :mouse:, :key:, or :gui: tags. This is a shame, because a lot of DocUtil authors are, I believe, documenting software, which generally means they're documenting user interfaces. - targets are sometimes mis-located. In particular, placing a target before a section header puts the target at the end of the previous section instead of the start of the next section. Programatically this makes sense; aesthetically, it does not: one usually places a target reference immediately before the thing being targeted. This probably merits some amount of discussion. - we could use a .. comment:: [author] tag. This would facilitate team authoring. There are ordinary comments, but these are prey to misidentification, and there's no way to automagically pull them from the source by author name. Indeed, a kick-ass comment tag would allow for author, date, and ID. If you're interested in the XSL:FO stuff, give a shout. I'm happy to share, provided you feedback your changes or ideas to me. When I write the tutorial, I'd like the XSL:FO to be maximally useful to the broadest number of users. |