Usenet 1994 January/usenetsourcesnewsgroupsinfomagicjanuary1994.iso/sources/unix/volume6/lbl/doc/lbl.doc

Text File | 1986-11-30 | 10.6 KB | 464 lines

          LBL - Symbolic Labels in Text Documents





1.  Introduction

     _l_b_l is a pre-processor for _t_r_o_f_f and _n_r_o_f_f which allows
Sections,  Figures,  Tables,  etc.,  to  be  referred  to by
symbolic names rather than  by  absolute  number.   It  will
handle forward references as well as backward ones.

     Uses of  a  label  in  the  text  are  indicated  by  a
delimiter  character (default '@', but resettable), followed
by a _t_y_p_e name (e.g. "TABLE", "EQN", etc.), followed by  the
label itself (e.g. "Profits-1983").  Each such occurrence is
replaced  by  a  reference  number;  the  default  style  of
numbering  is  a sequence of period-separated arabic numbers
(e.g. 2.4.1)  but  this  is  resettable.   Finally,  another
delimiter is required to close the reference (cf. the use of
delimiters in _e_q_n for in-line equations).

Examples:

        For full details refer to Table @TABLE Profits-1983@.
        As we saw in Chapter @chap intro@, ...
        Figure @fig wing-profile@ shows the airflow patterns ...


     Labels may be defined at any point in  the  text.   The
definition looks like a _t_r_o_f_f macro, and the definition line
is retained in the original text.   By  default,  the  macro
used  is  ".L=",  but  this can be reset.  The macro takes 3
arguments: a type-name, a level-number, and a label-name.

     The type-name corresponds to  that  used  to  signal  a
label  occurrence  in  the text.  There is no restriction on
the choice of name; any sequence of non-blank characters may
be used.  Upper- and lower-case letters _a_r_e distinguished.

     The  level-number  corresponds  to   the   header-level
numbers  used  by  the .NH macro in _m_s, the .sh macro in _m_e,
etc.  The index at the given level is incremented by 1,  and
all higher indexes set to 0.  Initially, all indexes are set
to 0 by default, but other starting values  may  be  chosen.
There is an implementation-defined restriction on the number
of levels of index (currently 20);  it  is  not  anticipated
that this will lead to problems.

     The label may be any sequence of non-blank  characters;









                           - 2 -


the   same  label  may  be  used  in  more  than  one  type.
Furthermore, the special label-name ``*''  can  be  used  to
increment  the  appropriate level-counter without defining a
label at all; this is useful, for example, when all  tables,
figures,  etc.,  in  a section take their initial index from
the section number: two ways of doing this would be:

a.
    .L= section 1 this-section
    .L= last table 0
    .L= last figure 0
    ...
    ... refer to table @section this-section@.@table profits@ ...
    ... see figure @section this-section@.@figure structure@ ...
    ...
    .L= table 1 profits
    ...
    .L= figure 1 structure
    ...

(see section 3 for the use of
``.L= last ...'')

b.
    .L= section 1 this-section
    .L= table 1 *
    .L= figure 1 *
    ...
    ... refer to table @table profits@ ...
    ... see figure @figure structure@ ...
    ...
    .L= table 2 profits
    ...
    .L= figure 2 structure
    ...

It is largely a matter of taste which technique is used; the
former  is more long-winded, but avoids the need to remember
to keep the tables  and  figures  in  step  every  time  the
section is updated.  Yet a third possibility (similar to the
first) would be:

c.
    .L= section 1 this-section
    .ds Sc "@section this-section@
    .L= last table 0
    ...
    ... refer to table .@table profits@
    etc.

making use of the string-definition facility within _n_r_o_f_f.

     It is important to be  aware  that  all  processing  on
labels  is done before _t_r_o_f_f processes the text; attempts to









                           - 3 -


build label-references by  using  macros  or  _t_r_o_f_f  strings
registers will almost certainly not work as expected.

2.  Command Line Options

     Options to _l_b_l are set in the command line,  which  has
the form

        lbl [ -d_d_e_l_i_m ] [ -m_m_a_c_r_o ] [ -l ] [ -s ]


-d   _d_e_l_i_m  is  the  character  used  to   delimit   in-line
     occurrences of label references (default ``@'');

-m   _m_a_c_r_o is the 2-character name of a  _t_r_o_f_f  macro  which
     introduces label definitions, etc. (default ``L='');

-l   causes a listing of label-definitions to be written  to
     the  standard error stream.  Each label-type is listed,
     together with its print format, followed by a line  for
     each  label  of that type, showing label-name, file and
     line where it is defined, and value;

-s   causes the generation of the _t_r_o_f_f  input  file  to  be
     suppressed; setting -_s automatically also sets -_l.

3.  Control directives

     In addition to defining labels, the .L= macro  (or  its
substitute)  can  be used for several other purposes.  These
are all indicated by commands of the form

        .L= _c_o_m_m_a_n_d _a_r_g_u_m_e_n_t ...

where the _c_o_m_m_a_n_ds are reserved words which may not be  used
as  type-names.   These  commands  allow  control  over  the
initialisation of label values, the print format of  labels,
and thelabel reference delimiter.

