Program Documentation for "mm2frame" by David A. Wheeler Documentation as of August 2000 (superceding 3/12/92) (C) David A. Wheeler 1990, 1992, 2000 mm2frame is a program for translating basic troff/mm commands into Framemaker. The combination of troff and the mm macros will be called MM in this documentation. To translate MM documents into Framemaker documents: 1) Install the program (see the file INSTALL on how to do this) 2) Rename your MM file so that it ends in .mm (mv oldname oldname.mm) If the program was installed to be automatically invoked from Framemaker: 3) Use Framemaker's File/Import command. Choose your file, which now ends with .mm. You may need to execute the "Redisplay" command. Else (the program was not installed to be automatically invoked): 3) Type: /usr04/wheeler/framemm/mm2frame oldname.mm 4) Use Framemaker's File/Import command. You'll notice a new file ending in .mml -- choose this file. You may need to execute the "Redisplay" command. Currently this is a VERY simplistic translator. It does not handle preprocessor commands, such as tables, equations, or pictures (tbl, eqn, pic), it ignores many parameters, it ignores all MM variables, and handles only a limited subset of the MM commands. Commands the translator doesn't understand are included in the resulting Framemaker document as regular text. Nevertheless, this is helpful for documents which use (at least mostly) a subset of the MM commands. It certainly beats doing it ALL by hand. The next best alternative to this translator is to rename the file to end in .txtalt and then use the Framemaker file/import command, but the formatting information is unused. The translator handles the following MM commands: italics (\fI, .ft I or .I), bold (\fB, .ft B or .B), normal (\fP, \fR, .R or .ft R), headers (.H 1-3), dashed and bold lists (.DL/.BL - .LI - .LE; can't imbed them), don't fill/fill (.nf/.fi), paragraph (.P), and center (.ce no arguments, creates a Title paragraph). The vertical space commands (.sp, .SP, .SK, and .bp) are interpreted as new-paragraph commands. The table begin & end commands (.TS/.TE) and displays (.DS or .DF /.DE) will cause each line to be its own Framemaker paragraph (as don't fill/fill do) in order to make translating easier. Special characters such as double-backslash, angle brackets, dagger, logical not, em dash, and double quote marks (both directions) are translated as well. Note: if your documents have heading levels greater than 3 (.H 4, etc), you should define equivalent paragraph types BEFORE you translate. --- David A. Wheeler wheeler@ida.org ------------------------------------------------------------------- Design information: Actually, mm2frame performs various checks and then calls mm2mml, a filter program that accepts MM and produces MML. MML is an intermediate Framemaker format. Framemaker then translates MML into MIF, and then translates MIF into its own internal format. mm2mml sends the file through a sed script to do some cleanup (mm2frame.sed), then through an awk script (mm2frame.awk). The resulting file is in MML format. This file has an include statement for the file troffmm.mml -- a file with various formatting information that can be modified for other formats. Currently the sed script translates the italics, bold, and plain commands, as well as stripping off quotes in the .H command. It also translates certain characters that can appear in MM files into their equivalent MML characters (tab, greater-than, less-than, and backslash). Be careful about modifying the order - the order the substitutions are done in is important. The sed script outputs all backslashes as doubled backslashes. The characters backquote and forward quote are not translated - it appears that the Frame documentation is wrong in suggesting this translation, because it results in garbage. See MML Reference manual page 2-10 and .../frame/source/txttomif.c. The awk script does all the rest. mm2frame understands the following MM commands: \fI \fB \fP or \fR Note that this is really "previous" in troff, not "plain", but in troff it is usually used to revert to plain text and so is translated that way. For example, the program checknr checks to see that all \fx commands end with \fP and complains when this is not true. This translation would have to be done in the awk script in order to really make it "previous" (it is currently done in sed). .ft B, I or R Into Bold, italics or roman. .B, .I, .R Bold, italics, roman. These work normally with 0, 1 or 2 parameters. Bug: if these commands are given more than 2 parameters, any quotation marks which surround the parameters will (unfortunately) be included. `` and '' Into and , the doublequote chars. \(dg Into , the dagger character. .H x text (heading) Note: x must be <=3. If it is greater, edit troffmm.mml to support larger values of x. each of these is translated into: {CR} <{x}Header> text (with surrounding quotes removed) {CR} then sets "bodynext" .DL (dashed list) .BL (bulleted list) Limitation: ignores arguments. Note: imbedded lists are not supported. The current implementation just skips these commands & all the real work occurs in the .LI command. If bullets should be differentiated (FirstBullet, Bullet) or nestable this (and .LE) would have to be modified. .LI (list item) Limitation: ignores arguments. Generates: {CR} then unsets "bodynext" .LE (end of list) Currently just skips and sets Bodynext. .P (paragraph) Limitation: ignores arguments. Currently just sets Bodynext .TS/.TE Makes each line a paragraph. Doesn't translate tables, but this makes table conversion easier. .nf/.fi Makes every line a paragraph. .ce (center) Limitation: ignores arguments. Generate {CR} set Bodynext .\" Comment eliminated. .DS/.DF/.DE displays - same as nofill/fill (.nf/.fi) .any other command copied into the output and sets bodynext. Encountering anything else, the system will: 1) if "eachline" is >0, print a blank line. 2) if "Bodynext" is set, output: <Body> 3) copy lines until it hits something it recognizes. In the awk script, the following variables have the following meanings: eachline: if >0, each line is turned into a paragraph by seperating each line with a blank line. .TS and .nf add one to it; their converses subtract one. bodynext: if >0, if the next line is normal text a <Body> phrase is put in front of it. The following are constants: defaultparagraph -- name of default paragram in MML format. Currently <Body> headingname -- name of heading format. Currently Heading. headingformat -- format of Heading in MML in C printf format. Currently <%d%s>\n. This program should be installed in ../frame/.fminit2.0.ps/MifRead so that the filename suffix .mm will automatically engage this if you often translate from MM files. POSSIBLE UPGRADES The following MM commands could be handled better, and are listed here to give people ideas on how to improve this. .TS/.TE Could translate tables, but that's hard. I understand others are working on programs to translate tbl tables into Framemaker; if they become available they could be automatically invoked. .SK A real page skip. This isn't so easy in Framemaker. .sp and .SP Improve vertical spacing to do more than create a new paragraph. .UL text underline text. This isn't officially an MM macro but it's in common use at IDA. It'd be <underline> ... <nounderline>. This would be an easy addition. The sed script already strips any double quotes on a UL command in anticipation of this command being added. .S point size. <pts number> is close. The awk script could keep track so that +2, etc, would work. This wouldn't be too hard to add. .FS/.FE footnotes. Possibly generate <Footnote> at the appropriate time. .ce NUMBER use the NUMBER for centering .DS options .BR, .IB, .RI, .BI, .IR, .RB alternating bold, roman & italic commands. (note that \fI, etc, works) equations and figures This could be difficult. other special characters This is an easy addition, just time-consuming if you add ALL of them. Editing mm2frame.sed should do the job for almost all special characters. Other characters are especially important for mathematical or non-English documents. See appendix B of the Framemaker Reference Manual for Framemaker characters, and the sed script for some examples. In particular, I've done the "dagger" character as an example in the sed script. Note the double backslashes and the space before the greater-than sign - these are required! You may also consider using "lex" to translate characters. .LI support multiple depths of lists, not just one. .AL x y Alphabetized or numbered lists. FILES INCLUDED IN TRANSLATOR ARCHIVE The following is a brief description of the files included in the translator shar archive. mm2frame -- Main program (for use by humans). Calls mm2mml. mm2mml -- Real filter program. mm2frame.awk -- Awk script... does the more difficult translations. mm2frame.sed -- Sed script... does the simple character-based xlations. mm2frame.txt -- Program documentation (former filename: mm2frame.pdoc). Test.mm -- Test file in MM format (type "make" to do a translation) Makefile -- Makefile for the mm2frame filter program. Allows the user to run a test case, install for the first time, install to the "final" directory, or create a shar archive. changename -- Simple program to change all instances of one phrase with another. Currently a sed command. INSTALL -- Text file of Installation instructions. README -- Text file of basic information. DISTRIBUTE -- shar archive created via the Makefile. This is created by typing "make DISTRIBUTE". sharup -- creates a shar archive. troffmm.mml -- file in MML format. Used when Framemaker loads the MML file created by this filter. Includes commands to create new paragraph types and to declare types that already exist and may be used by the filter. BUGS A double-backslash followed by the troff italics, bold, or previous commands (which begin with another backslash) won't come out correctly due to the way the sed script is organized. This bug is unlikely to cause problems in real documents. An escaped " in the parameters of commands doesn't work well. For example, the .B, .I, or .R commands work in funny ways. The troffmm.mml file could probably be cleaned up and shortened a bit - right now it sets too many things. It works for me, so I haven't bothered to change it. INSTALLATION To install the program somewhere else, follow the INSTALL file's instructions. It is necessary to substitute all instances of /usr04/wheeler/framemm with the name of the directory the files are actually installed in. The program "changename" was included to do this automatically to make installation easier. CHANGES If you make any changes to this program that you find useful, please let me know! Use "make DISTRIBUTE" to create a shar file (named DISTRIBUTE) of all the files to transport. Email the resulting DISTRIBUTE file to David A. Wheeler at "dwheeler@dwheeler.com". Currently mm2frame is available at http://wwww.dwheeler.com. NECESSARY LEGAL STATEMENT This product is not sponsored by the Institute for Defense Analyses (IDA) and comes "as is". Neither IDA nor David A. Wheeler guarantee that this product will or will not do something. The term product includes the executable program as well as its documentation. This software Copyright (C) 1990-200 David A. Wheeler. This program 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; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA The following are the original licensing conditions. In 2000 I switched the license conditions to the GPL instead. I include the following below, so you'll know what the old rules were: You may freely use this program as long as you do all of the following: 1) Give credit where credit is due. You must leave in the notice of who wrote this program both in the code and in the generated file. 2) Don't sell it commercially (for profit) or as part of a commercial package. Talk to me if you wish to!