Nikita Karetnikov <[email protected]> skribis: >> 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. > > Are you talking about the pdf versions?
It’s poor in terms of presentation, not in terms of typography. > Could you show an example? http://www.gnu.org/software/guile/manual/html_node/Standard-Library.html (Watch it before 2.0.8 is out.) >> 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. > > I don't understand this part. Is it trying to say that it was necessary > to rewrite the relevant parts of the manual by hand? Is it trying to > say that the sources were moved somewhere from Guile-Lib? Is it about > the code or the manual? It’s about the manual. Initially, each of the sections above was entirely extracted from the corresponding module: the module contained a comment at the top that would give a rough overview, and the rest was just taken from docstrings. The result looked poor mostly because there is little introductory material, few cross-references, and the modules and procedures are listed in alphabetical order, which is rarely the right order to introduce and connect concepts. >> 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.) > > Good, I agree. > >> We would still write appropriate text to provide context and >> cross-references above the raw function @deffn lists. > > OK. But I hope that the glue text won't be technical but philosophical > (to avoid mistakes). For instance, it can explain the rationale or talk > about the GNU system. Yes, the extraction would be for the APIs, which are currently almost undocumented in the manual. > Each module should be self-contained. It should be possible to import > it somewhere without a problem. Basically, the current version of the > manual follows the same approach; each module has its own node: > "Invoking guix-daemon," "Invoking guix package," and so forth. These are not modules, these are commands. I wouldn’t want to automatically extract command-line doc. First, because --help needs to be concise, whereas the manual can give additional details (compare ‘guix package --help’ and “Invoking guix packages”.) Second, because the manual should include cross-references and examples to make things more understandable. > So it's only necessary to represent this information using docstrings > and commentary (i.e., a module-level documentation). > > Could you explore the possibilities of the literate programming system? > So we can identify the missing bits. Of course, I'll do the same. What I have in mind is just API documentation. This is easily done by traversing the exported bindings, and calling ‘procedure-documentation’. There’s a complication: currently docstrings in Guile must be Info-style plain text, not Texinfo (this may change in the future.) So one would need to infer Texinfo markup from the docstrings. Anyway, a clarification: I find it OK to extract docstrings today, because it’s better than nothing; but to me, a good manual should be more than a mere paragraph followed by a list of docstrings. Thanks, Ludo’.
