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.
