[ILUG] documentation...

[kevin lyda]

along the lines of "starman jones'" ever so useful contribution to the
community i thought i'd toss in my own.  like any programmer i really
enjoy doing documentation.  ok, that's a total lie.  but if i can play
with some amusing tools along the way it's a bit more tolerable.

anyway since i've been using troff to do another part of a project i
used it for the docs.  it's pretty nifty.  not much markup required and
i can get indexing, table of contents, etc with not much work.  the hard
part is getting docs on it but a good place to start is richard stevens'
page here:

    http://www.kohala.com/start/troff/troff.html

though it's kind of weird visiting a web page of a person who has passed
away.  one part that is a bit out of date is the section on indexing.
on my redhat box there's a program called makeindex that does the indexing
work that the collection of awk scripts mentioned on the page does.

makeindex will spew latex as well if that gets your jollies.  not that
i've tried.  however the man page is a bit off, so i include an index
style file that does work below.

in addition redhat 6.1's groff doesn't include an a4 macro for, well,
a4 type paper.  that's also included below.  just make it the first file
on the groff command line.

make handles building the document and index for postscript, pdf or even
an x previewer (groff -TX75 -t -me files.me).

finally i used the "me" macros since i could find more docs for it.
the "ms" macros look nice too, but i'm at a loss for docs for it.
pointers?

cheers,

kevin

files:

    a4.tmac:
    .\" Set up groff for A4 paper.
    .pl 27.7c
    .ll 21c-2i

    index.style:
    keyword "IX:"
    preamble
    ".\\\" start of index output
    .\\\" enter two column mode
    .pl 27.7c
    .ll 21c-2i
    .2C
    .SH
    .ce
    INDEX
    .XS
    INDEX
    .XE
    .R
    .ps 9
    .vs 11p
    .sp
    .de IS
    .B
    .ps +5
    ..
    .de IE
    .ps -5
    .R
    ..
    .de I1
    .ti 0.25i
    ..
    .de I2
    .ti 0.5i
    .."
    postamble "\n.\\\" end of index output"
    setpage_prefix "\n.nr % "
    setpage_suffix ""
    group_skip "\n.sp 1.0"
    headings_flag 1
    heading_prefix "\n.IS\n"
    heading_suffix "\n.IE"
    item_0 "\n.br\n"
    item_1 "\n.I1\n"
    item_2 "\n.I2\n"
    item_01 "\n.I1\n"
    item_x1 "\n.I1\n"
    item_12 "\n.I2\n"
    item_x2 "\n.I2\n"
    delim_0 ", "
    delim_1 ", "
    delim_2 ", "
    delim_r "-"
    delim_t "."
    encap_prefix "\\fB"
    encap_infix "\\fP\n.\\\""
    encap_suffix "\n"
    indent_space ""
    indent_length 0

-- 
kevin at suberic.net        q: what's the difference between batman & b. gates?
fork()'ed on 37058400    a: when batman fought the penguin, he won.
meatspace place: home                             http://suberic.net/~kevin/
 >> want privacy? www.gnupg.org or www.pgp.com.  encrypted mail preferred <<