doc/my-bib-macros.texi

   1 @c -*-texinfo-*-
   2 @c %% my-bib-macros.texi --- Texinfo macros providing a crude
   3 @c %% bibliography and citation capability.
   4
   5 @c % This is modified for use with gnutls. texi2dvi had some problems using
   6 @c % this, thus some things are hard coded here. (for the sake of a good pdf output)
   7
   8 @c % Copyright (C) 2007  Free Software Foundation, Inc.
   9 @c % Copyright (C) 2004  Aaron S. Hawley
  10
  11 @c % Author: Aaron S. Hawley <ashawley@gnu.uvm.edu>
  12 @c % Keywords: docs, texinfo, extensions, bib
  13
  14 @c % This file is free software; you can redistribute it and/or modify
  15 @c % it under the terms of the GNU General Public License as published by
  16 @c % the Free Software Foundation; either version 2, or (at your option)
  17 @c % any later version.
  18
  19 @c % This file is distributed in the hope that it will be useful,
  20 @c % but WITHOUT ANY WARRANTY; without even the implied warranty of
  21 @c % MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  22 @c % GNU General Public License for more details.
  23
  24 @c % You should have received a copy of the GNU General Public License
  25 @c % along with GNU Emacs; see the file COPYING.  If not, write to
  26 @c % the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  27 @c % Boston, MA 02111-1307, USA.
  28
  29 @c %% Commentary:
  30
  31 @c %%% Introduction
  32
  33 @c %% Creates references to a ``Bibliography'' or ``References''
  34 @c %% section of a Texinfo document, using Texinfo's
  35 @c %% macro system.  Although not as terse a way to cite systems as is
  36 @c %% found in document systems like TeX, the format is simpler and
  37 @c %% the rendering  is easier for non-academic readers.
  38
  39 @c %
  40
  41 @c %%% Usage
  42
  43 @c %% References to cited works can be put in any section of a document.
  44 @c %% The cited works must be put in either a Texinfo table (for
  45 @c %% instance with ``@table @asis ... @end table'') or within a
  46 @c %% Texinfo list (something like ``@enumerate ... @end enumerate''
  47 @c %% or ``@itemize @bullet ... @end itemize'').  They are created
  48 @c %% with the command ``@mybibitem{REF-NAME}''.  To cite a reference
  49 @c %% with a @mybibitem use ``@mybibcite{REF-NAME}''.
  50
  51 @c %% The beginning of a document must include (using the @include
  52 @c %% command) the file my-bib-macros.texi, which should be made
  53 @c %% available in the current directory of the parent file.  A single
  54 @c %% call should be made to choose to use a list or a table.  The
  55 @c %% command to chose is called @mybibuselist{NODE}, where NODE is
  56 @c %% the node containing the location where the references are listed.
  57
  58 @c %
  59
  60 @c %%% Example
  61
  62 @c %% \input texinfo   @c -*-texinfo-*-
  63 @c %% @comment %**start of header
  64 @c %% @setfilename my-file-with-bib.info
  65 @c %% @settitle Texinfo with a Bibliography and References
  66 @c %%
  67 @c %% @include my-bib-macros.texi
  68 @c %% @mybibuselist{References}
  69 @c %%
  70 @c %% @comment %**end of header
  71 @c %%
  72 @c %% @node Top
  73 @c %% @top Top
  74 @c %%
  75 @c %% @menu
  76 @c %% * Introduction::
  77 @c %% * @mybibnode{}::
  78 @c %%
  79 @c %% @end menu
  80 @c %%
  81 @c %% @node Introduction
  82 @c %% @chapter Introduction
  83 @c %%
  84 @c %% The ability of a documentation format to make cross references to a
  85 @c %% bibliography, a feature of LaTeX @mybibcite{LaTeX2e}, isn't
  86 @c %% currently supported in Texinfo.
  87 @c %%
  88 @c %% @node @mybibnode{}
  89 @c %% @chapter References
  90 @c %%
  91 @c %% @itemize @asis
  92 @c %%
  93 @c %% @mybibitem{LaTeX2e} Leslie Lamport, LaTeX User's Guide and
  94 @c %% Reference Manual, 2nd edition, Addison-Wesley, Reading,
  95 @c %% Massachusetts, 1994.
  96 @c %%
  97 @c %% @end itemize
  98 @c %%
  99 @c %% @bye
 100
 101 @c %%
 102
 103 @c %% This example produces (in Info):
 104
 105 @c %%       1 Introduction
 106 @c %%       **************
 107 @c %%
 108 @c %%       The ability of a documentation format to make cross
 109 @c %%       references to a bibliography, a feature of LaTeX (See item
 110 @c %%       [LaTeX2e] in *Note LaTeX2e: References.), is not currently
 111 @c %%       supported in Texinfo.
 112 @c %%
 113 @c %%
 114 @c %%       2 References
 115 @c %%       ************
 116 @c %%
 117 @c %%       [LaTeX2e] Leslie Lamport, LaTeX User's Guide and Reference
 118 @c %%       Manual, 2nd edition, Addison-Wesley, Reading,
 119 @c %%       Massachusetts, 1994.
 120
 121 @c %% and (in printed output):
 122
 123 @c %%       1 Introduction
 124 @c %%       **************
 125 @c %%
 126 @c %%       The ability of a documentation format to make cross
 127 @c %%       references to a bibliography, a feature of LaTeX (See item
 128 @c %%       [LaTeX2e] in Chapter 2 [References], page 3.), is not
 129 @c %%       currently supported in Texinfo.
 130 @c %%
 131 @c %%
 132 @c %%       2 References
 133 @c %%       ************
 134 @c %%
 135 @c %%       [LaTeX2e] Leslie Lamport, LaTeX User's Guide and Reference
 136 @c %%       Manual, 2nd edition, Addison-Wesley, Reading,
 137 @c %%       Massachusetts, 1994.
 138
 139 @c %
 140
 141 @c %%% Notes
 142
 143 @c %% The pointers to references will be functional in hypertext
 144 @c %% documentation (info, HTML, XML and others) and properly rendered
 145 @c %% in print documents, because they are implemented with Texinfo's
 146 @c %% cross referencing capabilities (using @anchor and @ref).  Failures
 147 @c %% by an author to make proper references with ``my-bib-macros'' in
 148 @c %% their document will give cross referencing errors by Texinfo
 149 @c %% conversion tools.
 150
 151 @c %% Only one ``Reference'' section is allowed per document.
 152
 153 @c %% An improvement of this system would create cross references
 154 @c %% (with @xref) at each cited work to all the originating cross
 155 @c %% refererences.
 156
 157 @c %
 158
 159 @c %% Code:
 160
 161 @c % Configuration Options
 162
 163 @c %% @mybibsetrefnode : Defines the name of the node to contain
 164 @c %% references.
 165
 166 @macro mybibsetrefnode{node}
 167 @set mybibrefnode \node\
 168 @end macro
 169
 170 @c %% @mybibnode{} : Macro to be placed at node containing references
 171 @c %% and calls to @mybibcite{}
 172
 173 @macro mybibnode{}
 174 @value{mybibrefnode}
 175 @end macro
 176
 177 @c %% @mybibusetable : Whether each @mybibitem will be put in a
 178 @c %% table.
 179
 180 @macro mybibusetable{node}
 181 @set mybibtable true
 182 @ifset mybiblist
 183 @clear mybiblist
 184 @end ifset
 185 @mybibsetrefnode{\node\}
 186 @end macro
 187
 188 @c %% @mybibuselist : Whether each @mybibitem will be put in a
 189 @c %% list.
 190
 191 @macro mybibuselist{node}
 192 @set mybiblist true
 193 @ifset mybibtable
 194 @clear mybibtable
 195 @end ifset
 196 @mybibsetrefnode{\node\}
 197 @end macro
 198
 199
 200 @c %% @mybibcite{REF} : Cites the cross reference REF.
 201
 202 @macro mybibcite{ref}
 203 @ifclear mybibrefnode
 204 @mybibmakeref{mybibsetrefnode was not used, \ref\}
 205 @end ifclear
 206 @c %**else if
 207 @ifset mybibrefnode
 208 @mybibmakeref{@mybibnode{}, \ref\}
 209 @end ifset
 210
 211 @end macro
 212
 213 @macro mybibmakeref{node, ref}
 214 [\ref\] (@pxref{Bibliography,\ref\})
 215 @end macro
 216
 217 @c %% @mybibcite{REF} : Creates a cross referenced citation REF.
 218
 219 @macro mybibitem{ref}
 220 @ifclear mybiblist
 221 @ifclear mybibtable
 222 @set mybiblist true
 223 @end ifclear
 224 @end ifclear
 225 @ifset mybiblist
 226 @item
 227 @anchor{\ref\}[\ref\]
 228 @end ifset
 229 @c %**else if
 230 @ifset mybibtable
 231 @item @anchor{\ref\}[\ref\]
 232 @end ifset
 233
 234 @end macro
 235
 236 @c %% my-bib-macros.texi ends here