Home | Catalog

SDF Frequently Asked Questions

SDF-FAQ.001 (Final)
Ian Clatworthy
25 May 1999

Table of Contents

1. General Questions

1.1. Where can I get this document?

The latest version of this FAQ is available from http://www.mincom.com/mtr/sdf/faq/.

1.2. What is SDF?

SDF (Simple Document Format) is a freely available documentation system designed and developed by Ian Clatworthy, with help from many others. Based on a simple, readable markup language, SDF generates high quality output in multiple formats, all derived from a single document source. Supported output formats include HTML, PostScript, PDF, man pages, SGML, POD, LaTeX, GNU Info, MIF, RTF, Windows help and plain text. If you want to:

then SDF may be for you.

1.3. What platforms are supported?

SDF documents are plain text files which can be created on any platform.

The SDF software has been completely developed in Perl, so it can be executed on all commonly used platforms including most variants of Unix, most variants of Windows, OS/2, the Macintosh and VMS. Perl 5.003 or later is required.

1.4. How do I get it?

SDF is available in a number of formats from http://www.mincom.com/mtr/sdf/download.html. It should also be available from CPAN, the Comprehensive Perl Archive Network.

1.5. What else is required?

To generate PostScript, SDF requires one of the following:

Earlier versions of FrameMaker will generally work, but I don't explicitly support them.

To generate PDF, Adobe Acrobat is required.

To generate Windows help, a help compiler (e.g. hcp.exe) is required.

1.6. How can I learn SDF?

Generally, the best way to learn SDF is to read the overview paper called The SDF Document Development System - it should contain enough details to get you started. If you need further information on the commonly used features, read the first few chapters of the SDF User Guide.

If you already know Perl's POD format, you might want to read the SDF for POD Users tutorial before these.

In practice, 99% of SDF documents are created by copying an existing one and making the necessary changes. So, once you're created templates for the types of documents you commonly produce, things are pretty simple ...

1.7. How is SDF supported?

The following mailing lists are available:

To subscribe to these lists, send email to sdf-users-request@mincom.com and/or sdf-bugs-request@mincom.com for instructions on using factotum, the majordomo variant that manages these lists. In short, send email to factotum@mincom.com with a message body of subscribe sdf-users or subscribe sdf-bugs.

An on-line bug database is also available providing information on some of the known bugs and requested enhancements.

1.8. Why is SDF free?

I have always wanted to contribute a useful tool back to the worldwide software community which has given me so many useful tools (e.g. Perl). As there appears to be very few documentation tools which:

  1. generate high quality output in multiple formats, and
  2. reduce the time it takes to produce software documentation

SDF will hopefully be useful to a large number of software developers.

Also, by being freely available, SDF should benefit in several ways. These include more testers, more add-on tools and more design ideas.

1.9. Is SDF still simple?

Arguably not. But SDF has remained simple in spirit, so the name hasn't been changed. Maybe Software Document Format would be a better choice, given that SDF is part mark-up language, part programming language. Feel free to make SDF stand for whatever you like.

1.10. Why the grapes logo?

After considering a few logos with a paper/writing theme, it was decided to follow that great software package tradition - a meaningless logo! As an on-line documentation system is essentially a cluster of topics linked together, I looked for something which reflected that idea. After 10 minutes, the best I could do was grapes, a fern or a wattle flower. After 5 seconds of agonising decision making, the prize went to the grapes.

Fortunately, there seems to be some useful parallels:

Ok - it's not as sexy as a cup of coffee, but grapes, grape juice and red wine (at least) are probably better for you. :-)

1.11. How can I help?

In lots of ways:

Tell your friends about SDF.

Tell the world about SDF.

Report bugs.

Make SDF more useful.

Make it easier for people to migrate to SDF.

2. SDF in the real world

2.1. How stable is SDF?

Other than some syntax changes introduced in 2.000beta10 to make SDF more palatable for users of Perl's POD format, the core SDF code hasn't changed much since early 1996. Within Mincom, people have been using SDF on a daily basis for at least 4 or 5 years now.

2.2. How many people are using SDF?

At the moment (February 98), my guess is that SDF has 50-100 users within Mincom and a few hundred within other organisations. Excluding Mincom, SDF has active users within a large number of countries including Australia, Belgium, Canada, Denmark, England, Germany, France, Italy, New Zealand, Norway, Russia and the USA.

2.3. What is SDF being used for?

Within Mincom, SDF is used for a large number of purposes including:

Outside of Mincom, SDF is also used for many things including:

Note: If you are using SDF and would like to be mentioned above, send me some email.

SDF can also be used to convert documentation in Perl's POD format to any output format supported by SDF. For example, the HTML produced by SDF for Perl's documentation is available at http://www.mincom.com/mtr/perl/catalog.html.

