DragonFly On-Line Manual Pages
atom(1) DragonFly General Commands Manual atom(1)
NAME
atom - ASCII-to-markup filter
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
SEE ALSO
tex(1)
BUG REPORTS TO
Gary Kline kline@thought.org
atom(1)