Re: [Groff] pdfmark XN help

[Keith Marshall]

On 27/01/16 18:46, Larry Kollar wrote:
> 
>> Anton Shterenlikht <address@hidden> wrote:
>>
>> I discovered pdfmark macro today.
>> I like it, and would like to use it's
>> facilities for hyperlinking and automatic
>> table of contents.
>>
>> However, pdfmark.pdf included in groff-1.22.2
>> stops just at this point.
>> Section 3.1.1.1. "The XN Macro" is empty,
>> as are all subsequent sections.

That document is intended as an example, to be read in conjunction with
its source file, pdfmark.ms; it isn't abandoned, but I had to put it on
hold, when it got to that point, and I simply haven't managed to find
time to progress it further since then.

>> The intro says that this document was produced
>> with groff-1.19.1.
> 
> The source file, pdfmark.ms, uses it and includes voluminous
> commands about how to use it. It works like this:

I guess Larry means "comments" here, rather than "commands".

> .NH 2
> .XN This is the Heading
> .LP
> etc….
> 
> You can also specify a named PDF link destination, if you need to
> cross-reference back to the section:

You can, but not quite like this:

> .NH 2
> .XN thisplace -- This is the Heading
> .LP

The correct syntax would be:

  .NH 2
  .XN -N thisplace -- This is the heading
  .LP

The "-N" option is required here, to identify the following macro
argument as a name to be used to refer to the current PDF location.

> Put a .TC at the end of your document to output the table of contents.
> I’m not sure if pdfmark relocates the Table of Contents for you, but it
> does appear in the right place in the PDF file.

No, pdfmark doesn't, but if you use pdfroff rather than groff, then it
will take care of TOC relocation for you; you will also need to use
pdfroff, (or Deri's "-Tpdf" capability), to properly format active cross
references within the document body.

Finally, if you are using pdfroff, and you are *not* using ms' .TC to
generate a table of contents, then you may need the --no-toc-relocation
option, to prevent insertion of a second copy of your document instead
of the TOC; see "man pdfroff" for more details.

-- 
Regards,
Keith.