Ruff!

Difference between version 55 and 56 - Previous - Next
Ruff! is a documentation generation system for programs written in the Tcl programming language.

[APN] 2021-01-28 Ruff! 1.1.0 released. V1.1 adds a searchable index. See https://iocp.magicsplat.com/iocp_docindex.html%|%this%|% for an example.

Ruff! (Runtime function formatter) is a documentation generation system for programs written in the Tcl programming language. Ruff! uses runtime introspection in conjunction with comment analysis to generate reference manuals for Tcl programs. For more on the benefits, see
https://ruff.magicsplat.com/#Why_Ruff_%|%Why Ruff!%|%.

Downloads and release notes at https://sourceforge.net/projects/magicsplat/files/ruff/.

Documentation is at https://ruff.magicsplat.com.

Source repository at https://github.com/apnadkarni/ruff.

**Examples**

https://ruff.magicsplat.com%|%Ruff!%|%,
http://www.cawt.tcl3d.org/download/CawtReference.html%|%CAWT%|%,
https://tcl-promise.magicsplat.com/%|%tcl-promise%|%,
https://iocp.magicsplat.com/%|%iocp%|%,
http://woof.sourceforge.net/woof-ug-0.5/html/_woof/woof_manual.html%|%Woof!%|% and
https://tcl-vix.magicsplat.com/%|%tcl-vix%|%.


**Historical**

(comments on older releases that shipped with Woof!)

----
[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.

----
'''[aplsimple] - 2020-02-29 17:23:58'''

Perhaps, these remarks would be helpful:

   * The `_ruff_preamble` variable may contain tables of definitions. It would be nice to have <code></code> tags for the left column of terms, like in the comments of procedure/method - just for a consistency of view. [APN] No, because not all tables are assumed to be definitions. The ones within procedures are distinguished as such because of their placement at the top of the procedure.

   * Ruff! makes NS.html#link for a document's internal links. Perhaps, a simple #link would be better (shorter in any case) because if, for some reasons, you rename NS.html to NS_guide.html, those links don't work. [APN] Yes. Perhaps in a future release.

   * "See also:" can include only links to procedures/methods and bracketed links. Seemingly, direct WWW link and <WWW link> don't work. [APN] Done. Was meant only for program element references. Now changed in repository to permit Markdown links.

   * "Show source" adds a new line under a proc, which would be good if there weren't a new line in the proc by itself (two blank lines are created by Ruff! in this case) [APN] I think this only happens if there is in fact a blank line at the end of the original procedure. In which case, it is reflected in the Show source.

   * It would be nice to have a link to Ruff! site in the bottom message "Document generated by Ruff!". [APN]. Good idea. Done.

   * ...and to have some options of customizing, e.g. for colors and width ratio of TOC/description. When the generated documents are injected into an external site, it's desirable to have them a bit consistent with the site. [APN] There is now a -stylesheets option. Note the YUI CSS used for gridding is still included but the Ruff-specific pieces can be overridden by specifying new stylesheets. Be aware my CSS is structurally horrible if you clone the default ruff css :-)

   * ...and to emphasize sections' titles (for more readability), e.g. with <br><h2 class='ruff'> and <br><h4 class='ruffproc'>. [APN] May be. But I've gone through so many iterations in fonts, it is now what it is. You can use the stylesheets to change this though.

   * ... and to highlight a Tcl syntax in "Show source", at least basic - keywords and comments (strings perhaps) [APN] Would be nice but more work than I can manage now I'm afraid. I'll take a look at your mulster reference later when I again have some time for Ruff.

The last four proposals are seen in https://aplsimple.github.io/en/tcl/trimmer/trimmer.html%|%trimmer.html%|% tuned for this reason by https://aplsimple.github.io/en/tcl/mulster/index.html%|%mulster utility%|% that can be also used for fine tuning of other generated documents, e.g. made by [mkdoc::mkdoc], to satisfy different tastes of users.

[APN] Yes, those remarks are helpful, thanks :-) Just awaiting the time I work on Ruff next.

2021-01-28 Released 1.1.0 but forgot about the above requests :-(. Copied them to the ruff ticket tracker so as to not forget next time.

----
'''[apIsimple] - 2020-09-27 03:57:05'''

Would it be useful if <img...> tags will be not modified by [Ruff!]? Now they are converted to be readable as is (with &quot; &gt; etc.) so that not working in a resulting Reference page.
----
'''[RZ] - 2021-02-08 14:58:28'''

Currently only oo::class classes and no metaclasses are recognized in
`proc ruff::private::extract_procs_and_classes` because of line :

`set class_names [[info class instances ::oo::class $pattern]]`

May be add an option -metaclasses and do an "[[info class instances $metclass ..]]".

<<categories>> Documentation