vicuna
commented
18 years ago Comment author: administrator
On Mon, 25 Jul 2005 21:59:01 +0200 (MET DST) gerd@gerd-stolpmann.de wrote:
Full_Name: Gerd Stolpmann Version: 3.08.3 OS: Linux Submission from: p54a79b9e.dip0.t-ipconnect.de (84.167.155.158)
Hello,
Hello,
I am currently updating the documentation of ocamlnet. This is a quite complex set of libraries, and it is necessary to include introductional, teaching, and explanatory material into the documentation. My wish is to have text-only pages for ocamldoc that aren't related to code, but that may link to code if the author wishes so. For example, there is the new nethttpd library. I would like to include an overview page that explains how the modules work together. This page would be on the same level as the top-level modules, but of course, it isn't a module. Currently, I work around this missing feature by adding the overview text to one of the modules, but this is not ideal.
My suggestion is quite simple: Besides interfaces and implementations, there is a third category of files with the suffix ".txt". These files are processed by ocamldoc like the intro page that is already possible. The files get also a name like the module files, e.g. nethttpd_overview.txt would be accessible as Nethttpd_overview (e.g. in hyperlinks). I think this extension is quite simple to do, consistent with the existing design, and would allow authors to write more kinds of reference manuals.
That's done in the CVS (publicly available within some hours). The content of each .txt file given in arguments in interpreted like an empty module with one comment. Cross-ref works to and from this comment. Let me know if it suits your needs or not.
(Well, if you asked me whether there is another missing features in ocamldoc, I would say: pictures. Other authors have probably other wishes that are not that important for me. Maybe the future direction of ocamldoc should be better extensibility. Custom tags are not sufficient. I have here two suggestions: (1) A general-purpose custom notation {foo ...},
Ok, I'll add this.
and (2) an XML output format allowing easier postprocessing - currently, defining a custom generator is quite difficult - an XML transformation would be much simpler.)
Ok. Do you have a DTD in mind ? or some ideas about the structure ?
Thanks for your suggestions.
Best regards,
Maxence Guesdon
Original bug ID: 3737 Reporter: administrator Status: closed (set by @damiendoligez on 2005-12-15T14:15:36Z) Resolution: fixed Priority: normal Severity: feature Category: ~DO NOT USE (was: OCaml general)
Bug description
Full_Name: Gerd Stolpmann Version: 3.08.3 OS: Linux Submission from: p54a79b9e.dip0.t-ipconnect.de (84.167.155.158)
Hello,
I am currently updating the documentation of ocamlnet. This is a quite complex set of libraries, and it is necessary to include introductional, teaching, and explanatory material into the documentation. My wish is to have text-only pages for ocamldoc that aren't related to code, but that may link to code if the author wishes so. For example, there is the new nethttpd library. I would like to include an overview page that explains how the modules work together. This page would be on the same level as the top-level modules, but of course, it isn't a module. Currently, I work around this missing feature by adding the overview text to one of the modules, but this is not ideal.
My suggestion is quite simple: Besides interfaces and implementations, there is a third category of files with the suffix ".txt". These files are processed by ocamldoc like the intro page that is already possible. The files get also a name like the module files, e.g. nethttpd_overview.txt would be accessible as Nethttpd_overview (e.g. in hyperlinks). I think this extension is quite simple to do, consistent with the existing design, and would allow authors to write more kinds of reference manuals.
(Well, if you asked me whether there is another missing features in ocamldoc, I would say: pictures. Other authors have probably other wishes that are not that important for me. Maybe the future direction of ocamldoc should be better extensibility. Custom tags are not sufficient. I have here two suggestions: (1) A general-purpose custom notation {foo ...}, and (2) an XML output format allowing easier postprocessing - currently, defining a custom generator is quite difficult - an XML transformation would be much simpler.)
Gerd