The latest version of this FAQ is available from http://www.mincom.com/mtr/sdf/faq/.
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.
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.
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.
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.
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 ...
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.
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:
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.
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.
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. :-)
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.
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.
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.
Within Mincom, SDF is used for a large number of purposes including:
Outside of Mincom, SDF is also used for many things including:
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.
My current priorites are:
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/.
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.
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.
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).
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:
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.
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.
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.
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 |
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