Documentation for this Tcllib package can be found at the locations listed below. For writers of manpages: * http://tcllib.sourceforge.net/doc/doctools_fmt.html ---- doctools language (manpages) * http://tcllib.sourceforge.net/doc/doctoc_fmt.html -- doctoc language (table of contents) * http://tcllib.sourceforge.net/doc/docidx_fmt.html ---- docidx language (indices) Browsing the tcllib CVS respository at [http://tcllib.cvs.sourceforge.net/tcllib/tcllib/modules/] provides many examples of actual manpage sources (.man files). For people who wish to add doctools functionality to their application, or package: * http://tcllib.sourceforge.net/doc/doctools.html -- Package to handle doctools input * http://tcllib.sourceforge.net/doc/doctoc.html ---- Ditto for doctoc input * http://tcllib.sourceforge.net/doc/docidx.html ---- Ditto for docidx input For people who wish to create support for additional output formats: * http://tcllib.sourceforge.net/doc/doctools_api.html - API between doctools package and formatters. * http://tcllib.sourceforge.net/doc/doctoc_api.html --- API between doctoc package and formatters. * http://tcllib.sourceforge.net/doc/docidx_api.html --- API between docidx package and formatters. Miscellanea: * http://tcllib.sourceforge.net/doc/changelog.html * http://tcllib.sourceforge.net/doc/cvs.html * http://tcllib.sourceforge.net/doc/mpexpand.html * http://tcllib.sourceforge.net/doc/docidx_intro.html * http://tcllib.sourceforge.net/doc/docidx_lang_intro.html * http://tcllib.sourceforge.net/doc/docidx_lang_cmdref.html * http://tcllib.sourceforge.net/doc/docidx_lang_faq.html * http://tcllib.sourceforge.net/doc/docidx_lang_syntax.html * http://tcllib.sourceforge.net/doc/docidx_plugin_apiref.html * http://tcllib.sourceforge.net/doc/doctoc_intro.html * http://tcllib.sourceforge.net/doc/doctoc_lang_intro.html * http://tcllib.sourceforge.net/doc/doctoc_lang_cmdref.html * http://tcllib.sourceforge.net/doc/doctoc_lang_faq.html * http://tcllib.sourceforge.net/doc/doctoc_lang_syntax.html * http://tcllib.sourceforge.net/doc/doctoc_plugin_apiref.html * http://tcllib.sourceforge.net/doc/doctools_intro.html * http://tcllib.sourceforge.net/doc/doctools_lang_intro.html * http://tcllib.sourceforge.net/doc/doctools_lang_cmdref.html * http://tcllib.sourceforge.net/doc/doctools_lang_faq.html * http://tcllib.sourceforge.net/doc/doctools_lang_syntax.html * http://tcllib.sourceforge.net/doc/doctools_plugin_apiref.html ---- The idea here is to include in tcllib a set of tools making it easier to write documentation. To that effort, a set of tools is included so that the tcllib author can write the documentation for his/her module in a format agnostic manner, and then convert the documentation into Unix man pages, HTML, and other formats. The basis of the implementation is the '''expander''' package in [textutil], a derivative of the [expand] macro processor. ---- Note: Discussion of documentation issues is encouraged, either here, on the [dtp] page, or the [user documentation project]. ---- Problem: There are zero examples of C API documentation using doctools, and the doctools documentation is ironically (annoyingly!) completely inadequate :-( [AK]: I do not know who has written the above, as there was no signing, however I do hope that this person is willing to also file concrete bugs, i.e. to give us [Tcllib Contribution & Feedback]. Concrete, i.e. not as vague as the above general complaint, but listing specific things which were sought, or expected in the documentation, and found missing. Regarding examples of C Api documentation, yes, there are zero. No one has apparently ever used it for that. No, not even me. I usually have no C API's around in need of documentation, only Tcl. ---- [LV] Perhaps one could pick a simple Tcl or Tk C function and rewrite its documentation in doctools format to provide a guideline for authors? Concrete examples, using the doctools format to '''correctly''' ''semantically'' mark up documentation, is one important addition for doctools. ---- [AM] Andreas Kupries described the procedure on c.l.t.: Steps: 1. Get yourself the [dtp] starkit from http://www.tcl.tk/starkits (Direct link: http://www.tcl.tk/starkits/dtp.kit) 2. Read the manpages in the tcllib distribution (files with an extension of .man). All of them are in the doctools manpage format and serve as examples. See for example the pool.man file in tcllib/struct. :) 3. Write your own manpage. 4. To convert your manpage into HTML, nroff, or plain text, run: dtp doc html your_manpage > your_manpage.html dtp doc nroff your_manpage > your_manpage.n dtp doc text your_manpage > your_manpage.txt Windows users may encounter problems in invocation. Refer to the [dtp] page. And here is a small example: [manpage_begin math::optimize n 1.0] [moddesc {Math}] [titledesc {Optimisation routines}] [description] [para] This package implements several optimisation algorithms: [list_begin bullet] [bullet] Minimize or maximize a function over a given interval [bullet] Solve a linear program (maximize a linear function subject to linear constraints) [list_end] [para] The package is fully implemented in Tcl. No particular attention has been paid to the accuracy of the calculations. Instead, the algorithms have been used in a straightforward manner. [para] This document describes the procedures and explains their usage. [section "PROCEDURES"] This package defines the following public procedures: [list_begin definitions] [call [cmd ::math::optimize::minimize] [arg begin] [arg end] [arg func] [arg maxerr]] Minimize the given (continuous) function by examining the values in the given interval. The procedure determines the values at both ends and in the centre of the interval and then constructs a new interval of 2/3 length that includes the minimum. No guarantee is made that the [emph global] minimum is found. [nl] The procedure returns the "x" value for which the function is minimal. [nl] [arg begin] - Start of the interval [nl] [arg end] - End of the interval [nl] [arg func] - Name of the function to be minimized (a procedure taking one argument). [nl] [arg maxerr] - Maximum relative error (defaults to 1.0e-4) [call [cmd ::math::optimize::maximize] [arg begin] [arg end] [arg func] [arg maxerr]] Maximize the given (continuous) function by examining the values in the given interval. The procedure determines the values at both ends and in the centre of the interval and then constructs a new interval of 1/2 length that includes the maximum. No guarantee is made that the [emph global] maximum is found. [nl] The procedure returns the "x" value for which the function is maximal. [nl] [arg begin] - Start of the interval [nl] [arg end] - End of the interval [nl] [arg func] - Name of the function to be maximized (a procedure taking one argument). [nl] [arg maxerr] - Maximum relative error (defaults to 1.0e-4) [call [cmd ::math::optimize::solveLinearProgram] [arg constraints] [arg objective]] Solve a [emph "linear program"] in standard form using a straightforward implementation of the Simplex algorithm. (In the explanation below: The linear program has N constraints and M variables). [nl] The procedure returns a list of M values, the values for which the objective function is maximal or a single keyword if the linear program is not feasible or unbounded (either "unfeasible" or "unbounded") [nl] [arg constraints] - Matrix of coefficients plus maximum values that implement the linear constraints. It is expected to be a list of N lists of M+1 numbers each, M coefficients and the maximum value. [nl] [arg objective] - The M coefficients of the objective function [list_end] [emph Notes:] [para] Several of the above procedures take the [emph names] of procedures as arguments. To avoid problems with the [emph visibility] of these procedures, the fully-qualified name of these procedures is determined inside the optimize routines. For the user this has only one consequence: the named procedure must be visible in the calling procedure. For instance: [example_begin] namespace eval ::mySpace { namespace export calcfunc proc calcfunc { x } { return $x } } # # Use a fully-qualified name # namespace eval ::myCalc { puts [lb]minimum ::myCalc::calcfunc $begin $end[rb] } # # Import the name # namespace eval ::myCalc { namespace import ::mySpace::calcfunc puts [lb]minimum calcfunc $begin $end[rb] } [example_end] [para] [section EXAMPLES] Let us take a few simple examples: [para] Determine the maximum of f(x) = x^3 exp(-3x), on the interval (0,10): [example_begin] proc efunc { x } { expr {[lb]$x*$x*$x * exp(-3.0*$x)[rb]} } puts "Maximum at: [lb]::math::optimize::maximum 0.0 10.0 efunc[rb]" [example_end] [para] The maximum allowed error determines the number of steps taken (with each step in the iteration the interval is reduced with a factor 1/2). Hence, a maximum error of 0.0001 is achieved in approximately 14 steps. [para] An example of a [emph "linear program"] is: [para] Optimise the expression 3x+2y, where: [example_begin] x >= 0 and y >= 0 (implicit constraints, part of the definition of linear programs) x + y <= 1 (constraints specific to the problem) 2x + 5y <= 10 [example_end] This problem can be solved as follows: [example_begin] set solution [lb]::math::optimize::solveLinearProgram \ { { 1.0 1.0 1.0 } { 2.0 5.0 10.0 } } \ { 3.0 2.0 }[rb] [example_end] Note, that a constraint like: [example_begin] x + y >= 1 [example_end] can be turned into standard form using: [example_begin] -x -y <= -1 [example_end] The theory of linear programming is the subject of many a text book and the Simplex algorithm that is implemented here is the most well-known method to solve this type of problems. [keywords math optimization minimum maximum "linear program"] [manpage_end] ---- At times, it has been suggested that the [Tcl] core documentation be converted into doctools format. One argument against this is that it would require the user to have a copy of dtp to generate the documentation pages. A suggested solution for this is that the authority be in doctools manpage format, but that the packaging step (that creates the distributed source tar and zip files) run dtp to generate the nroff or windows cfm formats at the time of distribution creation. The developer working from the CVS will need the [dtp] tool to generate nroff; but that seems less of a deal since that developer in all likelihood needs other tools such as autoconf, etc. [LV] Why not just include dtp or the scripts as a part of the core - then everything is there. ---- [RS] 2007-05-16: I obtained http://www.tcl.tk/starkits/dtp.kit , but with the above inline example saved to a file optimize.man, I get /Tcl $ tclkitsh-win32.upx.exe dtp.kit doc text optimize.man Processing optimize.man ... dtp.kit internal error Manpage error (nolistcmd), "para" : Dieser Befehl ist innerhalb einer Liste nicht erlaubt. while executing "::doctools::_format dt \ \[manpage_begin\ math::optimize\ n\ 1.0\]\n\ \[moddesc\ \ \ \{Math\}\]\n\ \[titledesc\ \{Optim isation\ routines\}\]\n\ \[desc..." ("eval" body line 1) invoked from within "eval [list ::doctools::_$cmd $name] $args" (procedure "::doctools::DoctoolsProc" line 15) invoked from within "dt format [tools::getfile $docfile]" Reporting the position of an error might be an optimization :^) I expected to have an example that works, and then experiment with it - but now I'd have to start debugging in a foreign language... [EMJ] 2007-05-16: Example fixed - the changes were: 46d46 < [para] 65d64 < [para] 81c79 < [para] --- > [list_end] ---- [LV] Anyone consider writing a little Tk app that would make writing doctools man pages easier? Something with the various sections, in the expected order, and with the ability to do some WYSIWIG (what you see is what is get) type format generation? ---- [jnc] I created a script that extracts doctools formatted comments from a source file. Thus, you can maintain your doctool information and source code in one file, for more info see it's page: [docextract]. ---- [APN] The [Ruff!] documentation generator can also generate output in doctools format. ---- '''[kpv] - 2010-07-09 23:45:19''' I couldn't get ''dtp'' to work but the following script did the trick: package require doctools ::doctools::new mydtp -format html puts [mydtp format [ReadAllText $manFilename]] ---- '''[AK] - 2010-07-10 22:19:40''' '''dtp''' is the heavyweight processor, not very use to use. '''dtplite''' is the easy to use little brother. In tcllib under apps/, ---- !!!!!! %| [Category Package], subset [Tcllib] | [Category Documentation] | [Category Word and Text Processing] |% !!!!!!