Hi all....
On this subject, I wanted to submit my FAQ maintaining method,
claiming it to have the most unique combination of the following:
- efficiency in write-up time for its purposes
- ease of maintaining the desired formats with their unique needs
- beauty of output results--i.e. they're just what I want
- and convolution in the way it produces the final outputs
:-)
Here's the deal. I maintain the Relativity and FTL Travel FAQ for the
rec.arts.startrek.tech newsgroup. Because of it's complicated subject
matter, it's more of a text-book style write-up that explains the
subject as thoroughly as needed.
I provide the four part FAQ as a graphics-rich HTML version, an HTML
version without graphics, a plain text version, and a LaTeX version
along with its corresponding postscript file. All of these formats
are produced from one source file, and they each contain formatting
and information unique to their needs.
I do this by using my own sort of mark-up language in conjunction with
perl, latex, latex2html, and Netscape. My mark-up language (processed
with a perl script) is rather latex-like, but is made to produce just
the results I want for my specific needs. For example, let's say I
have a section called "Junk Section" and labeled "sec:junk"--then I
write in my source file:
\section{Junk Section}{sec:junk}
If I then want to reference that section (say it turns out to be
section 2.1), I could use any of the following:
\ref{sec:junk}
-- rendered as the section number and made a hyperlink in the
-- html versions.
\rref{sec:junk}
-- rendered as "Section 2.1" and the whole text is made a
-- hyperlink in the html versions.
\rref{sec:junk}{see the previous section}
-- rendered as "see the previous section" and made a hyperlink
-- in the html versions.
\rref{sec:junk}{<k> <#>: <t>}
-- where <k> stands for the kind of reference (here, a
-- "Section"), <#> stands for the reference number, and <t>
-- stands for the title of the reference. Thus, this is
-- rendered "Section 2.1: Junk Section" and made into a
-- hyperlink in the html versions.
\rrefnl{sec:junk}
-- rendered as "Section ##" but without making a hyperlink in
-- the html versions (nl stands for no link)
etc.
That's just one example of the mark-ups I use. Another very useful
one is \hnal which lets you specify things to go separately into the
*h*ypertext, hypertext--*n*o graphics, *a*scii, and *L*aTeX versions.
It works like this:
\hnal{hl:cool graphics, huh?}{na:sorry 'bout the ascii graphics.}
The first part goes in the "h" and "l" versions (html and LaTeX, which
have nice graphics) and the second part goes into the "n" and "a"
versions (no-graphics html and ascii, which have only ascii graphics).
Similarly, I could write
\hnal{hn:aren't hyperlinks convenient?}
to just put that text only in the two html versions. Further, since
the html and LaTeX versions can contain graphics for their in-line
equations while the others cannot, I might write something like this:
\hnal{hl:$\gamma$}{na:\it{gamma}}
where the "\it{}" is used for italics. But I made a shorthand for
this:
$\gamma!gamma$
Oh, and to put in a diagram called, say, junkdi, I'd just write
\figure{junkdi}
and my script finds the right files (junkdi.txt and junkdi.gif for the
ascii diagram and graphic diagram respectively) and formats the
versions appropriately (centering the diagrams in all formats). Or
to use 2 diagrams side by side:
\figure{junk1di,junk2di}
On and on and on, I use my little helpful mark-ups. In the end
though, I didn't want to have to do ALL the rendering into the various
formats myself. So, my perl script turns the source file into 4 latex
files, one for each format. That produces the latex version just as
needed with the other 3 versions each heavily marked-up with
latex2html tags to keep my own formatting and html coding intact.
Then my script runs each of the three non-latex versions through
latex2html, producing the desired html versions (one slower-loading
but graphics rich, the other faster-loading but ascii only) and the
almost-finished ascii version. Finally, it calls Netscape (with the
proper flag) to turn the ascii version into its final, well-formatted
product.
It's nice to let these other programs handle a lot of the formatting.
For example, I do not center my own ascii diagrams. Rather, my script
puts them into html tables, tells html to center the tables, and
Netscape does the centering for the final ascii version.
The only real draw-back: it is very specific to my own tastes and
needs, formatting things in the different versions just the way I want
them. However, within that limitation, it is quite flexible.
Well, sorry for the long post, but you see that I can quickly and
easily make changes in any and all of my formats from one source file,
even if I had to write my own mark-ups and even though the conversion
is a bit convoluted (but that's what scripts are for :-)
See the results by looking at the various versions/formats available
here: http://www.physics.purdue.edu/~hinson/ftl/
Take a quick glance at part 1 of the FAQ in the different versions
listed near the bottom of the main page--then you can see the
graphics-rich content vs the ascii-only content.
-Jay
[
FAQ Archive |
Search FAQ Mail Archive |
Authors |
Usenet References
]
[
1993 |
1994 |
1995 |
1996 |
1997 |
1998 |
1999 |
2000
]
© Copyright The Internet FAQ Consortium, 1997-2000
All rights reserved