What does SDS mean?

- SDS is pronounced "Software Development Foundation". It has been claimed that it means "Serious Development System", but I presume this is only if you configure it --without-humour
What is CSF?

- CSF is the Code Structure Format. It's an XML-format which captures most of the information necessary to create nifty development tools. It's not very complex, yet powerful and flexible enough to be useful for several languages (C, C++, Java, Pascal, Python, etc.)
What is SDOC?

- SDOC is the Documentation-part of SDS. It is also the name of a XML-format. CSF-files can be translated to SDOC. Where CSF is the core format, SDOC tries to organise the information in a manner more suitable for "written" documentation.
Why is SDS written in [insert language]?

- It's a compromise. Not all parts in SDS are in [insert language] though. Other code is written in Common Lisp, Java, C, C++ and Python. The foundation of SDS is XML and that is language-independent, so basically every developer can choose his or her favourite language to do the job.
I have an IDE (or some other tool) and want to use SDS/parts of SDS, how can I do that?

- We have not worked out the implementation details, as those will vary a lot. You will probably try to access the Lisp server. sdsclient.py will be a good example on how to do this. As for legal issues; SDS is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation version 2 or later.
SDS is too complex for me. I don't know all compiler-options and I am not used to command-lines.

- Those are statements. Not questions. But I'll answer anyway. Yes, SDS is complex if you're a beginner. It is however flexible and powerful and meant to be included into (more visual) development environments AND build-systems (like Make). We respect that your mileage may vary. Consider it more like a library than a clicky-click tool.
XML-files are large and somewhat complex, can I verify my file vs the DTDs?

- Yes. Provided that you have James Clark's parser nsgmls installed and you have installed the DTDs for the SDS XML formats, you can verify your XML-file with validatexml.sh xmlfile.
Why do everything screw up with my latin 1 characters?

- XML uses UTF-8 and all files which use ISO-8859-1 (or latin1) must be translated to UTF-8. Unfortunately UTF-8 and latin1 aren't compatible. There is a small recode.sh script (which uses GNU recode) in the src/scripts/ directory which can be used to do the translation.

CSF and information-retrieval

What compilers support CSF?

- Currently we have three semi-working frontends (C++, Java and Common Lisp) which can produce CSF, but as more parts stabilise we expect that the number of compilers and parsers with CSF-support will increase rapidly.
CSF does not fit 100% with [insert language], why?

- CSF is supposed to be general enough to accomodate several languages. As C, C++ and Java were the first languages considered and chosen, they have of course left their mark on CSF. This was more visible in the older version of CSF, while the newer version of CSF is much more general and can serve the needs of more languages.
Are there any disadvantages with using a compiler front-end?

- Yes. Several limitations of this approach became visible when using Cppp [which is now no longer part of the source-tree]. The biggest problem is complexity, as it can be rather complex to dive into the trees to get info. Some info may not be in the trees semantic processing. Among them is the name of arguments in your function declarations, though the names of arguments in the definition is available (and are used) in the argument scope. And you can't document macros in C/C++ for obvious reasons (this can be solved easily by adding a primitive pre-processor). But you get full access to the code and can document whatever you want, and that is what you really want, no?

SDOC and information-presentation

Why not use other documentation systems?

- Most documentation systems I have seen on the Net seems excellent for smaller projects and I strongly recommend them for small projects. They have short-term parsers too but they do a good job with a lot. SDS and SDOC in particular is not meant for small projects or for "easy" code, but for middle-sized projects where the code gets gritty and most documentation parsers choke and where you want a bit more than glossy html-pages. As an example, all parsers I have tested on our hypermedia system have collapsed, even commercial ones. The code is not really complex, but uses defines for e.g dll-making and function hiding in shared objects.. parsers trip. My experience is that when code gets beyond 10-15 KLOC and is written by people with a tendency to make hacks to make it easy for the developers/"people" (not parsers and compilers, and this is how it should be imho), that one needs hand-tuning and special rules. Again, if you don't find this familiar and if your biggest program was 5000 lines with gui-code, find another documentation system.
I heard of an Emacs-module for accessing the SDOC documentation from Emacs.. can you confirm this?

- Check the src/emacs directory. The source was based on Erik Naggum's hyperspec.el (for accessing Common Lisp documentation). The Emacs-module is getting revised though and a more complete system where Emacs queries a SDS server will be added.
What output formats are supported by SDOC?

- Currently (v0.5.x) only Docbook/XML. Luckily this format is easily translatable to HTML, Postscript, PDF, and others. The HTML-format code is not maintained as Docbook will be the main supported format.
What about support for other output formats?

- Should be easy to add. Add your own lisp-code and mail it to me and I will add it. YMMV so it is easy to add other formats and/or tune existing ones. Lisp is excellent for this (too).

Extending SDS

Is it easy to make an extension to SDS?

- Yes and no. As for the compiler and parsing-part, I suggest that you at least take a compiler-course at a university. It's never easy to work with complex systems as a compiler-frontend is. Dumping the info to the CSF-system should be ok though, and using CSF or SDOC for various purposes should be easy though.
How can I specify a hyperspec-location for my documented lisp?

Please check out tests/glob-prefs.xml where the hyperspec-pref is in the general-element. This may also be customised in src/clisp/base/defaults.lisp before compilation.

How can I specify which dtd to use for docbook-output?

Please check out tests/glob-prefs.xml where the dtd-pref is an info-field for a format in the output-prefs. This may also be customised in src/clisp/base/defaults.lisp before compilation.

All the APIs seem generated. Why?

