Quick Navigator

 Search Site Miscellaneous Server Agreement Year 2038 Credits

# Manual Reference Pages  -  ATOM (1)

### NAME

atom - ASCII-to-markup filter

Synopsis
Description
Examples
Notes
Bug Reports To

### SYNOPSIS

atom -t - B{1to5}- [<number>eipQTsht] file...

### DESCRIPTION

atom automatically translates typewriter quotes into those which are displayed as properly typeset quotation marks for HTML.

Additionally, this filter also turns italics-delimited words or phrases into italics when displayed by LaTeX or HTML. The default delimiter to indicate that italics be displayed is the asterisk. This is configurable by simply editing the #define in atom.h. And, for LaTeX only, atom correctly sets the markup to correctly display ellipses. The LaTeX markup is being discounted; it will likely eventually vanish.

The following options apply:

-B Followed by the digit 1,2,3,4, or 5 inserts that many <BLOCKQUOTE></BLOCKQUOTE> tags. As a default there are 4 <BLOCKQUOTE> tags.

-c Perform simplistic centering processing.

-e Do not do ellipses processing. (Affects LaTeX only.)

-<number> <number> indicates the number of space-indentations that indicates a paragraph. (This is explained further below.) This option is also going away; eventually only an empty line or a TAB will indicate an ASCII paragraph, or a standard ASCII 5-spaces will indicate a paragraph.

-I Process italics marks only. The resulting output file is postpended with IO.

-i Do not handle italics processing.

-p Handles physical-spacing by inserting five ‘‘<BR>’’ tags in HTML and the markup ‘‘\vspace*{.5in}’’ for TeX and LaTeX. The option requires that you have exactly five blank lines in your manuscript.

-Q Process double-quotation marks only. The resulting output file is postpended with QO. With this flag "Such a line." would be translated simply to “Such a line.&rdquo

Note that to efficiently process double-quotes, you may want to use tr to join all lines in any paragraph. [ Still at work on this!]

This flag does not need the additional -t flag.

-t Process some very slight TeX/LaTeX output (DEPRECATED) (The -h flag is gone, turned into a "help" output function. HTML is the default.)

TeX is no longer the default for atom. The program handles italics and ellipses under TeX or LaTeX, and processes any italics-delimited word or words into HTML emphasis tags if this flag is specified.

Paragraphs are most easily recognized by lines of text separated by at least one newline. Additionally, a line in which the first character is a tab (’\010’) indicates a paragraph. Lastly, and these are the least preferred means of paragraph recognition, lines in which at least the first character is a space--or the first several character are spaces--followed by tab indicates a paragraph; or lines which begin with 5 or 8 spaces (’\040’) are recognized as paragraphs.

If you have used an ‘‘unusual’’ number of spaces to indicate paragraphs in your manuscript--say, two, three, six, or seven spaces, you must indicate this to atom with the -<number> flag. If you have paragraphed with seven spaces and want an HTML outfile, you must type ‘‘atom -7h <yourfile>’’ on the command line. For reasons that should be fairly obvious, if you have ‘‘atom -7h <yourfile>’’ then 5- or 8-space-indented paragraphs won’t be seen as paragraphs.

If your manuscript has any mix of tabs, 8-spaces, and 5-spaces to indicate paragraphs you do not need to use the ‘‘-<number>’’ option.

If you are about to prepare an ASCII file, best to stick with TABS or spaces to indicate paragraphs.

### EXAMPLES

For example, the following

% atom -te speech01


will correctly format speech01 into LaTeX, and produce the output file speech01.tex. Quotation marks and italicization will be handled in the LaTeX-markup output file; ellipses will not be processed.

The following:


% atom -hi ShortStory


will produce the output ShortStory.html in which double quotation marks will be processed but any italics-delimited words will be left alone.

The following command


% atom -h2 testFile


where exactly <2> or <number> spaces indicate paragraphs within the file test, will produce a properly formatted HTML output file.

For example:



This is a case where there is a new
paragraph that is indicated by a 2-space indentation.
This happens occasionally.
And this is yet another instance of the
above. For atom to turn these two paragraphs into HTML or TeX
formatted paragraphs, use the command: ‘‘atom -h2 <file>’’ or
‘‘atom -t2 <file>.’’



will produce the following:



<P>
This is a case where there is a new
paragraph that is indicated by a 2-space indentation.
This happens occasionally.
<P>
And this is yet another instance of the
above. For atom to turn these two paragraphs into HTML or TeX
formatted paragraphs, use the command: ‘‘atom -h2 <file>’’ or
‘‘atom -t2 <file>.’’



Note that without the ‘‘-2’’ flag in this case, the HTML or TeX output would run these two paragraphs together.

The commands

        % atom -Q lglass18.txt       # translate quotations marks to ‘‘ and ’’


will produce ‘‘lglass18.txt.QO.html.’’

Finally,


% atom -t story01 story02 story12


will produce story01.tex, story02.tex, story12.tex with any quotation marks, italicization, and ellipses marked up in LaTeX style.

atom will do centering if and only if your original ASCII file has the strings judiciously centered by using spaces-only to the left of the centered string. If you use this -c option, any paragraphs that are denoted by 5 or 8 spaces will not be seen as paragraphs and not processed as such. If you do have space-centered lines that you wish to be centered in HTML or LaTeX and you also have paragraphs denoted by 5 or 8 spaces, you will have to edit your ASCII source and replace the spaces to tabs. Then run atom to handle the centering.

Note that in this simple filter, centered text is best if only one or two lines. atom will not handle multiple lines of centering efficiency.

The latest version of atom automatically puts only a single paragraph tag, ‘‘<P>’’ between what are understood as paragraph, namely, a single vertical line space {or newline}. Previously, if the source file had thee newlines, there would be three paragraph tags, each on it’s own newline. In short, the -s switch is history.

### NOTES

Any series of three dots (...) is, for LaTeX, considered to be an ellipse.

This program could be expanded to handle boldface markup, but this would require having another delimiter, and we are creating yet another markup language.

I admittedly am tempted to have this filter handle a maximum of two types of markup: the standard _underscore_ for italics or <EM>, and the *asterisk* for bold or <STRONG>. ...But not that tempted!

Finally, it is worth noting that if your plain ASCII file has a lengthy italicized string--something that exceeds 80 columns, for example--the best solution is to simply join the lines of your italicized string.

Copyright (C), 1994, 1995, 1996, 1997, 2001, 2005, 2006, 2007, 2008, 2009 by Gary Kline

This software is placed under distribution restrictions and rights according to the GNU General Public License. See the file ‘‘COPYING’’ included, or write to the Free Software Foundation, Inc., 675 Mass Avenue, Cambridge, MA 02139, USA