Title: Members' Experiences

SDF (Simple Document Formatter) is one of those Unix/Linux programs that takes a document written in its own markup language and converts it to an impressively long list of possible output formats, including HTML, LaTeX, manual pages, Windows help, PDF, and so on. What sets SDF apart is the closeness of its markup language to plain text; you won't have to spend much time learning it, and the result can be read as plain text (the markup is unobtrusive). It supports tables (you set it out in columns in the text), lists (you use * and other symbols), figures, headings, code samples, links, macros, conditional compilation, inserting dates, and other things.

SDF is also designed with programmers in mind; it can extract its text from comment blocks in source code, and it can select different sections for different output documents (e.g. user manual versus technical reference manual). It can also pretty print any code extracts that are included in the text (or you can just use it to pretty print a file of code). However, it is not a system for automatically generating documentation from class definitions like JavaDoc.

When I tried SDF, I found that some of the output formats were dependent on external programs (such as sgml2latex), which were not necessarily installed on the machine (even though the package manager is supposed to take care of these things). Aside from that, I would consider this a program worth knowing about.

FunnelWeb is a literate programming system, similar to Donald Knuth's "Web" system but not limited to Pascal or C (and the output code does not look like object code). The idea is that you maintain a document with fragments of code in it, and either the document can be typeset (in TeX or HTML) or the code can be extracted (with re-ordering if necessary) for compilation. The system is really a macro preprocessor and a formatter; writing a code extract is defining a macro, and typesetting the document is formatting it with the macro definitions as figures. Extracting the code itself is executing the macro pre-processor (which has the ability to write files).

The macro preprocessor is powerful, but its syntax is slightly messy (this is justified by saying it makes sure you do not call a macro accidentally) and it takes some getting used to. There is an emacs major mode for FunnelWeb files, based on LaTeX mode, but you lose the C or C++ editing features. The typeset output is reasonable, but you can not hide the fact that it is a FunnelWeb document - all the figures have captions like "This macro is invoked in definition 32", which is not helpful if the document is intended for readers unfamiliar with FunnelWeb ("Macro? I thought I was looking at an enum"). This limits its usefulness a little.