Re: FLI question

Friedrich,

I feel your pain.  To the extent that I offer the following fishing
equipment:  a self-documenting function for packages.  It sweeps the entire
package for functions, classes, methods, variables and structures and
prints out all of them in PDF (unexported ones too, optionally), including
any documentation on the objects.

The code is not pretty but workmanlike:  it contains some very (ugly)
LW-specific stuff.  I offer it as a way of determining what functions are
there so you can at least ask Xanalys for examples of their use if you
can't figure that out from the arglists, which is often the case.

The system requires the cl-pdf system, which you can get from
marc.battyani@fractalconcept.com.  Examples of usage are at the end of the
file - you would want
(do-document 'fli "fli-doc.pdf")

The output document, needless to say, is of limited usefulness since it
contains no examples.  But it is of interest in that it is much more
complete (and sometimes more correct w/r/t arglists) and the text sometimes
differs from the documentation in the manual.

These functions would be of use to someone wishing to document their
system.

davef, if you're listening - here is a possible skeleton for your new CAPI
manual (as opposed to your closet?).

Raymond Laning

(See attached file: funcmap.lisp)

Re: FLI question

In a similar vein, I have a CAPI based package browser.  You can browse all packages and
their interned symbols.

http://www.cadvision.com/humeniuw/package-browser.lisp

The file is also attached.  There might be a few problems on LWL, it was written under
LWW.  Double click on a package symbol and it will create an lispworks-tools::inspector to
inspect the symbol.

Wade

----- Original Message -----
From: "Raymond C Laning" <rclaning@raytheon.com>
To: <lisp-hug@xanalys.com>
Sent: Friday, September 27, 2002 3:01 PM
Subject: Re: FLI question


|
| Friedrich,
|
| I feel your pain.  To the extent that I offer the following fishing
| equipment:  a self-documenting function for packages.  It sweeps the entire
| package for functions, classes, methods, variables and structures and
| prints out all of them in PDF (unexported ones too, optionally), including
| any documentation on the objects.
|
| The code is not pretty but workmanlike:  it contains some very (ugly)
| LW-specific stuff.  I offer it as a way of determining what functions are
| there so you can at least ask Xanalys for examples of their use if you
| can't figure that out from the arglists, which is often the case.
|
| The system requires the cl-pdf system, which you can get from
| marc.battyani@fractalconcept.com.  Examples of usage are at the end of the
| file - you would want
| (do-document 'fli "fli-doc.pdf")
|
| The output document, needless to say, is of limited usefulness since it
| contains no examples.  But it is of interest in that it is much more
| complete (and sometimes more correct w/r/t arglists) and the text sometimes
| differs from the documentation in the manual.
|
| These functions would be of use to someone wishing to document their
| system.
|
| davef, if you're listening - here is a possible skeleton for your new CAPI
| manual (as opposed to your closet?).
|
| Raymond Laning
|
| (See attached file: funcmap.lisp)
|

Re: FLI question

> The output document, needless to say, is of limited usefulness since it
> contains no examples.  But it is of interest in that it is much more
> complete (and sometimes more correct w/r/t arglists) and the text sometimes
> differs from the documentation in the manual.
Well thanks I'll give it a try...

Another possibility, would be if we just show some of our findings and
maybe it would be an idea for us to add documentation strings?



Regards
Friedrich

Re: FLI question

"Wade Humeniuk" <whumeniu@telus.net> writes:

> In a similar vein, I have a CAPI based package browser.  You can browse all packages and
> their interned symbols.
> 
> http://www.cadvision.com/humeniuw/package-browser.lisp
Thanks too to you, I'll check it I guess even today ;-)

Regards
Friedrich

Re: FLI question

"Wade Humeniuk" <whumeniu@telus.net> writes:

> In a similar vein, I have a CAPI based package browser.  You can browse all packages and
> their interned symbols.
> 
> http://www.cadvision.com/humeniuw/package-browser.lisp
> 
> The file is also attached.  There might be a few problems on LWL, it was written under
> LWW.  
It worked nearly out-of-the-box the only change I had to to was in 
(font :initform (gp:gf nil #+win32"Courier New" #-win32"Courier"
:medium :roman 12)))

I adpoted the size and instead of :normal :medium had to be used. I
guess it will work this way too on Windows.

Well I hope it's ok to post this....

Regards
Friedrich

Re: FLI question

Unable to parse email body. Email id is 598

Re: FLI question

davef@xanalys.com writes:

> 
> The doc strings in the image, where they exist, are generally much
> shorter than the descriptions in the reference manual, and are not
> adequate as descriptions. One practical problem in programmatically
> generating the reference pages from the Lisp image, even with
> substantial doc strings, is that there will be no formatting of the
> description text.
Sorry what prevents Xanalys to use something like doxygen for the
documentation strings? This things could be extracted and printed in
whatever form you like. For the beginning it would be good to just
have plain text and HTML for the Documentation. Of course you do not
have to use the doxyfile syntaxs for it, but something simular to
htmlgen or laml would do the job quite fine. this is e.g a comment
about a function in the docs:

activate-pane
Function
Summary

The activate-pane function gives the focus to a pane and brings the window containing it to the front.
Syntax

activate-pane pane
Description

This brings the window containing pane to the front, and gives the focus to the pane (or a sensible alternative inside the same interface if that pane cannot accept the focus).
Example

This example demonstrates how to swap the focus from one window to another.

(setq text-input-pane

      (capi:contain (make-instance 

                     'capi:text-input-pane)))

(setq button

      (capi:contain (make-instance

                     'capi:push-button

                     :text "Press Me")))

(capi:activate-pane text-input-pane) (capi:activate-pane button)
See also

hide-interface

So one could write (ad hoc notation
(defun activate-pane (pane)
        "The activate-pane function gives the focus to a pane and
brings the window containing it to the front.

Long descriptin....
(:example (setq text-input-pane ....))

(:see-also .....))


The first sentences will be the short description and the long
description is all what follows the first sentence
You could add things like 
(:param ....) 
        (:bold ....
etc 

And your tools automatically gen generate whatever they like from
it. I can't see why this shouldn't work in Lisp.
> 
> In general, please don't use internal symbols and undocumented
> arguments without checking with lisp-support first. You are welcome to
> ask, of course.
Well I do think that some solutions posted here rely on internal
functions. Therefor I would think they should not be internal and if
they are not external the should be documented at least with a
Documentation string IMHO. You won't update your documentation all too
often, but if you write code it should be mandatory to add a
documentaton string. And I would even go further and try to write
those things away that they can be extracted and put into the
Documentation as above. It's not terrible much more work, it's a small
overhead which will save time in the end for you and your customers.

Regards
Friedrich