Re: Some questions

[Günter Milde <milde@xxxxxxxxxxxxxxxxxxxx>]

On Sat, Jun 14, 2003 at 08:10:13PM +0000, Joerg Sommer wrote:
> 
> is !if (foo) faster then if (foo != 0) or why exists this version of
> negation?

Yes, with foo != 0, 2 items need to be pushed on the stack (i.e. it is the
same as i += 3 vs. i = i+3).

 
> What does ".[var]"? (var is a variable) I found it in site.sl
> custom_variable().

It seems to be the equivalent to "variable var" (SLang has a
undocumented/sparely documented) RPN syntax variant).

> And what's with %!%+ and %!%-? Are this active comments? 

These special comments enclose an extractable documentation in tm-language
There is a suite of c programs to extract the documentation and translate it
to txt, html and/or latex formats.

> Where can I read more about them?

AFAIK, only in the sources.

> How to use them? Is there a function in jed, that helps
> creating them?

Again, a look into the sources (mainly site.sl) helps a lot.

tmmode.sl is a mode designed for the documentation language.

The attached file tmtools.sl (originally by Dino Sangoi) provides a function
that sets up a template for a function-doc in tm.

I would like to see a slang-script that would do the work of the
c-programs+Makefile and produce a libfuns.txt file from all this doc-blocks
in a directory, so contributed modes could give online-help.

Günter

-- 
Milde at ife.et.tu-dresden.de

%-------- tmtools.sl ----------------------------------
% Some semi-automatic tm style documentation generation.
%
% By Dino Leonardo Sangoi.
% modified by G Milde
%
% If you have my cext.sl, uncomment the next line and
% exchange c_top_of_function with new_top_of_function.
%
%require("cext");
%
% _traceback=1;
% _debug_info=1;
require("comments");

% find out whether we are in C or Slang mode
static variable WhatMode;
(WhatMode, ) = what_mode;

%!%+
%\function{tm_make_doc}
%\synopsis{Create documentation comments for a function}
%\usage{tm_make_doc()}
%\description
%   When this function is called from inside a C or SLang function, it
%   creates right above the function itself a set of commented lines
%   formatted as expected by tm2txt. Some data will be generated
%   automagically from the function definition and comments.
%\notes
%   Bind to a key.
%\seealso{tm_set_attr}
%!%-
public define tm_make_doc()
{
   variable name, name_with_args;
   variable c = get_comment_info();
   variable cb, cm, ce;
   
   if (c == NULL)
     return;
   
   % Uhm, the word should be defined by mode, I guess (but currently is not)
   % More accurate: it should be mode specific: when I edit a latin1 encoded
   % text after calling tm_make_doc, I get trouble with Umlauts. Therefore:
   variable word_chars = "A-Za-z0-9_";
   cb = strtrim(c.cbeg);
   ce = strtrim(c.cend);
   cm = strtrim(c.cbeg);
   if (c.cend != "") {
      if (strlen(cm) > 1)
	cm = " " + cm[[1:]];
   }
   
   % new_top_of_function();
   % find the top of function
   down_1(); % dont't jump to last fun, if in first line of function
   c_top_of_function(); % goes to first opening {
   !if (re_bsearch("[]\\)\\}\\;\\>\\\"]"))
     break;
   if (what_char != ')')
     return;
   right(1); % leave on Stack
   push_mark();
   go_left(());  % get from stack
   call("goto_match");
   bskip_chars(" \t\n");
   name = bget_word(word_chars);
   bol();
   name_with_args = bufsubstr(); 
   % may contain static, local, global, and define keywords:
   if(WhatMode == "SLang")
     {
	(name_with_args, ) =  strreplace(name_with_args, "static ", "", 1);
	(name_with_args, ) =  strreplace(name_with_args, "local ", "", 1);
	(name_with_args, ) =  strreplace(name_with_args, "public ", "", 1);
	% (name_with_args, ) =  strreplace(name_with_args, "define ", "Void ", 1);
	% use this if you don't like to insert Void by default
	(name_with_args, ) =  strreplace(name_with_args, "define ", "", 1);
	% optional arguments
	(name_with_args, ) =  strreplace(name_with_args, "() % ", "", 1);
     }
	
%    TODO:
%    % Check existing comments
%    push_mark();
%    do
%      {go_up_1; bol;}
%    while(looking_at("%"));
% %   exchange_point_and_mark();
%    message(bufsubstr);
    
   % Grrr, Wy C uses " *%+" while slang uses "%!%+" ???
   if (cb == "%")
     insert (cb + "!%+\n");
   else
     insert (cb + "%+\n");
   vinsert("%s\\function{%s}\n", cm, name);
   insert (cm + "\\synopsis{}\n");
   % TODO: check for a return value
   vinsert("%s\\usage{ %s}\n", cm, name_with_args);
   insert (cm + "\\description\n");
   insert (cm + "   \n");
   insert (cm + "\\example\n");
   insert (cm + "#v+\n");
   insert (cm + "   \n");
   insert (cm + "#v-\n");
   insert (cm + "\\notes\n");
   insert (cm + "   \n");
   insert (cm + "\\seealso{}\n"); % comma separated list
   if (cm == "%")
     insert (cm + "!%-\n");
   else
     insert (cm + "%-\n");
   if (ce != "")
     insert(" "+ce+"\n");
}

%!%+
%\function{tm_set_attr}
%\synopsis{Add attribute around a word in tm format}
%\usage{tm_set_attr(String_Type attr)}
%\description
%   This function adds '\\attr{' and '}' around the word at the point.
%   (attr is replaced with the actual parameter).
%\notes
%   Bind this to a key. For example, I bind "tm_set_attr(\"var\")" to "^Wv".
%\seealso{tm_make_doc}
%!%-
public define tm_set_attr(attr)
{
   % As abobe...
   variable old_word = get_word_chars ();
   define_word("A-Za-z0-9_");
   bskip_word_chars();
   vinsert("\\%s{", attr);
   skip_word_chars();
   insert("}");
   define_word(old_word);
}

provide("tmtools");