On 13.06.05, [EMAIL PROTECTED] wrote: > On Mon, 13 Jun 2005, G. Milde wrote: > > IMHO, the short description doesnot need any markup. (And if a see-also > > should be contained in the Synopsis (I would put See Also only in the > > full doc), an extraction script could easily convert a lfun-name to a > > link.) > > Hmm... are you suggesting that *only* the short description should go > into the source eventually? Wouldn't that too easily lead to the long > and the short descriptions diverging?
Yes. This seems to me as a good tradeoff between ease of work for the developers and user friendly documentation. The threat of diverging always exists. However with the source containing either the full description or no documentation at all, I fear the divergence to be between the function and the documentation. With a short description in the source, it might become easier to press the developers to keep this up to date. (At least this is my hope.) The preamble of References.lyx will tell that the short doc is more accurate (and should be trusted in case of inconsistencies). Also, the generating script should only include the documentation for lfuns that are currently defined in the source. Obsolete lfuns will linger in the template for a while but not go to the generated documentation (and the script will print a warning, maybe). > > The full description should use LyX markup (as we are all LyX users). It > > could be a "revived" and improved References.lyx document or a separate > > lyx file for every lfun. (see attachment for example). > > I see, a separate LyX document for the lfuns (partially generated). Would > there be one such document for each language? We should start with English. The intended audience of this Reference will most likely need to understand English. If the design proofes sucessfull, translating might become the next task. Strings in the source should use the po mechanism, the generating script as well, the template lyx file would have to be translated similar to all other help documents. > Anyway, I think the way forward now is simply to start compiling the raw > information... Eh... did you have an "up-to-date" list of lfuns btw? I have copied and converted to an ASCII/CSV format your list from the wiki: # The lists of LFUNs below were derived from from # releaes lyx-1_3_3 of [59]src/LyXAction.C. You find it in the pyLyX package on the PyClient page. (I can mail you a copy if you wish.) G�nter -- G.Milde web.de