.L= delimiter off
     turns off interpretation  of  the  delimiter  character
     altogether;  subsequent  text is copied literally until
     another _d_e_l_i_m_i_t_e_r command is encountered;

.L= delimiter _c_h_a_r_a_c_t_e_r
     resets the delimiter in subsequent text  to  the  given
     character;

.L= format _t_y_p_e_n_a_m_e _s_t_r_i_n_g
     sets the print format for labels of the  given  type  -
     see section 3.1;

.L= last _t_y_p_e_n_a_m_e _c_o_u_n_t_1 _c_o_u_n_t_2 ...
     resets the counters for _t_y_p_e_n_a_m_e  as  though  the  last









                           - 4 -


     label  generated  had  been  _c_o_u_n_t_1._c_o_u_n_t_2... (with all
     omitted counts taken as 0).

3.1.  Print formats

     The default print format for a label is as  a  sequence
of  period-separated  arabic  numerals.  However, it is also
possible  to  specify  alphabetic  or  roman  labels,  or  a
mixture,  and  to have separators other than a period.  This
is governed by the format given in a ``.LE format'' command.

     Such a format contains escape sequences (flagged  by  a
``%'' character) and literal text.  The text is copied until
an escape  sequence  is  encountered;  such  a  sequence  is
replaced by the index for the next level of the label value,
printed in one of the following formats:

%1   Arabic  numerals   (without   non-significant   leading
     zeros);

%0   As %1, but offset by 1 so that the first value  printed
     will be 0 rather than 1;

%a   Lower-case alphabetics, starting  at  ``a'';  ``z''  is
     followed by ``aa'', etc.;

%A   Upper-case alphabetics;

%i   Lower-case roman numerals (with some  odd  choices  for
     large  numbers,  consistent  with  the  roman  numerals
     printed by _t_r_o_f_f).

%I   Upper-case roman numerals.

A ``%'' followed  by  any  other  character  (in  particular
another ``%'') prints as that character.

4.  Limits

     _L_b_l imposes  no  limit  on  the  size  of  text  to  be
processed,  but  (like  _r_e_f_e_r)  needs  to act on a text as a
whole, rather than processing individual files.   The  limit
on  the  number  of  levels of header is unlikely to prove a
problem.  The number of labels which may be used is  limited
only by the amount of memory available to a process; even on
a small machine it is possible to handle a few hundred label
definitions.

5.  Further Examples

     The copying of the definition macros makes it  possible
to use them as _t_r_o_f_f macros, as in the following example:











                           - 5 -



        .de L=
        .ie '\\$1'sec' .NH \\$2
        .el .ie '\\$1'table' .if !'\\$3'*' \{
        .DS C
        Table '\\$3' about here
        .DE
        \}
        .el .if '\\$1'fig' .if !'\\$3'*' \{
        .DS C
        Figure '\\$3' about here
        .DE
        \}
        ..
        .nr LL 5i
        .ND
        .TL
        Example of LBL
        .L= sec 1 intro
        Introduction
        .L= table 1 *
        .PP
        We begin with a small table (Table @table opening@).
        .L= table 2 opening
        and consider things in more detail in Section
        @sec cont@.
        .L= sec 1 cont
        Continuation
        .L= table 1 *
        .PP
        In this continuation we refer back to Section
        @sec intro@, which contained
        Table @table opening@, and present more detailed
        information in Table
        @table detail@.
        .L= table 2 detail
        .L= sec 2 subcont
        Sub-continuation
        .PP
        In which we further refine things, as shown in
        Table @table mega-detail@ below.
        .L= table 2 mega-detail

In the above, the ``.L= sec'' macros automatically  generate
the numbered headings by expanding to the _m_s ``.NH'' macros,
while the  ``table''  definitions  cause  the  insertion  of
figures such as

                 Table 'detail' about here

The above example thus produces the following:












                           - 6 -



                          Example of LBL





        _1.  _I_n_t_r_o_d_u_c_t_i_o_n

             We begin with a small table (Table 1.1).


                    Table 'opening' about here

         and consider things in more detail in Section 2.

        _2.  _C_o_n_t_i_n_u_a_t_i_o_n

             In this continuation we refer back to Section
        1,  which  contained  Table  1.1, and present more
        detailed information in Table 2.1.


                    Table 'detail' about here



        _2._1.  _S_u_b-_c_o_n_t_i_n_u_a_t_i_o_n

             In which we further refine things,  as  shown
        in Table 2.2 below.


                  Table 'mega-detail' about here


     The alphabetic formats may be useful for such things as
appendices, e.g.

        .L= format appendix %A
        .L= appendix 1 trade-marks
        .SH
        Appendix @appendix trade-marks@:
        List of Registered Trade Marks
        .LP
        (For the addresses of the proprietors see
        @appendix props@).
          ...
        .L= appendix 1 props

which will generate












                           - 7 -



        _A_p_p_e_n_d_i_x _A: _L_i_s_t _o_f _R_e_g_i_s_t_e_r_e_d _T_r_a_d_e _M_a_r_k_s

        (For the addresses of the proprietors see appendix B).
























































echo shar: "274 control characters may be missing from 'lbl.doc'"