Some notes on using Groff to produce a Table of Contents with the ms macros

toc_for_ms.org

Table Of Contents

Example of automatic creating of tables of contents in groff

.NH
method

.XS \" index start
method contents
.XE \" end index
.LP
this is the method maragraph
.bp
.NH 2
pethod
.XS
pethod
.XE
.LP
phis is the method maragraph
.TC \" create table of contents

Example of manual creating of tables of contents in groff

.XS 1 \" toc start with index at page 1
method contents
.XA 2 \" index at page 2
pethod
.XE \" end toc listing
.LP
.NH
method
.bp
.NH 2
pethod
.LP
phis is the method maragraph

.TC \" create table of contents on seperate page

No Auto Relocating TOC

groff -Tpdf -ms "$file" > "$base".pdf

pdfroff -Tpdf -ms "$file" > "$base".pdf

Using mspdf to Generate TOC

Automatic TOC Using mspdf

.NH
.XN "method"
.LP
hello
.NH 2
.XN "pethod"
.LP
phis is the method maragraph
.TC \" create table of contents

No Auto Relocating TOC

groff -Tpdf -mspdf "$file" > "$base".pdf

No Auto Relocating TOC alternative

groff -Tps -mspdf "$file" | ps2pdf - > "$base".pdf

Auto Relocating TOC alternative using pdfroff

pdfroff -mspdf "$file" > "$base".pdf

@Gavinok none of these handles the case when you want to put TOC after the title/cover page. Do you know how to achieve this? Also do you know how to handle the page shift when the TOC is placed at the beginning? The TOC is placed at the beginning, but the page numbers in the document are not updated accordingly.

@m-kru Unfortunately I do not. I have to admit dealing with how groff handles the TOC is a pain. The best option is to do the non auto relocated approach and do it manually. This is the reason I just wrote my own solution for neatroff https://github.com/Gavinok/neatroff_toc . Not a complete solution unfortunately. I have considered digging into the macros and making this a little more flexible but haven't gotten around to id. I am not sure if you already took a look at it but I'd recommend digging through the mailing list archives https://lists.gnu.org/archive/html/groff/

Personally I use groff for quick things like notes and simple markup but use neatroff for anything I need complex formatting like this since neatroff is substantially nicer to hack on in my experience. Since I use org more these days I don't use groff it's self all that often.