2.4. What new developments are expected for SDF in the future?

My current priorites are:

  1. Supporting existing SDF users (by email and bug fixes).
  2. Developing the next generation of SDF called SimpleDoc.

The key objectives of SimpleDoc are:

As always, my time is limited, so if one or more of the above features interests you, let me know so I can prioritise things accordingly.

Further information on SimpleDoc is available on the web. The URL is http://www.mincom.com/mtr/simpledoc/.

3. Output Formats

3.1. What output formats does SDF directly support?

HTML, plain text, POD, MIF (Maker Interchange Format), SGML, MIMS F6 help and MIMS HTX.

When generating HTML, either a single document or a set of topics can be created.

When generating MIF, either a single document or a FrameMaker book and set of chapters can be created.

3.2. What output formats does SDF indirectly support?

By using the pod2* programs provided with Perl 5, SDF can generate man pages, LaTeX files, PostScript and a few other formats.

By using FrameMaker, SDF can indirectly generate PostScript, FrameViewer, RTF and other formats which FrameMaker can export. On Unix, most of these can be generated using FrameMaker's batch utility (fmbatch). On other platforms, it is necessary to generate a MIF file, open it in FrameMaker and print, save or export to the required format.

By using SGML-Tools 1.02 or later, SDF can indirectly generate LaTeX, RTF, GNU Info and LyX formats. If LaTeX is also installed, SDF can indirectly generate PostScript and DVI.

3.3. Why should I use SDF when my word processor can generate HTML?

Unlike WYSIWYG tools, SDF encourages authors to specify documents in a logical manner. As a result, SDF has the semantics it needs to generate high quality paper-based and online documents.

SDF also includes a number of features which greatly simplify the effort required to produce online documents. These include:

It could be a long time before word processors provide these features. As a result, it takes a lot less effort (and cost) to create and maintain a large online documentation system in SDF when compared to existing WYSIWYG tools (that I know about, at least).

3.4. Can SDF generate Word documents?

Not directly. However, SDF can generate RTF (Rich Text Format) files which can be opened in Word and many other word processors. The commands to convert a file called mydoc.sdf to RTF are:

   sdf -2rtf_mif  mydoc.sdf
   sdf -2rtf_fm   mydoc.sdf
   sdf -2rtf_sgml mydoc.sdf
   sdf -2rtf      mydoc.sdf

The first of these works by generating a MIF (Maker Interchange Format) file and then converting it to RTF via a Perl script supplied with SDF called mif2rtf. The main problems with mif2rtf are:

  1. it is slow
  2. the output is not as great as one would hope for
  3. it occasionally crashes. :-(

The second command works by generating a MIF file and then converting it to RTF via FrameMaker's RTF export filter. This approach is more reliable than using mif2rtf, although it has it own set of problems and limitations.

The third command works by generating a SGML file and then uses SGML-Tools to generate RTF. I haven't tested SGML-Tools's RTF generation, so I have no idea how well this will work.

The forth command is an alias for one of the commands above. See the FormatMapping section of the sdf.ini file to view and/or edit the mapping.

Oneday, SDF will support RTF directly.

3.5. Can SDF generate Windows help?

SDF can generate RTF files and HPJ files which are the inputs to a Windows 3.x help compiler (e.g. hcp.exe).

I haven't tried building help for Windows 95 or NT, so I'm not sure how well that works or otherwise. In any case, Microsoft is moving to HTML for online help, so I'm not overly motivated to improve the existing support for Windows help.

3.6. Is FrameMaker needed for generating PostScript?

No. SDF can generate PostScript via the freely available pod2ps program or the freely available SGML-Tools/LaTeX packages.

However, if you have FrameMaker, using it currently has the following advantages:

Alternatively, SDF can be used to generate RTF which can then be imported into most word processors.

4. Language Issues

4.1. How do I enter an empty row in a table?

TBL format ignores blanks lines, so to enter an empty line, you need to enter an empty cell like this:

!block table
Big     Small
A       a
{{}}
B       b
!endblock

The result is:

Big Small
A a
   
B b

4.2. How do I enter a multi-line cell in a table?

By beginning a cell with a << symbol like this:

!block table
Option  Description
-g      <<
        This option produces the following:

        !import "g_code"
>>
-v      verbose mode
!endblock

Note:

  1. The cell is terminated by a >> symbol at the beginning of a line.
  2. You can place any SDF you like within the cell.
  3. Whitespace is generally ignored at the beginning of lines, so you can put the cell contents under its column heading if you want to.
  4. If the multi-line cell is not the last one within the row, you currently need to format the table using delimited format rather than fixed width format.

Home | Catalog