Albert FAQ

  1. What do I need to run Albert on my system?

    Albert can manage mostly with a lisp-environment, but to process the generated Docbook files you need a docbook-environment. For a debian-system you will probably need jade, docbook and docbook-dsssl.

  2. How can I tell Albert where I installed the xml-programs?

    This was more relevant in v0.4.6. If you're debugging stuff and turned on ("albert" "use-temporary-files"), you might need to specify location of xml-parser. In case you just ran 'make' or installed albert-programs outside /usr/bin/ you might need to help albert a bit by specifying where the programs are:

      (setf apispec:*xml2sexp-prog* "/home/stig/Projects/albert/expat/alb_xml2sexp")
    

    You don't need to worry about the xml2esis program, it isn't used and xml2sexp is faster. The xml-files are there for debugging, safety and other tools, but if you just want to go straight from lisp-code to docbook you can set the albert-setting ("albert" "use-temporary-files") to NIL and the xml-programs will not be used and no temporary files will be created.

  3. Albert/lisp2csf whines about CL-USER, why?

    Currently Albert doesn't know about the CL-USER package, but the default handling will be just fine. Don't worry.

  4. Albert seems unable to parse my lisp-code, why?

    Albert uses READ to read the lisp-code, so at the very least your code should be READable. Albert may also stumble on references to symbols in undefined packages, because the lisp-reader stumbles on it. When compiling your lisp-program, you might do a lot of twisted and wacky stuff, and that is great (it's lisp after all). But Albert has no interpreter and does not process macros so it will not even try to do the twisted and wacky stuff, and as such might miss some good parts.

  5. How can I tell Albert to ignore some calls?

    An example:

    (dolist (i '(+ - * / = < <= > >= /=
    	     dotimes cons list push pushnew string dolist assoc))
      (pushnew i lisp2csf:*ignorable-calls*))
    

    This will ensure that these functions do not show up in the "Calls" or "Called by" documentation.

  6. How can I tweak the navigation header and footer?

    You can check the albert.css for how to configure the look of it, to turn on and off parts of the naigation header or footer, check the albert.dsl file and the %albert-navigation settings in it. The navigation has changed/been improved from v0.4.5 to v0.4.6.

  7. How can I make the navigation icons work?

    The simplest way is to copy the icons/ directory from the data/ directory in the Albert distribution (/usr/share/albert/data/ on Debian) to the documentation output-dir (like you copy albert.css file there). If you need a separate path to the icons, please check albert.dsl where you can set %albert-navigation-iconpath% to the path where your icons are.

  8. How can I tweak the look of the documents?

    Typically the simplest is to tweak the albert.css file where most of the look'n feel can be tweaked. Some of the more structural HTML-issues can be tweaked in albert.dsl.

  9. How can I make headers for exported and non-exported methods differ?

    Check albert.css for font.exported and font.not-exported. These are typically commented out by default.

  10. Jade is really noisy about the generated file, is that normal?

    Yes, jade will probably complain about several things, examples:

     jade:RFC2822/BCC.xml:4:20:E: there is no attribute "class"
     jade:RFC2822/BCC.xml:4:71:E: there is no attribute "hovertext"
     jade:RFC2822/BCC.xml:7:15:E: there is no attribute "class"
     jade:book.xml:71:24:X: reference to non-existent ID "packageXCL"
    

    These are ok, jade will do as it is told. The extra attributes are used to communicate info from lisp to DSSSL (formatting), and they're not mentioned in the DTD. The 'non-existent ID' is usually not a problem. You might also give the -wnovalid option to jade which will ensure that the above errors/warnings are not displayed.

  11. How can I change what is displayed in the TOC for my class/struct/gf?

    There are two ways to do this currently. If you want to change the default string for the various objects, check settings.lisp for the ("albert" "presentation" "default-purpose-string" *) settings. The way to change the specific message for a given class is to use a javadoc-style @purpose field in the documentation string, example:

     (defstruct foo
      "Foo class this that and this that. ... @purpose Handles Xyzzy transport."
      a b c d)
    
  12. The 'full listing' gets really big and cluttered, how can I sort it?

    This is being worked on.

  13. How can I change the <title> of generated HTML-pages?

    By default the name of the class or generic function will be used. If you wish to change this you can override the function that sets this name, here's an example (details might change):

    (defmethod spres-impl:docbook-page-title ((doc spres-impl:docbook-document)
                                              (object sdoc:sdoc-class))
      (concatenate 'string (sds-global:get-object-name spres-impl:*enclosing-package*)
                   ":" (sds-global:get-object-name object)))
    

    This will override for classes, and make the <title> PACKAGENAME:CLASSNAME, other variations exist of course.

  14. Albert doesn't know my FOOBAR macro, and I want contents in FOOBAR analysed, how can I do that?

    Here's an example from Langband, where I have a macro called WHEN-BIND:

    (defmacro when-bind ((var expr) &body body)
      "generalisation of (let ((var expr)) (when var ...))."
      `(let ((,var ,expr))
        (when ,var
          ,@body)))
    

    It's not a sophisticated macro, but I use it a lot and I want the EXPR and the BODY to be analysed by Albert, and this is an example of how I do it. This function returns T if it analysed something, or NIL if it didn't.

     
    (defmethod lisp2csf:check-body-expression (expr-type expression)
      (cond ((equal (symbol-name expr-type) "WHEN-BIND")
             (let ((var-calc (second (second expression))))
               (lisp2csf:analyse-body-expression var-calc))
             (map nil #'lisp2csf:analyse-body-expression (cddr expression))
             t)
            (t nil)))
    
  15. I hear rumours of Albert giving out 'called by' info, how?

    Check the settings you can set here. Setting ("albert" "presentation" "funcallable" "calledby") should do the trick.

Thanks goes to Erik Enge for testing things early and providing much good feedback, questions and suggestions.


stig@users.sourceforge.net
Last modified: Sat Jul 5 14:07:34 CEST 2003
SourceForge.net Logo