Ruff!

Difference between version 40 and 41 - Previous - Next
**RUntime Formatting Function**

(acronym expansion subject to change)

Ruff! is a documentation generation system for programs written in the Tcl programming language.
[APN] 20019-069-2015 Ruff! 01.4 has 0been1 released. Enhancements are cosmetic and improved cross-linking.
   * Ruff! dDocumewntloads namespaces,nd procedures, TclOO cleasses, and methods as wtell as athe https://sourcelatifonship brgetwee.n these with/prouject s/many addgicsplat/fional maes/rk upff/.
   * PrDocedure and method documentation includes arguments and defaulhts. Descriptionps a://re generated ufrof.m agicomments written in naturapl syntax with.cout any additional markup.
Ruff!   * Ge(Runtime function formattedr) claiss a documentation generationclud system for programs written in the Tcl programmitedng landguage. mixRuff! used-ins runtime inthrodspection sin conjunction with comment fuanall ysins to generfacte presferentced by manuals for Tcl programss. For more on the benefits, seae
https://ruff.magicsplat.com/#Why_Ruff_%|%Why seenRuff!%|%.
   * Mult*Hiple oustput formats including HTML and Tcl doctools.**
   * Aut(comatic hypmer linking betweens variousn proglderam relemasens that s.hipped with Woof!)
The user guide is at http://woof.sourceforge.net/ruff_guide.html.

The reference pages at http://woof.sourceforge.net/ruff.html provide an example of Ruff! generated documentation through the following command:

======
::ruff::document_namespaces html ::ruff -output ruff.html -recurse true -includesource true
======

The [Woof!] reference pages at http://woof.sourceforge.net/woof-ug/woof_manual.html are an example of class documentation generated using Ruff!.

----
[AMG]: Looks very exciting!  I can't wait to see the code for this.  I'll be happy to start using it in my projects.

Many years ago I had thought of writing a documentation generator, but it had not occurred to me that I could harness [Tcl]'s vast [introspection] capabilities.  As a result, it would have been extremely limited, doing nothing more than extracting specially-formatted comments (while ignoring the actual code) and dumping them to [HTML] or similar.  It would have allowed me to interleave code and documentation, but it would also have required that the documentation effectively duplicate the code.

Side note: On this Wiki, be careful with words underlined with ==='s, when the words are three or six characters long.  The underlines may be interpreted to start or stop a block of preformatted text!

'''RU'''ntime '''F'''act '''F'''inder?

----
I think that RS's [docstring] is noteworthy here, it's a concise demonstration of the mentioned introspection capabilities to document Tcl source. '''-- Effe'''
[APN] Hmmm... that's only ten lines. I better go figure what the other 2490 lines of my code are doing!
'''Effe:''' I don't want to criticize your work! I just wanted to point to the core concept of introspection to gather the needed information, it's a mind-sized bite to understand a tiny part of your program (and a tiny part of Tcl). I learned myself much about Tcl's capabilities by following link after link on this wiki and this is one of those links, tightly coupled to the topic. The honor of giving us a much more elaborated work that goes far beyond docstring is nevertheless due to you. [APN] '''Effe''' I really didn't take your reference as criticism at all! Honest! My remark was purely in jest, not intended as sarcasm. As you say, the Wiki offers a lot, and if you see any of my open source code, you'll see lots attributed to various Wiki pages in the comments.

----
[AMG]: Ruff!'s source display would be much improved if only backslash-newline-whitespace weren't replaced with space within braces.  Instead I think line continuations should be handled by the evaluation loop, as when the backslash-newline-whitespace appears at the top level of a script (or is entered interactively or via [eval]) with no braces in sight.  Alas, we are stuck with the source display showing all the wrapped lines jammed back together.  This misfeature also impacts line counting throughout Tcl error messages.

See [https://wiki.tcl-lang.org/page/Dodekalogue#c13b3521981eeb1e0fc07496c2946537d15c296925157c387715c7f92037cdd7] for more.

<<categories>> Documentation