pdc@otter.hple.hp.com (Damian Cugley) (09/09/88)
Avoiding re-inventing the wheel
I'd like to be able to incorporate the manual pages for some programs in
a LaTeX document. It occurs to me that one way to do it would be to
have `some program' that translates the `-man' macros into a reasonable
LaTeX analogy (or perhaps texinfo?), and then \include or \input these
files.
Example: `.TH FOO 1Z ...' might become `\section{Manual entry for {\em
foo}(1Z)}', which is easy enough, `.RI' etc. are a doddle, but the `.TP'
etc. macros will need a little bit of cleverness to convert them into
descriptions with matching braces and the like:
.TP \begin{description}
.BI "\-q " wfile \item[{\tt -q }{\em wfile}]
Use Use
.I wfile {\em wfile}
as a wombat file as a wombat file
... ...
.TP \item[{\tt -z}]
.B \-z Enable zebra option
Enable zebra option ...
... \end{description}
.SH FILES \subsection*{FILES}
... ...
I looked at the various tools available and I think Emacs-LISP (with
outout to another buffer) is probably the easiest language to use for
this sort of thing. It shouldn't be too problematical, I'm just too
lazy to bother if it's already been done. ?:-)
Has anyone already done such a thing (in *any* language)? I haven't found
any obvious commands using command-apropos. Hints? Suggestions?
(Would texinfo be more useful than LaTeX or vice versa?)
PEMIS (Please-e-mail-I'll-summarise) :-)
pdc
--
/--Damian Cugley-------------------------------------\/--HP Labs----------\
| pdc@hplb.lb.hp.co.uk ...!mcvax!ukc!hplb!pdc || Filton Rd |
| pdc%otter@hplabs.HP.COM ...!hplabs!otter!pdc || Stoke Gifford |
| pdc%hplb.csn@csnet-relay.arpa (Guesses not || BRISTOL UK |
| pdc%hplb.csnet@relay.cs.net addresses :^} ) || BS12 6QZ |
\----------------------------------------------------/\-------------------/
``lsh \- a shell (command interpreter) with LISP-like syntax''jr@PIZZA.BBN.COM (John Robinson) (09/09/88)
The tr2tex program from Kamal Al-Yahya at Stanford does what you want.
Following is its own output of its own manmual page, originally in
troff -man. It is in (al least our 1988 copy of) the Unix TeX
distribution tape, under TeXcontrib/kamal/.
Since this expects to make each man page its own document, putting
this inside another document may be a tad problematic, but mainly you
will have to pick up the definitions of troffman.sty in the package
and incorporate most of them into the larger document's style.
/jr
jr@bbn.com or bbn!jr
--------
% -*-LaTeX-*-
% Converted automatically from troff to LaTeX by tr2tex on Fri Feb 20 12:05:23 1987
% tr2tex was written by Kamal Al-Yahya at Stanford University
% (Kamal%Hanauma@SU-SCORE.ARPA)
\documentstyle[troffman]{article}
\begin{document}
%
% input file: tr2tex.1
%
\phead{TR2TEX}{1}{1\ January\ 1987}
\shead{NAME}
tr2tex -- convert a document from troff to LaTeX
\shead{SYNOPSIS}
{\bf tr2tex}
[
{\bf -m}
]
{\it filename}
\shead{DESCRIPTION}
{\bf Tr2tex}
converts a document typeset in
{\bf troff}
to a
{\bf LaTeX}
format.
It is intended to do the first pass of the conversion. The user
should then finish up the rest of the conversion and customize the
converted manuscript to his/her liking.
It can also serve as a tutor for those who want to convert from
troff to LaTeX.
\par
Most of the converted document will be in LaTeX
but some of it may
be in plain
{\bf TeX.}
It will also use some macros in
{\bf troffms.sty}
or
{\bf troffman.sty}
which are included in the package and must be available to the document
when processed with LaTeX.
\par
If there is more than one input file, they will all be converted into
one LaTeX document.
\par
{\bf Tr2tex}
understands most of the
{\bf -ms}
and
{\bf -man}
macros and
{\bf eqn}
preprocessor symbols. It also understands several plain
{\bf troff}
commands. Few
{\bf tbl}
preprocessor commands are understood to help convert very simple tables.
\par
When converting manuals, use the
{\bf -m}
flag.
\par
If a troff command cannot be converted, the line that contain that
command will be commented out.
\par
NOTE: if you have
{\bf eqn}
symbols, you must have the in-line mathematics delimiter defined by
{\bf delim}
in the file you are converting. If it is defined in another
setup file, that setup file has to be concatenated with the
file to be converted, otherwise
{\bf tr2tex}
will regard the in-line math as ordinary text.
\shead{BUGS}
Many of these bugs are harmless. Most of them cause local errors
that can be fixed in the converted manuscript.
\par
-- Some macros and macro arguments are not recognized.
\par
-- Commands that are not separated from their argument by a space are
not properly parsed (e.g .sp3i).
\par
-- When some operators (notably over, sub and sup) are renamed (via define),
then they are encountered in the text,
{\bf tr2tex}
will treat them as
ordinary macros and will not apply their rules.
\par
-- rpile, lpile and cpile are treated the same as cpile.
\par
-- rcol, lcol are treated the same as ccol.
\par
-- Math-mode size, gsize, fat, and gfont are ignored.
\par
-- lineup and mark are ignored. The rules are so different.
\par
-- Some troff commands are translated to commands that require
delimiters that have to be explicitly put. Since they are
sometimes not put in troff, they can create problems.
Example: .nf not closed by .fi.
\par
-- When local motions are converted to \bs raise or \bs lower, an \bs hbox
is needed, which has to be put manually after the conversion.
\par
-- 'a sub i sub j' is converted to 'a\_i\_j' which TeX
parses as 'a\_i\{\}\_j\}' with a complaint that it is vague. 'a sub \{i sub j\}'
is parsed correctly and converted to 'a\_\{i\_j\}'.
\par
-- Line spacing is not changed within a paragraph in TeX
(which is a bad practice anyway).
TeX uses the last line spacing in effect in that paragraph.
\shead{TODO}
Access registers via
{\bf .nr}
command.
\shead{SEE ALSO}
texmatch(1), trmatch(1).
\shead{AUTHOR}
Kamal Al-Yahya, Stanford University
\end{document}jr@bbn.com (John Robinson) (09/09/88)
In article <10834.589815198@pizza>, jr@PIZZA (John Robinson) writes: [That's me!] >Since this expects to make each man page its own document, putting >this inside another document may be a tad problematic, but mainly you >will have to pick up the definitions of troffman.sty in the package >and incorporate most of them into the larger document's style. Silly me, I didn't look at it hard enough. troffman.sty is like a minor mode; the translator emits some default document type, but you can strip the LaTeX \documentstyle{}\begin{document}\end{document} wrapper trivially and add the troffman option to your outer document. -- /jr jr@bbn.com or bbn!jr