- It was a mess maintaining apis in several different languages for every small change needed, and changes are more frequent than we could've wished for. My solution was to specify the APIs in XML and use a tool to generate the code for other languages. Currently, APIs can be output in C++, Java, Python and Common Lisp. The APIs that are already specified in XML and are used is CSF, SDOC, Preferences, Module-Spec and actually the API-API itself. A nice bootstrapping was done in a running Lisp-system. The API-generator is written in Lisp.
How do I generate an API?

- See the update-all-apis.sh script in src/scripts/ directory.
generate-sds-api mentions HTML, can this be used in HTML OS?

- If you use the HTML OS (Operating System) you can use the APIs directly, just load the produced HTML-file and it should work. The code should be fairly portable across platforms.
Ever thought of database-support?

- It will eventually show up, but is mostly of interest for really large projects. If memory use is a problem, let us know.
Is it easy to add new keywords to SDOC?

- This is being updated now. I plan for it to be really easy.
I have added a front-end. How can I verify that my id's are correct?

- The csf2sdoc tool has an option -V which verifies your CSF-file before conversion. This verification also checks id-fields.
What kind of policy is there for adding new tools and front-ends for writing in non-mainstream languages?

-SDS has an open architecture and a rather liberal attitude to what kind of languages and tools can be put in the SDS-distribution. Currently (19.aug), at least four languages are used to create SDS-tools and the number will probably grow. The liberal attitude may mean that from a user or developer's point of view; obscure, odd and/or experimental languages are used. But, to put it simple: The open architecture will allow developer FOO to add support for language/library/system XYZZY in SDS and/or use XYZZY to add useful functionality to SDS, which means that an SDS-user probably need to get XYZZY to use that functionality. This will usually mean: extra effort from the user during installation

A developer's time should basically be used to develop and enhance functionality. This is done easiest by using well-suited tools chosen carefully based on whatever the developer believes in. SDS is for developers so I am sure you understand and appreciates this policy at the cost of some extra effort when installing.

Please note that tools based on commercial systems not freely available will probably not be put in the main distribution, but might be placed in the SDS-area for easy download. The different language front-ends may be put in separate packages at a later stage.

About OSes

Why write software for Unix/Linux?
- Unix and Linux is not close to an OS in Plato's world of ideas (I hope) but they're decent to work with, and once you know how to use the many programs you can be quite productive. Unlike on lesser OSes you reap the benefits of both tuned command-line interfaces and of guis.

Technical issues

SDS leaks memory

- The C or C++ code may leak memory, yes. Buy more memory for your box. I am used to at least 128 Meg memory and I expect people who will use SDS will use a RealOS with a decent amount of memory. If the memory-use is a problem (let me know) I will add a garbage collector. Be happy.
SDS is big

- Probably. If this is a problem for you, let us know. Any serious developer should have a decent amount of memory and disk space on his box though.
Real programmers use C, isn't SDS a real program?

- SDS has some minor parts in C, and uses the expat XML-parser which is in C. The rest is plain vanilla code.
C++ is Great! Why don't you program everything in C++?

- C++ isn't awfully peachy. It can be powerful but it is ugly, and Stroustrup's third edition scares me. I like many other languages better but where the alternative is C vs C++ I usually end up with C++ because I soon miss my string-class and templates and at times inheritance. It can be hacked neatly in C but it is more fuss. CLOS is in most ways superiour to C++. Java is an easier C++ and often worthwhile.
Why do you use Lisp? Lisp is slow.

Those of us raised in C/C++ environments have been taught for ages that Lisp is really slow, has too many parantheses and is only good for AI (and AI was never a success, which probably was Lisp's fault). Of course, this is not so. However, as all good lies, there are some truth in it.
- Some Lisp implementations have been slow. Today, some Common Lisp implementations is better at number-crunching than Fortran and for other stuff it can beat C but is comparable to C++. But, to quote Richard Gabriel: "In Lisp, writing programs that perform very poorly is quite easy; in C it is almost impossible". Lisp-novices produce slow code. I am a novice, but currently the performance is near the equivalent C++ code in ACL. The most recently written code is usually written as code where I explore the domain and try to solve the problem and is not optimised. As time goes by it is profiled and optimised and in the end one has a correct and fast result.
- A more thorough comparison of some lisp and c++ code: here and the lisp code is simpler, faster and smaller. It's not too hard.
- Lisp has more parantheses than C, but after some use it feels more natural and is in fact quite useful.
- Lisp is excellent for AI, but also for other stuff. AI'ers have yet to create HAL (actually Deep Space 1 has got a nifty AI which controlled the spacecraft for several days. The AI was written in Common Lisp.), but compared to other achievements in software engineering they've probably come just as far, if not further.
I use Common Lisp and CLOS because it's much easier for me to write usable programs in CLOS compared to C/C++. The people who are writing decent software and who has a need for SDS should also be CLOS-aware. The Lisp development is mainly done on Linux with Allegro CL and therefore is (probably) faster there.
The Java front-end is slow, why?

- To be pedantic, it is the AST tree traverser which is slow. This is mostly due to lack of optimisation in the current version. A lot of unneccessary copying can be removed, and some short-cuts can be taken with some of the Java language constructs, but this could mean trickier code in some places. It will be fixed as the Java front-end matures.
The python-code is slow, why?

- The python-support is the most recent and it seems to have been a port from the c++ code and doesn't always use what is smart in python. As the python-code takes on bigger challenges, it is expected to grow.

SDS FAQ

General questions

CSF and information-retrieval

SDOC and information-presentation

Extending SDS

About OSes

Technical issues

Other questions