[groff] [UTROFF] references, summary, index

[Pierre-Jean]

Hello alls,

On my previous mail, I said I was willing to discuss about some
of the goodies offered with Utmac. But as I had a look at those
things, I realized that while some are effectively goodies only
useful on some rare occasions, the others are things which are
filling basic needs.  So, I’ll keep the term « goodies » for my
next mail, and will talk today about references, summaries, and
indexes.

# References
------------

Concerning references, there are habbits and standarts to follow.
The habbits are well known: if the same reference is cited
several time in a row, the macro should only write "ibid."
followed by the possible differences. If the reference has been
cited yet in another page, the macro should write "op. cit.
p. XX". The standart is less known: it is the iso-690 one, which
define mandatory fields and their order.

In Utmac, u-ref respects both those habbits and the standart. It
also indexes each of the referenced title. A modified version of
refer <http://utroff.org/man/refer.html> sorts the bibliography
list respecting the iso-690 standart. That version of refer also
uses strings to define fonts, instead of hardcoded fake small
caps.

# Summaries
-----------

In utmac, summaries are all implemented within a macro
(u-sum.tmac).  Compared to solutions which rely on moving a pdf
page from the end to the beginning of the document, this solution
has the advantage to allow the possibility to write summaries
without breaking the flow of the text: within a margin, between
a heading and the first paragraph, etc. The drawback is that two
to three passes of the troff are needed to adjust the page
numbers.

The summary is written to a file using .sy and sourced on the
next pass with .so. Internally, the hierarchical position of each
line of the summary is recorded, to may print summaries of
sub-sections.

    .\" The summary string
    .ds sum-list .
    .de sum:record
    .       \" Record the summary in a string
    .       \" This macro called by each heading
    .       \" The aim of the sum-level string is to define the hierarchical
    .       \" position of the heading : /, /1/, /1/1/, /1/2/, /1/3/, /2/, etc.
    .       as sum-list @@@sum :print \\*[sum-level] \\n% "\\*[head-text]"
    ..
    .am doc:end
    .       \" Write the summary to a file (added to the ending macro)
    .       \" the sed command creates troff macros from the summary string
    .       \" the iconv command gets around a bug in Heirloom Troff
    .       sy echo \\*[sum-list] | sed -e "s/@@@/\\\\n./g" | iconv -f latin1 
-t utf8 > /tmp/summary.tr
    ..
    .de S3
    .       \" user macro to print a summary of level 3 headings
    .       \" The aim of the sum-toprint string is to select only
    .       \" the headings of the actual section.
    .       ds sum-toprint /\\n[head-1]/\\n[head-2]/
    .       \" Source the summary
    .       so /tmp/summary.tr
    ..
    .de sum:print
    .       \" Only print the desired summary lines
    .       if "\\$1"\\*[sum-toprint]" \\$3\t\\$2
    ..


# Index
-------

To create indexes of titles, words, and everything else, Utmac
also uses the .sy and .so requests. But to format the indexes, it
calls an external script: idx.

    .sy echo "\\*[idx-list]" | sed -e "s/@@@/\\\\n/g" | iconv -f latin1 -t utf8 
> \\*[idx-file]
    .sy idx -d \\*[idx-file] > \\*[idx-file].b
    .so \\*[idx-file].b
    .sy rm \\*[idx-file] \\*[idx-file].b


The idx script can be used to help people create summaries of
paper books. The procedure is explained on the manual of idx
<http://utroff.org/man/idx.html>.

On my next, and hopefully last, mail about Utmac, I will
effectively discuss about goodies.

Kind Regards,
Pierre-Jean.