Poorly written documentation, indeed no documentation at all, can turn completely unusable the best programs or pawindowsckages. In what file format should documentation be written: man, chm, html, xml, pdf or something else? ---- 0. Of course, the tcl man pages are availabe in *roff man page macro format as a part of the source distribution. 1. [Andreas Kupries] and others have been working away at the [tcllib] [doctools] and [dtp] code to make it easier to write one [tcl] reference page that can then be translated into a variety of formats. 2. [Joe English] and others have worked on TMML for some time, as an alternative format for marking up Tcl doc. [TMML] is an [xml] [dtd] for tcl doc. 3. http://www.bodenstab.org/ houses a TeX marked set of pocket reference guides for tcl and a variety of extensions. 4. [HTML] versions of extension docs are availabe for download from [ActiveState] at the same place you get the binary [ActiveTcl] distribution. 5. [JCW] has [starkit]'s of [tclkit DOK commands] for tcl/tk and a few other items available at http://mini.net/sdarchive/ . Building these depends on having HTML versions of the original reference pages available. 6. One of the community members of the [tcldocs] mailing list makes the reference pages available in .chm (for Windows) and [PDF] - last update was last May, with 8.4.2 . ---- [LV] For presentation of scripting reference material for extensions and at least simple application references, if to be used on [Unix], documentation in "man" format needs to be able to be generated. For presentation of more detailed application doc, I prefer [html] over [PDF] simply because it is generally easier for me to read the docs that way. Another potentially useful format is the [wikit] format; [starkit]s have been making use of a wikit for help information for some time. As of 24Nov2003'', Dr. Detlef Groth has presented a help viewer based on Tkhtml's widget and the "hv.tcl" demo code to the starkit mailing list. This starkit is simply a wrap-up of a directory full of HTML files, presented to the user with table of contents and index pages - much like the Windows help viewer. As an example kit, he presents http://goblet.molgen.mpg.de/dgHelpBrowser.kit with 3Mb (compressed) of docs for Tcl/Tk and many extensions. However, the Tcl [doctools] format is pretty good for preparation purposes. ---- About documentation tools: editors, screenshot utilities, i18n... The simpler the better, for editors. [kroc] According to me, a perfect doc generator would be: * platform-independent for both editing and displaying contents. * very simple to use. * follow predefined formatting rules. * able to grab window or tk widget to include screenshots. Something based on [expand] maybe? ---- About content itself: What is desirable to do and what to avoid to write a good user manual? ---- Please give here your opinion, your own choices and why. ---- [RS]: Like many of us, I document less than I code. Luckily, I rarely have to deploy to nonexpert end-users. But even running my own apps after some time, I like concise online help best, e.g., [htext], and sticking to accepted standards, like having the Exit command at the bottom of the File menu... But if it has to be documentation that can also be printed out, I prefer [HTML] as the most portable, even to [PocketPC], editable, simple, yet decent in printout. Oh, and especially pages at [the Tcl'ers Wiki] - most easily reached from any online box :)! ---- [kroc] As I've found nothing ''really'' adapted for it, I planned to do it myself. Purpose: Create a very simple editor for end-users manuals (let's us call it Tkdoc). This editor itself will use a tcl-like syntax that will be parsed on output to produce html. The parsing will be done according to predefined macros (see below). Goal of Tkdoc: Make writing end-users' manuals easier and quicker. Make manuals easier to translate, to update and to correct. Finally give a kind of uniformity for look and feel of tcl and tcl apps manuals. Functions envisaged: Very simple GUI with an edit window (notebook based). Menu with standard file operations, "parsing" button, "preview" button and "embed image" button. Tkdoc file format: A single macro+text file with screenshots, images, data at the end. At the point, predefined macros could be: * [title ''string''] (Document title) * [sec ''title''] (Create a new level 1 chapter and its entry "title" in index. The section content (text, images and subsections) will end at the first following [sec]) * [sub ''title''] (Create a new level 2 chapter and its entry "title" in index. The subsection content (text and images) will end at the first following [sub] or [sec]) * [img ''name''] (Insert a image stored after [end] with "name"). * [tag ''name''] (insert a link target "name"). * [link ''target''] (insert a hypertext link to "target", target can be a section or a tag name.) * [index] (insert an hypertext index relating to existing sections and sub-sections). * [i ''string''] (output italic "string"). * [b ''string''] (output bold "string"). * [u ''string''] (output underscore "string"). * [end] (end of the manual). Please feel free to add your own ideas before I start it, so the result could be as good as expected for everybody. ---- [Lars H]: I like the command substitution like syntax, but it brings a couple of questions to mind. Is this what [expand] uses? Are there any other names being used for the same idea? (I've often felt the need for an introduction that explains the various formats and the communities in which they are used, but I haven't found any.) What projects currently have documentation marked up in that way? A nice thing with using a Tcl-like syntax for markup is that you don't have to worry about making it so crude that some things are impossible (or nearly impossible) to write -- the Wiki syntax has some dusty corners in that regard -- because the Tcl syntax has already been tried in actual programming and has been shown to make do for almost everything. Also, you might want to consider supporting also backslash substitution, since a simple \uXXXX is a reliable way of encoding exotic characters (in people's names and such) while keeping your source 7-bit clean. As for the actual macros suggested, stylistic variations such as italic, bold, and underline (underscore is a character) are probably a mistake. What would be needed is higher level markup, such as '''emphasis''' (which would probably be rendered as italic) and '''computer text''' (known as "typewriter" in the TeX world, probably best rendered as monowidth text where that is an option). The reason for this is that different output formats have very different capabilities. Printed text/PS/PDF handle bold, italic, monowidth, and many other things beautifully, but underlining is usually a mess. Character-based terminals may OTOH handle underlining well, but fail miserably with italic. By designing the markup to convey what you mean rather than what you expect to see in your favourite output format, the documentation becomes more likely to render well into a broad variety of output formats. The [[index]] thingie also looks a bit wrong; it seems you are rather thinking about a table of contents than about an index. There's nothing wrong with a [[tableofcontents]], but one should also think about indexing, because that is a very valuable kind of markup. The meaning of * [[index ''string'']] should rather be to expand to nothing, but also make a note that at this particular position in the document there is useful information about the ''string''. For large projects whose documentation is split on several files, an index with cross-references covering the entire project is an efficient way of finding the information one is looking for. ---- [LV] What is the difference between a level 1 and 2 chapter? Are you meaning the difference between a chapter title and a section title? link says that it's argument ''can be a section'' - what does that mean? I myself would rather see use of the italic/bold/underscore type things minimized and instead have semantic tags. That would make things easier to to translate to xml. Are the macros mentioned above the doctools names, the [TMML] names, or something else? ---- [kroc] ''26 May 2003'' It's something else and, once again, it would be better to use doctools existing tags describe here : http://tcllib.sourceforge.net/doc/doctools_fmt.html and evaluate what must be added to write a descent end-user manual. ---- [Michael Schlenker] Tkdoc looks very much like [doctools], but probably with a slightly different focus. Could those efforts be merged? There is not yet a GUI editor for doctools would be a good way to start. [AK]: I would welcome a GUI editor for doctools. This could start out separately, but ultimatively this should be made a subcommand of [dtp] (IMHO). [AK]: Regarding Tkdoc, it is quite similar, and thus a bit of a redundant effort. From my POV we can use parts of doctools (call, arg, method, option, ...) to describe a procedure and place that as comments in the code, either before a procedure, or inside. Then we just need a tool to extract the information and weave it together into a complete manpage. See also [autodoc] for such a tool, except that it uses it own markup for the embedded documentation (it predates doctools by some years). [kroc]: All this is more adapted to tcl developers' manpages than real end-users' manuals Tkdoc is suppose to produce. ---- [ro] It's a waste of time to create yet another format. Instead of documenting, you will be coding (a common pitfall). Just start documenting now, in whatever you know (roff, html, LaTeX...). You can always hack it into another format later. Docs now is better than perfect docs later. ---- [AK] Note that [doctools] as base format makes conversion to Latex, nroff, html easier. IOW, not hacking into a different format later, but automatic conversion without hassle. ---- [LV] Over the years, people have suggested various [SGML] or [XML]/[DTD] solutions to documentation. The problem with many/most/all (??) of these has been that while getting the words of the documentation is awkward enough, then the effort of adding ''appropriate'' formatting results in a loss of focus. If one is formatted as they write, as much time is spent worrying about the formatting as is about the content. If one attempts to format afterwards, the resulting text becomes difficult to edit. [HTML], Tex, nroff and PostScript are likewise an increasingly difficult series of formatting languages. Some would argue that MS Word resolves this - the text can be input directly, editing can, in general, remain focused on content. However, the problem with Word is that it may work well for Windows platform users, but is not easily generated and maintained on other platforms. What do other language communities use? Perl has their '''Plain Old Documentation" format (aka POD). ---- [NEM] ''25May2003'': I'm personally quite fond of LaTeX these days for writing documentation (and dissertations). I tend to just write the absolute minimum of formatting, just defining chapters and sections. Generally, LaTeX will then produce a pretty good quality output from this bare minimum. It's then a relatively quick (and quite fun!) job to add in specific formatting commands where needed. Also, importing a few packages here and there can make a really professional result. The big advantage that LaTeX has for me (over things like Word) is that the authors of it obviously knew a lot more than I ever will about professional typesetting. The results are generally excellent, and take account of so many things I wouldn't think of (like the fact that humans find reading lines of greater than 66 characters difficult). LaTeX also has the advantage that you can define new commands and environments to suit the current task (much like Tcl!). The basic idea is to leave all formatting commands out of a document, and just define the structure. Works well. [RWT] ''24Nov2003'': I also have just completed a set of online documentation for an application. It consisted of a technical manual and a users guide, instead of simply man pages. I also needed images (screen shots) in the users guide, and the technical manual is rife with equations. LaTeX turned out to be the best input format. [doctools] looked good, but didn't have images. For printable versions, I used pdflatex to get PDF files with TeX's famous beauty. For online versions, I used latex2html to generate HTML with table of contents, list of figures, internal reference links, and a navigation panel on each page. From the application help menu, I launch a web browser or (if that fails) the "hv.tcl" hypertext viewer that comes with Tkhtml. ---- [kroc]: As [AK] wrote above, Tkdoc also could be a simple [dtp] frontend. Of course, I'll do that with pleasure instead of starting from scratch. But in this case, I'll need to add/remove some doctools tags (like image support, restricted nested levels, etc..). Moreover, [AK] more or less planned to update doctools tags. Maybe we could define here what should be kept, add or remove for Tkdoc particular purpose? ---- [LV] What did you have in mind that would need to be removed from doctools? ---- [kroc] I don't really need to remove something to doctools. In fact, it will be enough for Tkdoc purpose to use only a limited set of doctools tags. The less choices the writer will have, the quicker the manual will be written. I think the list I wrote above is enough to write a comprehensive end-user manual. We also can consider a full doctools support for tcl-aware user manual. ---- [kroc] ''27 May 2003'': '''What should be present in an effective help system''' ''(a beginner point of view)''. Help have to be found easily. Here we can list three distincts kinds of help: * Online help - for users who wants to know possibilities before downloading something. * Command line or contextual help - for rapid access during use. * Printable detailed help - for a complete reference manual. '''Online help''' - One or few html pages to explain: * The application/package/library purpose. * How it can be installed and, if needed, what is required. * Features summary. * Samples of use and results. '''Command line help''' (pure Tcl only) - at least the two following: * Return how to access help for a general wrong call. * Return a good semantic command sample for incorrect args/subcommands use. '''Contextual help''' (Tk only) - at least one of the three following: * Help index menu entry with optionnal bind on F1 key. * Balloon help. * True contextual help binds on focused widget with F1 key. '''Printable detailed help''' - should be shipped in application/package/library archive, if possible using a platform standard help file format (manpage for unix, html or chm for windows, etc..). It should be the most detailed part of the help system. Globally, it could be the same content than online help, but with detailled features, subcommands, switches and arguments explained. '''Help content''', some simple rules: * It's more important to explain ''what can be done with'' than ''how you've done it''. * Samples are easiest to understand than detailed explanations. * Always try to use the shortest sentences with simplest words. It's easier to read, especially for foreigners. ---- One recent (July 2003) issue that came up was the fact that Tcl has established the precedence of documenting every command of tcl as a seperate man page, where as [perl], [python], [ksh], etc. have taken other approaches - in fact, tcl appears to be the only commonly installed language which has taken this approach. Despite this, perl at least comes with much more documentation than does tcl. python comes with tutorials, etc. So the general impression by someone new to tcl is that there is too little doc spread across too many pages. Subsequent discussions pointed out that this was not entirely the case. Perl, for instance, has hundreds of man pages in section 3 as well as over 100 man pages in section 1! Amazingly enough, the section 3 man pages are mostly packages, while the section 1 man pages are FAQs, etc. The perl language itself appears to be spread across a number of ''chapter'' files. ---- [LES] 21 Aug, 2003 - Wouldn't '''txt2tags''' [http://txt2tags.sourceforge.net] be an excellent tool to help develop documentation in many formats? 24 Nov, 2003: ...or aurigadoc [http://aurigadoc.sourceforge.net] Anyway, I see a lot of discussion about the format and nothing about the content. I think Tcl's documentation is mostly confusing, too economical and/or inadequate to newcomers. It really could use some rewriting, IMO. ---- [Category Documentation]