groff
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: How to use refer macros-agnostic way?


From: Tadziu Hoffmann
Subject: Re: How to use refer macros-agnostic way?
Date: Wed, 8 Jan 2020 03:33:10 +0100
User-agent: Mutt/1.11.4 (2019-03-13)


[I'm forwarding this to the list because I think it might be of general 
interest.]


> 1. Do the macros you made assume the use of refer.tmac?

No, they provide similar functionality[*], but they're a
completely separate and independent implementation of that
functionality.

[*] Once they are properly fleshed out, of course.

> I quess that groff -R automatically activates refer.tmac and
> all registers like [F become available. Correct?

No, -R only filters the input document through the "refer"
preprocessor before processing it with the actual formatter
"troff".  Support macros must be either loaded by the document
itself or requested with the -m command-line option of groff.

refer.tmac just contains shared macros that are loaded by
refer-m{e,m,s}.tmac, which in turn are loaded by {e,m,s}.tmac.


> 2. Can you also give an example of correct macros invocation
> inside a real document?

You don't invoke these macros yourself.  You just define them,
and they are then invoked by the troff code generated by refer.

To see how this works, Just run "refer test.troff" and look
at the output.  You will see that refer replaces the block

  .[
  $LIST$
  .]

by code which defines some strings and invokes the macros
.]<, .]>, .]-, and .][.  These are the macros you must provide
(either yourself or via a general-purpose macro package that
defines them) in order to typeset the bibliography.


> Generally, refer documentation is too scarce. I could
> see in man refer the following:

> 1) a brief description of the refer/refer.tmac operation principle
> (that refer uses macros like refer.tmac and refer-m*.tmac is not
> mentioned al all!);

That's because the "refer" program does not use these macros.
Refer simply generates troff code that calls the macros,
and therefore you (or your macro package) have to provide
them in order for troff to be able to format the bibliography.

Of course, the idea behind separating these two processing
steps is flexibility: the style in which the bibliography is
typeset is completely independent of the refer program itself.
If you don't like the style in which the bibliography is
formatted, you can simply replace these macros by some
that format the bibliography the way you want it.

> 2) list and description of the internal registers;
> 3) instructions on the citation formatting principle and customization.

This information is provided so that you can write the
corresponding bibliography-formatting macros.  :-)

> I will be happy to add the corresponding information to fix
> the refer man file once I understand the stuff myself.

In my opinion, the manual page is perfectly adequate, if you
accept that it is not a tutorial but rather a reference manual
that you refer to for particular details of implementation or
invocation.  In fact, all of the manual pages for troff-related
utilities assume that you're already familiar (at least in very
broad terms) with the basic ideas of how the utilities are
meant to be used.  These things are described in the various
Bell Labs papers and memos.  For example, troff.org lists
M. E. Lesk's "Some Applications of Inverted Indexes on the
UNIX System" as providing a basic overview of how refer works.





reply via email to

[Prev in Thread] Current Thread [Next in Thread]