[9fans] troff macros for typesetting books/longer texts
Rudolf Sykora
please, does somebody know of any troff macros that were used to typeset books?
Can one get hold of e.g. macros used to typeset e.g. "The AWK
Programming Language" by Aho, Kernighan and Weinberger, or “The Unix
Programming Environment” by Kernighan and Pike?
I want to particularly know how headings were programmed. I.e., how
the name of a chapter that is only to appear on a page gets to its
heading. I feel that either the file must be processed twice, or one
must write a heading of a page only when the page is about to be
completed (one would then back up to the heading position, write it,
and only then continue).
Thanks
Ruda
Lyndon Nerenberg
Richard Stevens' notes on typesetting (TCP Illustrated et al) at
http://www.kohala.com/start/ (see the 'Typesetting' section towards the
end of that page).
--lyndon
Rudolf Sykora
> http://troff.org has some good information. I especially recommend Richard
> Stevens' notes on typesetting (TCP Illustrated et al) at
> http://www.kohala.com/start/ (see the 'Typesetting' section towards the end
Actually, I know of both mentioned places. But, as far as I know, the
very macros are not discussed anywhere. But I may be, of course,
wrong.
Thanks
Ruda
Lyndon Nerenberg
> very macros are not discussed anywhere. But I may be, of course,
> wrong.
My guess is these works fall into two categories:
1) the author uses (say) ms, and extends it with macros in the document
source code to achieve the bits that pure ms doesn't provide.
2) the author starts with (say) ms, then customizes it for the specific
task at hand.
In either case, the customizations are locked in with the document source
and don't get distributed. Or they are so tied in with a specific document
that they're of no practical use as standalone tools.
I've done both when writing documentation, and in all those years I've
never come up with a macro package specifically for that task. The reason
being there is too much variablity in what I need. The effort it would
require to write a general purpose macro package to encompass all those
variations would be self defeating. It's considerably faster (for me) to
do these customizations on a per-document basis.
Over the years I have developed patterns in how I design these one-offs,
but the results are never quite the same between any two documents.
I usually use ms as the scaffolding, writing additional macros to provide
the higher level concepts (e.g. chapters). While it's possible to muck
around inside the ms macros themselves, the result isn't portable. I've
learned to be careful not to get too caught up in trying to make ms do
things it doesn't want to. Sometimes it's easier to just write your own
macro set for the specific task at hand. (Re-implementing basics like .LP,
.PP, .IP, .SH, etc. is quite easy if you don't require all the
generalizations ms provides.)
--lyndon
tlar...@polynum.com
> [...]
>
> In either case, the customizations are locked in with the document source
> and don't get distributed. Or they are so tied in with a specific document
> that they're of no practical use as standalone tools.
>
This is a general pattern. I'm not a troff but a TeX user, and just
seeing that learning how to use the full potential of TeX to match
my own needs was easier, shorter in time, and less expensive---because
of D.E. Knuth's TeXbook---than trying to learn how to _use_ some
instance of LaTeX, I still don't understand why others...
I know that it is less effort to climb a mountain via a lengther but
less sloping road... but it must not be endless because flat and must
reach the top.
The best thing I learnt while aging is not how to do more efficiently,
but how to have time doing knowing where to look for the needle stopping
to search the internet hay stack.
If there is no good short authoritative book on troff, and if you are
not already proficient in troff, try TeX instead simply because of the
TeXbook if not something else.
--
Thierry Laronde <tlaronde +AT+ polynum +dot+ com>
http://www.kergis.com/
Key fingerprint = 0FF7 E906 FBAF FE95 FD89 250D 52B1 AE95 6006 F40C
tlar...@polynum.com
>
> If there is no good short authoritative book on troff, and if you are
> not already proficient in troff, try TeX instead simply because of the
> TeXbook if not something else.
And mind you, I know for sure there is TeX for Plan9---even if I'm the
only one interested in it; but it is published as a side effect of my
own needs, not as a goal.
erik quanstrom
>> If there is no good short authoritative book on troff, and if you are
>> not already proficient in troff, try TeX instead simply because of the
>> TeXbook if not something else.
>
> And mind you, I know for sure there is TeX for Plan9---even if I'm the
> only one interested in it; but it is published as a side effect of my
> own needs, not as a goal.
the Teχbook may be authoratative, but it's by no means short.
- erik
tlar...@polynum.com
> >>
> >> If there is no good short authoritative book on troff, and if you are
> >> not already proficient in troff, try TeX instead simply because of the
> >> TeXbook if not something else.
> >
> > And mind you, I know for sure there is TeX for Plan9---even if I'm the
> > only one interested in it; but it is published as a side effect of my
> > own needs, not as a goal.
>
You can get started with the very first chapters. And once you stumble
upon something more special, you pick up the book.
300 pages without the appendices, and with exercices it's short; and
exhaustive. Compare with books about "LaTeX".
Bakul Shah
>
> If there is no good short authoritative book on troff, and if you are
> not already proficient in troff, try TeX instead simply because of the
> TeXbook if not something else.
Most TeX users are actually latex users, not raw TeX so the
TeXbook is not terribly useful. But there are good books on
latex and there is a wealth of material online (& many
packages that work with latex). With TeXworks and TeXshop on
the Mac writing latex docs has become more pleasant.
Still, it is much easier to learn to use troff (speaking as a
user; never tried writing a macro package for it). A lot of
things "just work".
tlar...@polynum.com
>
> Most TeX users are actually latex users, not raw TeX so the
> TeXbook is not terribly useful. But there are good books on
> latex and there is a wealth of material online (& many
> packages that work with latex). With TeXworks and TeXshop on
> the Mac writing latex docs has become more pleasant.
>
> Still, it is much easier to learn to use troff (speaking as a
> user; never tried writing a macro package for it). A lot of
> things "just work".
I'm not an integrist, and as long as someone is comfortable with troff,
I don't see why he should switch to TeX. The converse is true.
But most of the "difficulties" with TeX come precisely because this is
not "plain" TeX: plain TeX (i.e. the macros from D.E. Knuth) just work
too. But TeX is hidden---see the comments I received at first: "why do
you want to make a TeX package? People only use LaTeX..."
And I think that I have the right to say that if some people had really
grasped TeX and al., they would never have done the mess the
distributions of the system are now.
erik quanstrom
>
> You can get started with the very first chapters. And once you stumble
> upon something more special, you pick up the book.
>
> 300 pages without the appendices, and with exercices it's short; and
> exhaustive. Compare with books about "LaTeX".
i'm going to call this the "latin is easy" theory.
cantonese and arabic are much harder to learn.
☺
> But most of the "difficulties" with TeX come precisely because this is
> not "plain" TeX: plain TeX (i.e. the macros from D.E. Knuth) just work
> too. But TeX is hidden---see the comments I received at first: "why do
> you want to make a TeX package? People only use LaTeX..."
most of the difficulties of teχ are because
it's a macro language. macros don't scale.
dek did a wonderful job, but you just can't
paper over the fact that all this wierd macro
expansion is going on.
- erik
Jacob Todd
There's 'Document formatting and Typesetting on the Unix System, Vol. I &II' by Narain Gehani and Steven Lally. They're available on alibris at a cheap price. I unfortunately haven't had time to read them yet. I know there's also more listed at troff.org.
Anthony Sorace
There's 'Document formatting and Typesetting on the Unix System, Vol. I &II' by Narain Gehani and Steven Lally. They're available on alibris at a cheap price. I unfortunately haven't had time to read them yet. I know there's also more listed at troff.org.
pmarin
"A TROFF Tutorial" by Kernighan. (http://www.kohala.com/start/troff/troff.html)
A great and complete book with macros like you are looking for is
"Unix Text Processing". You can download it from
http://oreilly.com/openbook/utp/
Rudolf Sykora
This is the argument I'd stand by.
I read the TeXBook and used (plain)Tex much before ever touching
troff, thus I have a good idea about how it is written and explained.
Being a physicist, I use latex for writing articles. I have discovered
troff much later, basically because of plan9 (I had known of troff's
existence, sure, but never thought of trying it out). Basically,
seeing the conciseness and lucidity of works by Kernighan (eqn, tbl
documentation)---few extremely nice pages you can read over a
coffee---made me plunge into the troff's waters.
As I said many times, TeX is superior in (mainly math) quality.
However, troff and its preprocessors (eqn, tbl, grap,...) seem smaller
and more elegant to me. Eqn input is rather legible in the source
(even more with the ability to use utf-8 letters in place of e.g.
alpha; but this I think is now possible in some versions of TeX, too,
I believe).
Note, that neither plainTex nor troff handle cross-references,
automatic equation numbering, footnote numbering, table of contents,
etc. Nonetheless, mainly these listed features are often so needed.
One way out has been latex, which shows, in my opinion, how things
should not be done. There is also eplain, a much better choice for me
(plain extended with the mentioned almost always wanted features, and
some most frequent latex macros like graphix). What I am trying to get
is something like eplain, but for troff. And I wanted to have a look
at how some things are to be done. And to not invent a wheel, I asked
for some *simple* macros, which must have been used e.g. in the
mentioned books in my 1st contribution.
Just now I am reading "Unix Text Processing" by Dale Dougherty and Tim
O'Reilly, a freely available book (pmartin proposes it as well). There
are several chapters on the topic, so perhaps I'll get what I want in
the end.
Thanks
Ruda
Steve Simon
> by Narain Gehani and Steven Lally. They're available on alibris at a cheap
> price.
secconded, excellent books.
R.S. Bourne's "The Unix System" has some macros for writing books in it, though I
was never clear wether these where used to typeset the book itself or if they
are just a simplified example.
-Steve
tlar...@polynum.com
>
> Note, that neither plainTex nor troff handle cross-references,
> automatic equation numbering, footnote numbering, table of contents,
> etc. Nonetheless, mainly these listed features are often so needed.
Well I use a package called... MisTeX (my own), that is simply some
macros doing this and ridding piggy-back on plain TeX. (And BibTeX
added to kerTeX is compatible with plain TeX; cross references for
pdf are here with a macro file and support from dvips(1); the
footnote are explained in the TeXbook etc.)
But as I said before, this is not for me a religious case. It happens
that I made my way with TeX (LaTeX was not my cup of tea from the very
beginning) without knowing troff.
Stevens' books were made with troff and ed(1) IIRC, and they are
worth reading for Unix/POSIX programming, and pleasant to read due to
their presentation/formatting.
Rudolf Sykora
> that I made my way with TeX (LaTeX was not my cup of tea from the very
> beginning) without knowing troff.
Anyway, I do keep an eye on what you do with KerTeX. I appreciate
this. Having seen those >1GB TeX distributions out now... it's
definitely uplifting to see something saner.
Ruda
Lyndon Nerenberg VE6BBM/VE7TFX
> O'Reilly, a freely available book (pmartin proposes it as well). There
> are several chapters on the topic, so perhaps I'll get what I want in
> the end.
I was going to mention that one, but I figured it was so long out of
print as to be unobtainable. I should know better, though.
abebooks.com has found me a wealth of long out-of-print UNIX material.
My moment of truly understanding troff was when I stopped thinking of
it as a typesetting program, and instead recognized it as a
programming language. After that little epiphany, much of the smoke
cleared. If you re-read the troff paper in that light, a syntax that
initially appears to be line noise magically transforms itself into a
concise and elegantly consistent language. There's no denying it's
cryptic, though. But once you recognize the consistency of the
syntax, it's a marvel to behold.
There's no denying it has its warts. Number registers that are strings
still offends my sensibilities, but as with irregular verbs, pretty
soon you just learn to accept them and carry. But the one bit of troff
black magic I still can't get my head around, even after 25 years, is
how the hell .wh page-bottom traps are supposed to work :-P
As for indexes, the me macro package provides macros for
generating index entries: .(x and .)x. You can look in
/sys/lib/tmac/tmac.e to see how they are defined. Plan 9 doesn't
seem to provide any documentation for the me macros, though. I'm
pretty sure Stevens talked about index creation on his web site, and
you might want to check Brian Kernighan's web pages as well.
--lyndon
Stanley Lieber
I'm currently in the process of re-typesetting my books using troff. Once
completed, I plan to make the troff sources and build system available
alongside the output.
The links mentioned in this thread are basically the same documents
I've worked from during this process. In addition, I purchased the Gehani
books a while back; they contain a lot of helpful information, although
Gehani seems to favor mm over ms.
-sl
Rudolf Sykora
> pretty sure Stevens talked about index creation on his web site, and
> you might want to check Brian Kernighan's web pages as well.
>
> --lyndon
Yes, that's true. He discusses an index production. Basically, if I
remember, he uses software described in "Tools for printing indexes"
by Bentley & Kernighan.
Ruda
Brian L. Stuart
> cross-references,
> automatic equation numbering, footnote numbering, table of
> contents,
> etc. Nonetheless, mainly these listed features are often so
> needed.
> trying to get
> is something like eplain, but for troff. And I wanted to
> have a look
> at how some things are to be done. And to not invent a
> wheel, I asked
> for some *simple* macros, which must have been used e.g. in
> the
> mentioned books in my 1st contribution.
I'd suggest digging around for macro sets people created for
various schools' thesis and dissertation formats. I expect
several of us have done that and have included auto numbering
of chapters, sections, equations, tables, figures, etc. If
I look hard enough, I might even be able to find the ones I
did 20 some-odd years ago for my master's thesis, but I'm
pretty sure I won't get able to get to it until at least this
weekend.
BLS
Rudolf Sykora
> various schools' thesis and dissertation formats. I expect
> several of us have done that and have included auto numbering
> of chapters, sections, equations, tables, figures, etc.
Well, I tried google... and... :( That's why I asked.
I actually know how to do the numbering of eqs, figures, tables (all
the same principle, I use a ~10-line awk/sed script to do this),
chapters (for this slightly modified .NH is ok). I know to use 'refer'
for references (I believe it won't be hard to write a script to
translate bibtech references to refer's), even index production
shouldn't be difficult with the help of Bentley's paper (and I guess I
even won't need this right now).
I have only hesitated over the way (as described in my original, 1st,
post) how references that *depend on physical placement* of certain
text are to be coped with. (As with my page headings; or---probably
even harder so that at least 2-runs of troff are
inevitable---references to page numbers where sth is mentioned. But I
really need just the headings now.)
Thanks!
Ruda
Lyndon Nerenberg VE6BBM/VE7TFX
> post) how references that *depend on physical placement* of certain
> text are to be coped with. (As with my page headings; or---probably
> even harder so that at least 2-runs of troff are
> inevitable---references to page numbers where sth is mentioned. But I
> really need just the headings now.)
For page headers and footers, the tutorial section in the Troff paper
should have enough to get you going (/sys/doc/troff.ps, pages 34 on).
For section and index cross-references to page numbers, you pretty
much have to do two passes, writing the xref data to an external file
that gets read in the table of contents or index sections as
appropriate. (You read and write the xref data file from inside troff
itself using .so and .tm.)
For what it's worth, spending a couple of days studying the ms macro
package source code should give you a lot of ideas. And a headache
;-)
--lyndon
Steve Simon
> translate bibtech references to refer's
I have a refer contrib package, mostly based on forsyth's port but which
includes a few tweeks and bib2ref.c which attempts, rather naïvely, to do
this translation.
-Steve
erik quanstrom
i put both on my system last year for iwp9, but they were in
such poor shape (at least the copies i got), that i removed
them.
i think everybody would appreciate one xor the other cleaned up,
de-pccified and added to the distribution.
- erik
Allan Heim
as a typesetter. I swore by my copy of Word Processing on the UNIX
System by Morris Krieger, and I'm shocked to not see it listed at
http://www.troff.org/books.html but a Google search shows that used
copies are still available, and at reasonable prices.
If you want to go the plain TeX route, I _strongly_ recommend Arvin
Borde's books, TeX By Example and Mathematical TeX By Example. The
books' conceit is to show typeset text on one page, and the source code
used to generate that text on the facing page--such an obvious idea.
Those, plus The TeXbook, are sure to help someone become a solid wizard.
hiro
de-pccified and added to the distribution.
I like this use of languages :)
The thread is getting big. Perhaps simply learning troff/tex is indeed easier.
But I really am no typesetter, just a simple computer user.
Tex is yet an other language, Latex too complicated, Microsoft Word
too ugly, Troff macros not in a good state...
What can I use?
Gabriel Diaz
html?
For those who use math in their docs, this might be of interest:
http://www.mathjax.org,
gabi
Aharon Robbins
sets on top of TeX, but you don't have to know TeX. (I've been using
Texinfo for > 20 years, but don't know any TeX.)
I've written books in troff, Docbook/XML, and Texinfo, and Texinfo is
by far the easiest.
HTH,
Arnold
--
Aharon (Arnold) Robbins arnold AT skeeve DOT com
P.O. Box 354 Home Phone: +972 8 979-0381
Nof Ayalon Cell Phone: +972 50 729-7545
D.N. Shimshon 99785 ISRAEL
erik quanstrom
> I really like the GNU project's Texinfo markup language, which
> sets on top of TeX, but you don't have to know TeX. (I've been using
> Texinfo for > 20 years, but don't know any TeX.)
>
> I've written books in troff, Docbook/XML, and Texinfo, and Texinfo is
> by far the easiest.
i never could get past the fact that texbook reeks of hubris
and nih, nor forgive gnu for using info as an excuse for not
having man pages. that, and the fact that it's at least 100x
slower than troff, and the reader requires cursor addressing.
- erik
Lucio De Re
>
> i never could get past the fact that texbook reeks of hubris
> and nih, nor forgive gnu for using info as an excuse for not
> having man pages. that, and the fact that it's at least 100x
> slower than troff, and the reader requires cursor addressing.
>
++L
pmarin
realized that they couldn't write a decent man page for their tools
so they invented the info pages and the --help flag.
dexen deVries
> My theory is that GNU tools were so bloated by design that they
> realized that they couldn't write a decent man page for their tools
> so they invented the info pages and the --help flag.
coil!dexen!~ $ 9 man rc | wc -l
496
coil!dexen!~ $ man bash | wc -l
5351
coil!dexen!~ $ zcat /usr/info/bash.info.gz | wc -l
10348
coil!dexen!~ $ 9 man mk | wc -l
416
coil!dexen!~ $ zcat /usr/info/make.info* | wc -l
12306
--
dexen deVries
[[[↓][→]]]
``In other news, STFU and hack.''
mahmud, in response to Erann Gat's ``How I lost my faith in Lisp''
http://news.ycombinator.com/item?id=2308816
John Floren
love with ITS's documentation system (which was pretty good for its
time, I admit) that he decided to clone it for Unix.
Could the bloat of GNU tools merely be a ploy by rms to force people
into using info? :)
John
John Floren
That's a screenshot of Info running on an ITS system :)
John
Bakul Shah
I am with you on Texinfo, and manpages are vastly preferable
over info files but TeX/latex can be used to produce some
beautiful text. See "The Beauty of Latex" page for some
examples:
http://nitens.org/taraborelli/latex
For a much larger example:
http://www.duo.uio.no/publ/informatikk/2008/81971/uggedal.pdf
Lyndon Nerenberg VE6BBM/VE7TFX
> realized that they couldn't write a decent man page for their tools
> so they invented the info pages and the --help flag.
In fairness to info, you have to consider its history. The want was
to be able to present an online edition of some large documents (the
emacs documentation), with cross-references, search capabilities,
index lookups, etc. This was long before the web was even a glimmer
in anyone's eye. In that regard, it was a spectacular success. Being
able to jump around a 400+page document in real time on a VT100
plugged into a Sun 3/50 workstation is a testament to that.
The standalone implementation suffers from being keystroke compatible
with the emacs lisp implementation. Those of us who grep up on emacs
can find our way around. For anyone else, I can't imagine how they
manage to use it.
But as others have said, treating info as a replacement for man pages
is arrogance beyond any rational description. Then again, the quality
of documentation for most GNU software matches that of the code.
--lyndon
erik quanstrom
> to be able to present an online edition of some large documents (the
> emacs documentation), with cross-references, search capabilities,
> index lookups, etc. This was long before the web was even a glimmer
> in anyone's eye. In that regard, it was a spectacular success. Being
> able to jump around a 400+page document in real time on a VT100
> plugged into a Sun 3/50 workstation is a testament to that.
i take this as another strike against info. the fact that one
sees that the editor's docs are 400+ pages, and there's no easy
way to cut that down to a man page, and yet they proceeded to
build bloatware to accomidate bloatware.
it's like instead of taking a bath, you buy a monster air filter,
so no one will notice the stench.
- erik
Lyndon Nerenberg VE6BBM/VE7TFX
> sees that the editor's docs are 400+ pages, and there's no easy
> way to cut that down to a man page, and yet they proceeded to
> build bloatware to accomidate bloatware.
That's like blaming Mozilla because you choose to read Sarah Palin's
missives with Firefox.
--lyndon
erik quanstrom
your defense of info was that it was built to be
read a 400+ page reference for emacs. my claim is
that if you find a reasonable editor, you won't have
a need for info.
- erik
Michael Kerpan
> Well, I think it's more that Richard Stallman was so ridiculously in
> love with ITS's documentation system (which was pretty good for its
> time, I admit) that he decided to clone it for Unix.
>
> Could the bloat of GNU tools merely be a ploy by rms to force people
> into using info? :)
To be fair, Unix tools were getting bloated even without GNU (cat -v,
anyone?). GNU just introduced the
--verbose-lispmachine-style-option-syntax to the mess. Frankly, I
think that's the problem with a lot of GNU stuff: it was made by RMS
and other folks who mainly came out of the PDP-10 and LISP Machine
tradition which doesn't really mesh well with the Unix tradition.
Programs with lots of options were IMPORTANT when your shell
environment was really just a hacked up version of a debugger from the
mid-60s because you didn't have things like pipes to make programs
play nice together. On the other end, having a verbose syntax didn't
really matter when you were working with a smart LISP system or TWENEX
or some other system with really good completion support. Thus the
problems with GNU can be directly traced to the fact that it was
written by people with brains scrambled by DDT on the one hand and
spoiled by TWENEX and standalone LISP on the other.
Mike