Nikita Karetnikov <[email protected]> skribis: > Here is what I found yesterday: [1,2]. Those (texinfo ...) modules > provide various functions to generate html, pdf, and info from a single > source file.
[...] > [1] > http://wingolog.org/archives/2004/07/25/literate-programming-with-guile-lib > [2] http://wingolog.org/archives/2006/11/17/high-on-sodium-vapor Guile-Lib’s method was eventually integrated in Guile 2.0, to generate the documentation of modules that were imported from Guile-Lib, such as the texinfo and sxml modules. The result, as can be seen in Guile’s manual up to 2.0.7, was of poor quality compared to the rest of the manual. That’s why the upcoming 2.0.8 (due in a couple of days) got rid of that. NEWS reads this (written by Andy): ** An end to the generated-documentation experiment. When Guile 2.0 imported some modules from Guile-Lib, they came with a system that generated documentation from docstrings and module commentaries. This produced terrible documentation. We finally bit the bullet and incorporated these modules into the main text, and will be improving them manually over time, as is the case with SXML. Help is appreciated. So yes, you’re right that synchronizing code (and docstrings) with a separate Texinfo manual can lead to discrepancies. Yet, “good” manuals can hardly be automatically generated. For Guix, perhaps a middle ground approach could be used. For instance, we would keep the manual in its current form, but extract docstrings for internal modules in separate .texi files, which would be @included in the right places of the manual. (It would be an improvement over the current situation where almost none of the API documentation appears in the manual.) We would still write appropriate text to provide context and cross-references above the raw function @deffn lists. WDYT? Thanks, Ludo’.
