On 07.07.2011 14:59, TJ Frazier wrote: > On 7/7/2011 07:26, Mathias Bauer wrote: >> Moin, >> >> I know how the help files where written at Sun/Oracle: the writers took >> Writer for the text and used a set of basic macros to put some markup >> into the files. Then they used an xslt to convert the document into the >> xhp format. >> >> I can't speak for the help writers, but most probably that isn't >> necessary as we shouldn't ask those who created help content in the past >> but those who will do it in the future. >> >> IMHO using a well-established, maintained tool instead of a home brewn >> set of macros that probably has lost its maintainer would be a huge >> improvement. > > While I don't oppose a change to DITA, I do offer another string to the > bow. One advantage of the Writer / macros method is that it greatly > lowers the bar to participation. Example: I volunteer to maintain the > macros (and at least help with the source) either for the interim, or > indefinitely. I don't know xslt technology, but I should be able to > learn as much as is needed, quickly. >> >> There's another aspect that we should see: extension developers might >> also want to add help content to their extensions. As until now there is >> no tool available for the public, extension developers had a problem. >> DITA would be an improvement for them. > > The obvious alternative is to make the existing method public: create a > template with the Basic macros in a library, and make that and the xslt > down-loadable.
The macro package is available as an extension that can be installed with the extenion manager. It also contains the xslt that is installed as an export filter. I only rarely worked with this help editor, but from these occasions I remember that it was a little bit awkward. > Mathias, you would know much better than I how feasible it would be to > use some kind of Writer window to display help. Without making light of > the technical problems, I am intrigued by lowering the participation bar > that far. Translators could work directly with .odt files. Users could > customize their own help, using Writer, and (we would hope) send us > their suggestions and improvements. You might think that using Writer to edit the help content is a big plus, but all that is used is entering text and formatting through the assignment of styles - nothing fancy, as the help content file format itself isn't very feature rich. So the learning curve for other editors should be quite flat. Anyway, I don't believe that this is one of the most urgent problems to solve. First we have to get the code and build it, later we can look for people willing to write help content. We should present them the alternatives (and something like DITA definitely would be one to consider) and ask them what they prefer. Regards, Mathias
