From: Nikos Mavrogiannopoulos Date: Fri, 28 Oct 2005 00:12:52 +0000 (+0000) Subject: added bibliography\! X-Git-Tag: gnutls_1_2_9~59 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=b57dd1be6afacdf0efccd0a1ba442ec6102b81eb;p=thirdparty%2Fgnutls.git added bibliography\! --- diff --git a/doc/Makefile.am b/doc/Makefile.am index b018d0a4de..f61120effd 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -27,8 +27,9 @@ SUBDIRS += reference endif info_TEXINFOS = gnutls.texi -gnutls_TEXINFOS = gnutls.texi fdl.texi error_codes.texi \ +gnutls_TEXINFOS = gnutls.texi fdl.texi error_codes.texi bibliography.texi \ gnutls-api.texi gnutls-extra-api.texi x509-api.texi \ + my-bib-macros.texi \ pgp-api.texi examples/ex-client1.c examples/ex-client2.c \ examples/ex-session-info.c examples/ex-verify.c \ examples/ex-cert-select.c examples/ex-client-resume.c \ diff --git a/doc/bibliography.texi b/doc/bibliography.texi new file mode 100644 index 0000000000..b616aa0a0f --- /dev/null +++ b/doc/bibliography.texi @@ -0,0 +1,62 @@ +@table @asis + +@mybibitem{RFC2246} Tim Dierks and Christopher Allen, The TLS Protocol Version 1.0, +January 1999, Available from @url{http://kaizi.viagenie.qc.ca/ietf/rfc/rfc2246.txt}. + +@mybibitem{RFC2440} Jon Callas and Lutz Donnerhacke and Hal Finney and Rodney Thayer, +OpenPGP Message Format, November 1998, Available from @url{http://kaizi.viagenie.qc.ca/ietf/rfc/rfc2440.txt}. + +@mybibitem{RFC2511} Michael Myers and Carlisle Adams and Dave Solo and David Kemp, +Internet X.509 Certificate Request Message Format, March 1999, Available from @url{http://kaizi.viagenie.qc.ca/ietf/rfc/rfc2511.txt}. + +@mybibitem{RFC2817} Rohit Khare and Scott Lawrence, Upgrading to TLS Within HTTP/1.1, +May 2000, Available from @url{http://kaizi.viagenie.qc.ca/ietf/rfc/rfc2817.txt} + +@mybibitem{RFC2818} Eric Rescola, HTTP Over TLS, May 2000, +Available from @url{http://kaizi.viagenie.qc.ca/ietf/rfc/rfc2818.txt}. + +@mybibitem{RFC2945} Tom Wu, The SRP Authentication and Key Exchange System, +September 2000, Available from @url{http://kaizi.viagenie.qc.ca/ietf/rfc/rfc2945.txt}. + +@mybibitem{RFC2986} Magnus Nystrom and Burt Kaliski, PKCS 10 v1.7: Certification Request Syntax Specification, +November 2000, Available from @url{http://kaizi.viagenie.qc.ca/ietf/rfc/rfc2986.txt}. + +@mybibitem{RFC3280} Russell Housley and Tim Polk and Warwick Ford and David Solo, +Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile, +April 2002, Available from @url{http://kaizi.viagenie.qc.ca/ietf/rfc/rfc3280.txt}. + +@mybibitem{SSL3} Alan Freier and Philip Karlton and Paul Kocher, The SSL Protocol Version 3.0, +November 1996, Available from @url{http://wp.netscape.com/eng/ssl3/draft302.txt}. + +@mybibitem{PKCS12} RSA Laboratories, PKCS 12 v1.0: Personal Information Exchange Syntax, +June 1999, Available from @url{http://www.rsa.com}. + +@mybibitem{RESCOLA} Eric Rescola, SSL and TLS: Designing and Building Secure Systems, 2001 + +@mybibitem{TLSEXT} Simon Blake-Wilson and Magnus Nystrom and David Hopwood and Jan Mikkelsen and Tim Wright, +Transport Layer Security (TLS) Extensions, June 2003, +Available from @url{http://kaizi.viagenie.qc.ca/ietf/rfc/rfc3546.txt}. + +@mybibitem{TLSSRP} Taylor and Trevor Perrin and Tom Wu and Nikos Mavrogiannopoulos, +Using SRP for TLS Authentication, August 2005, +Internet draft, work in progress. Available from @url{http://www.normos.org/ietf/draft/draft-ietf-tls-srp-08.txt}. + +@mybibitem{TLSPGP} Nikos Mavrogiannopoulos, Using OpenPGP keys for TLS authentication, +April 2004, Internet draft, work in progress. Available from @url{http://www.normos.org/ietf/draft/draft-ietf-tls-openpgp-keys-05.txt}. + +@mybibitem{TLSCOMP} Scott Hollenbeck, Transport Layer Security Protocol Compression Methods, +May 2004, Available from @url{http://kaizi.viagenie.qc.ca/ietf/rfc/rfc3749.txt}. + +@mybibitem{CBCATT} Bodo Moeller, Security of CBC Ciphersuites in SSL/TLS: Problems and Countermeasures, +2002, Available from @url{http://www.openssl.org/~bodo/tls-cbc.txt}. + +@mybibitem{GUTPKI} Peter Gutmann, Everything you never wanted to know about PKI but were forced to find out, +2002, Available from @url{http://www.cs.auckland.ac.nz/~pgut001/pubs/pkitutorial.pdf}. + +@mybibitem{GPGH} Mike Ashley, The GNU Privacy Handbook, 2002, +Available from @url{http://www.gnupg.org/gph/en/manual.pdf}. + +@mybibitem{TOMSRP} Tom Wu, The Stanford SRP Authentication Project, +Available at @url{http://srp.stanford.edu/}. + +@end table diff --git a/doc/gnutls-logo.png b/doc/gnutls-logo.png new file mode 100644 index 0000000000..7b82218348 Binary files /dev/null and b/doc/gnutls-logo.png differ diff --git a/doc/gnutls.texi b/doc/gnutls.texi index 975735b38a..4452224e41 100644 --- a/doc/gnutls.texi +++ b/doc/gnutls.texi @@ -5,6 +5,10 @@ @include version.texi @settitle GNU TLS @value{VERSION} +@include my-bib-macros.texi +@mybibusetable{Bibliography} +@c @mybibsetrefnode{@mybibnode{}} + @c Unify some of the indices. @syncodeindex tp fn @syncodeindex pg cp @@ -79,6 +83,7 @@ Free Documentation License''. * Copying This Manual:: * Concept Index:: * Function and Data Index:: +* @mybibnode{}:: @end menu @@ -101,11 +106,8 @@ a program or a communication line and @acronym{GnuTLS} only helps with some of them. This document tries to be self contained, although basic network -programming and PKI knowlegde is assumed in most of it. Peter -Gutmann's ``Everything you never wanted to know about PKI but were -forced to find out''@footnote{Available from -@url{http://www.cs.auckland.ac.nz/~pgut001/pubs/pkitutorial.pdf}} is a -good introduction to Public Key Infrastructure. +programming and PKI knowlegde is assumed in most of it. A good introduction +to Public Key Infrastructure can be found in @mybibcite{GUTPKI}. @anchor{Availability} @@ -302,14 +304,13 @@ should allocate and free memory using the functions shown below. @chapter Introduction to @acronym{TLS} @acronym{TLS} stands for ``Transport Layer Security'' and is the -successor of SSL, the Secure Sockets Layer protocol@footnote{Described -in @cite{SSL3}} designed by Netscape. @acronym{TLS} is an Internet +successor of SSL, the Secure Sockets Layer protocol @mybibcite{SSL3} designed by Netscape. @acronym{TLS} is an Internet protocol, defined by @acronym{IETF}@footnote{IETF, or Internet Engineering Task Force, is a large open international community of network designers, operators, vendors, and researchers concerned with the evolution of the Internet architecture and the smooth operation of the Internet. It is open to any interested individual.}, described in -@acronym{RFC} 2246 and also in @cite{RESCOLA}. The protocol provides +@acronym{RFC} 2246 and also in @mybibcite{RESCOLA}. The protocol provides confidentiality, and authentication layers over any reliable transport layer. The description, below, refers to @acronym{TLS} 1.0 but also applies to @acronym{TLS} 1.1 and @acronym{SSL} 3.0, since the @@ -482,9 +483,9 @@ the EU project RIPE. Outputs 160 bits of data. @cindex Compression algorithms The TLS record layer also supports compression. The algorithms -implemented in @acronym{GnuTLS} can be found in figure -@cite{compression}. All the algorithms except for DEFLATE which is -referenced in @cite{TLSCOMP}, should be considered as +implemented in @acronym{GnuTLS} can be found in the table below. +All the algorithms except for DEFLATE which is +referenced in @mybibcite{TLSCOMP}, should be considered as @acronym{GnuTLS}' extensions@footnote{You should use @code{gnutls_handshake_set_private_extensions} to enable private extensions.}, and should be advertised only when the peer is known to @@ -498,9 +499,8 @@ tunnels, and in cases where network usage has to be minimized. As a drawback, compression increases latency. The record layer compression in @acronym{GnuTLS} is implemented based -on the paper @cite{TLSCOMP}. - -Supported compression algorithms: +on the paper @mybibcite{TLSCOMP}. +The supported compression algorithms are: @table @code @item DEFLATE @@ -538,7 +538,7 @@ encrypted packet. Those weaknesses were solved in @acronym{TLS} 1.1 which is implemented in @acronym{GnuTLS}. For a detailed discussion see the archives of the -TLS Working Group mailing list and the paper @cite{CBCATT}. +TLS Working Group mailing list and the paper @mybibcite{CBCATT}. @node The TLS Alert Protocol @section The TLS Alert Protocol @@ -835,13 +835,11 @@ more information on @acronym{X.509} protocols. algorithm, and signatures from several other parties. Depending on whether a signer is trusted the key is considered trusted or not. @acronym{GnuTLS}'s @acronym{OpenPGP} authentication implementation is -based on the @cite{TLSPGP} proposal. +based on the @mybibcite{TLSPGP} proposal. @xref{The OpenPGP trust model}, for more information about the @acronym{OpenPGP} trust model. For a more detailed introduction to -@acronym{OpenPGP} and @acronym{GnuPG} see Mike Ashley's @cite{The GNU -Privacy -Handbook}@footnote{@url{http://www.gnupg.org/gph/en/manual.html}}. +@acronym{OpenPGP} and @acronym{GnuPG} see @mybibcite{GPGH}. @subsection Using certificate authentication @@ -998,7 +996,7 @@ This algorithm exchanges Diffie Hellman parameters. @cindex @acronym{SRP} authentication Authentication via the Secure Remote Password protocol, -@acronym{SRP}@footnote{@acronym{SRP} is described in @cite{RFC2945}}, +@acronym{SRP}@footnote{@acronym{SRP} is described in @mybibcite{RFC2945}}, is supported. The @acronym{SRP} key exchange is an extension to the @acronym{TLS} protocol, and it is a password based authentication (unlike @acronym{X.509} or @acronym{OpenPGP} that uses certificates). @@ -1014,14 +1012,14 @@ protection is similar to the one used traditionally in the @emph{UNIX} harm to the system security if they were revealed. The @acronym{SRP} needs instead of the plain password something called a verifier, which is calculated using the user's password, and if stolen cannot be used -to impersonate the user. See @cite{TOMSRP} for a detailed description +to impersonate the user. See @mybibcite{TOMSRP} for a detailed description of the @acronym{SRP} protocol and the Stanford @acronym{SRP} libraries, which includes a PAM module that synchronizes the system's users passwords with the @acronym{SRP} password files. That way @acronym{SRP} authentication could be used for all the system's users. The implementation in @acronym{GnuTLS} is based on paper -@cite{TLSSRP}. The supported @acronym{SRP} key exchange methods are: +@mybibcite{TLSSRP}. The supported @acronym{SRP} key exchange methods are: @table @code @@ -1216,7 +1214,7 @@ handling @acronym{X.509} certificates is described at section An @acronym{X.509} certificate usually contains information about the certificate holder, the signer, a unique serial number, expiration -dates and some other fields @cite{RFC3280} as shown in the table +dates and some other fields @mybibcite{RFC3280} as shown in the table below. @table @code @@ -1334,7 +1332,7 @@ These algorithms have been broken and should not be trusted. Although the verification of a certificate path indicates that the certificate is signed by trusted authority, does not reveal anything about the peer's identity. It is required to verify if the -certificate's owner is the one you expect. See @cite{RFC2818} and +certificate's owner is the one you expect. See @mybibcite{RFC2818} and section @ref{ex:verify} for an example. @node PKCS #10 certificate requests @@ -1346,8 +1344,8 @@ A certificate request is a structure, which contain information about an applicant of a certificate service. It usually contains a private key, a distinguished name and secondary data such as a challenge password. @acronym{GnuTLS} supports the requests defined in -@acronym{PKCS} #10 @cite{RFC2986}. Other certificate request's format -such as PKIX's @cite{RFC2511} are not currently supported. +@acronym{PKCS} #10 @mybibcite{RFC2986}. Other certificate request's format +such as PKIX's @mybibcite{RFC2511} are not currently supported. In @acronym{GnuTLS} the @acronym{PKCS} #10 structures are handled using the @code{gnutls_x509_crq_t} type. An example of a certificate @@ -1357,7 +1355,7 @@ request generation can be found at section @ref{ex:crq}. @subsection @acronym{PKCS} #12 structures @cindex @acronym{PKCS} #12 -A @acronym{PKCS} #12 structure @cite{PKCS12} usually contains a user's +A @acronym{PKCS} #12 structure @mybibcite{PKCS12} usually contains a user's private keys and certificates. It is commonly used in browsers to export and import the user's identities. @@ -1404,7 +1402,7 @@ belong to the actual owner. @subsection @acronym{OpenPGP} keys In @acronym{GnuTLS} the @acronym{OpenPGP} key structures -@cite{RFC2440} are handled using the @code{gnutls_openpgp_key_t} type +@mybibcite{RFC2440} are handled using the @code{gnutls_openpgp_key_t} type and the corresponding private keys with the @code{gnutls_openpgp_privkey_t} type. All the prototypes for the key handling functions can be found at @file{gnutls/openpgp.h}. @@ -1472,7 +1470,7 @@ for the secured ones. This has the benefit that if a user requests a secure session then the client will try to connect to the secure port and fail otherwise. The only possible attack with this method is a denial of service one. The most famous example of this method is the -famous ``HTTP over TLS'' or @acronym{HTTPS} protocol @cite{RFC2818}. +famous ``HTTP over TLS'' or @acronym{HTTPS} protocol @mybibcite{RFC2818}. Despite its wide use, this method is not as good as it seems. This approach starts the @acronym{TLS} Handshake procedure just after the @@ -1501,7 +1499,7 @@ protocols just after the client requests it. This is a really neat idea and does not require an extra port. This method is used by almost all modern protocols and there is even -the @cite{RFC2817} paper which proposes extensions to HTTP to support +the @mybibcite{RFC2817} paper which proposes extensions to HTTP to support it. The tricky part, in this method, is that the ``STARTTLS'' request is @@ -2900,170 +2898,6 @@ functions: @end multitable -@c @node References -@c @chapter References - -@c @Misc{RFC2246, -@c author = "Tim Dierks and Christopher Allen", -@c title = "The TLS Protocol Version 1.0", -@c month = "January", -@c year = {1999}, -@c note = "Available from http://kaizi.viagenie.qc.ca/ietf/rfc/rfc2246.txt", -@c url = "http://kaizi.viagenie.qc.ca/ietf/rfc/rfc2246.txt" -@c } - -@c @Misc{RFC2440, -@c author = "Jon Callas and Lutz Donnerhacke and Hal Finney and Rodney Thayer", -@c title = "OpenPGP Message Format", -@c month = "November", -@c year = {1998}, -@c note = "Available from http://kaizi.viagenie.qc.ca/ietf/rfc/rfc2440.txt", -@c url = "http://kaizi.viagenie.qc.ca/ietf/rfc/rfc2440.txt" -@c } - -@c @Misc{RFC2511, -@c author = "Michael Myers and Carlisle Adams and Dave Solo and David Kemp", -@c title = "Internet X.509 Certificate Request Message Format", -@c month = "March", -@c year = {1999}, -@c note = "Available from http://kaizi.viagenie.qc.ca/ietf/rfc/rfc2511.txt", -@c url = "http://kaizi.viagenie.qc.ca/ietf/rfc/rfc2511.txt" -@c } - -@c @Misc{RFC2817, -@c author = "Rohit Khare and Scott Lawrence", -@c title = "Upgrading to TLS Within HTTP/1.1", -@c month = "May", -@c year = {2000}, -@c note = "Available from http://kaizi.viagenie.qc.ca/ietf/rfc/rfc2817.txt", -@c url = "http://kaizi.viagenie.qc.ca/ietf/rfc/rfc2817.txt" -@c } - -@c @Misc{RFC2818, -@c author = "Eric Rescola", -@c title = "HTTP Over TLS", -@c month = "May", -@c year = {2000}, -@c note = "Available from http://kaizi.viagenie.qc.ca/ietf/rfc/rfc2818.txt", -@c url = "http://kaizi.viagenie.qc.ca/ietf/rfc/rfc2818.txt" -@c } - - -@c @Misc{RFC2945, -@c author = "Tom Wu", -@c title = "The SRP Authentication and Key Exchange System", -@c month = "September", -@c year = {2000}, -@c note = "Available from http://kaizi.viagenie.qc.ca/ietf/rfc/rfc2945.txt", -@c url = "http://kaizi.viagenie.qc.ca/ietf/rfc/rfc2945.txt" -@c } - -@c @Misc{RFC2986, -@c author = "Magnus Nystrom and Burt Kaliski", -@c title = "PKCS 10 v1.7: Certification Request Syntax Specification", -@c month = "November", -@c year = {2000}, -@c note = "Available from http://kaizi.viagenie.qc.ca/ietf/rfc/rfc2986.txt", -@c url = "http://kaizi.viagenie.qc.ca/ietf/rfc/rfc2986.txt" -@c } - -@c @Misc{RFC3280, -@c author = "Russell Housley and Tim Polk and Warwick Ford and David Solo", -@c title = "Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile", -@c month = "April", -@c year = {2002}, -@c note = "Available from http://kaizi.viagenie.qc.ca/ietf/rfc/rfc3280.txt", -@c url = "http://kaizi.viagenie.qc.ca/ietf/rfc/rfc3280.txt" -@c } - -@c @Misc{SSL3, -@c author = "Alan Freier and Philip Karlton and Paul Kocher", -@c title = "The SSL Protocol Version 3.0", -@c month = "November", -@c year = {1996}, -@c note = "Available from http://wp.netscape.com/eng/ssl3/draft302.txt", -@c url = "http://wp.netscape.com/eng/ssl3/draft302.txt" -@c } - -@c @Misc{PKCS12, -@c author = "RSA Laboratories", -@c title = "PKCS 12 v1.0: Personal Information Exchange Syntax", -@c month = "June", -@c year = {1999}, -@c } - -@c @Misc{RESCOLA, -@c author = "Eric Rescola", -@c title = "SSL and TLS: Designing and Building Secure Systems", -@c year = {2001}, -@c } - -@c @Misc{TLSEXT, -@c author = "Simon Blake-Wilson and Magnus Nystrom and David Hopwood and Jan Mikkelsen and Tim Wright", -@c title = "Transport Layer Security (TLS) Extensions", -@c month = "June", -@c year = {2003}, -@c note = "Available from http://kaizi.viagenie.qc.ca/ietf/rfc/rfc3546.txt", -@c url = "http://kaizi.viagenie.qc.ca/ietf/rfc/rfc3546.txt" -@c } - -@c @Misc{TLSSRP, -@c author = "David Taylor and Trevor Perrin and Tom Wu and Nikos Mavroyanopoulos", -@c title = "Using SRP for TLS Authentication", -@c month = "June", -@c year = {2004}, -@c note = "Internet draft, work in progress. Available from http://www.normos.org/ietf/draft/draft-ietf-tls-srp-07.txt", -@c url = "http://www.normos.org/ietf/draft/draft-ietf-tls-srp-07.txt" -@c } - -@c @Misc{TLSPGP, -@c author = "Nikos Mavroyanopoulos", -@c title = "Using OpenPGP keys for TLS authentication", -@c month = "April", -@c year = {2004}, -@c note = "Internet draft, work in progress. Available from http://www.normos.org/ietf/draft/draft-ietf-tls-openpgp-keys-05.txt", -@c url = "http://www.normos.org/ietf/draft/draft-ietf-tls-openpgp-keys-05.txt" -@c } - -@c @Misc{TLSCOMP, -@c author = "Scott Hollenbeck", -@c title = "Transport Layer Security Protocol Compression Methods", -@c month = "January", -@c year = {2004}, -@c note = "Internet draft, work in progress. Available from http://kaizi.viagenie.qc.ca/ietf/rfc/rfc3749.txt", -@c url = "http://kaizi.viagenie.qc.ca/ietf/rfc/rfc3749.txt" -@c } - -@c @Misc{CBCATT, -@c author = "Bodo Moeller", -@c title = "Security of CBC Ciphersuites in SSL/TLS: Problems and Countermeasures", -@c year = {2002}, -@c note = "Available from http://www.openssl.org/\~\ bodo/tls-cbc.txt", -@c url = "http://www.openssl.org/~bodo/tls-cbc.txt" -@c } - -@c @Misc{GUTPKI, -@c author = "Peter Gutmann", -@c title = "Everything you never wanted to know about PKI but were forced to find out", -@c year = {2002}, -@c note = "Available from http://www.cs.auckland.ac.nz/\~\ pgut001/pubs/pkitutorial.pdf", -@c url = "http://www.cs.auckland.ac.nz/~pgut001/pubs/pkitutorial.pdf" -@c } - -@c @Misc{GPGH, -@c author = "Mike Ashley", -@c title = "The GNU Privacy Handbook", -@c year = {2002}, -@c note = "Available from http://www.gnupg.org/gph/en/manual.pdf", -@c url = "http://www.gnupg.org/gph/en/manual.pdf" -@c } - -@c @Misc{TOMSRP, -@c author = "Tom Wu", -@c title = "The Stanford SRP Authentication Project", -@c note = "Available at http://srp.stanford.edu/", -@c url = "http://srp.stanford.edu/" -@c } @node Copying This Manual @appendix Copying This Manual @@ -3084,4 +2918,12 @@ functions: @printindex fn +@c texi2dvi has problem if unnumbered is put there. However makeinfo works great. +@c STUPID texinfo. + +@node @mybibnode{} +@unnumbered @mybibnode{} +@include bibliography.texi + + @bye diff --git a/doc/my-bib-macros.texi b/doc/my-bib-macros.texi new file mode 100644 index 0000000000..98a284a3ae --- /dev/null +++ b/doc/my-bib-macros.texi @@ -0,0 +1,233 @@ +@c -*-texinfo-*- +@c %% my-bib-macros.texi --- Texinfo macros providing a crude +@c %% bibliography and citation capability. + +@c % Copyright (C) 2004 Aaron S. Hawley + +@c % Author: Aaron S. Hawley +@c % Keywords: docs, texinfo, extensions, bib + +@c % This file is free software; you can redistribute it and/or modify +@c % it under the terms of the GNU General Public License as published by +@c % the Free Software Foundation; either version 2, or (at your option) +@c % any later version. + +@c % This file is distributed in the hope that it will be useful, +@c % but WITHOUT ANY WARRANTY; without even the implied warranty of +@c % MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +@c % GNU General Public License for more details. + +@c % You should have received a copy of the GNU General Public License +@c % along with GNU Emacs; see the file COPYING. If not, write to +@c % the Free Software Foundation, Inc., 59 Temple Place - Suite 330, +@c % Boston, MA 02111-1307, USA. + +@c %% Commentary: + +@c %%% Introduction + +@c %% Creates references to a ``Bibliography'' or ``References'' +@c %% section of a Texinfo document, using Texinfo's +@c %% macro system. Although not as terse a way to cite systems as is +@c %% found in document systems like TeX, the format is simpler and +@c %% the rendering is easier for non-academic readers. + +@c % + +@c %%% Usage + +@c %% References to cited works can be put in any section of a document. +@c %% The cited works must be put in either a Texinfo table (for +@c %% instance with ``@table @asis ... @end table'') or within a +@c %% Texinfo list (something like ``@enumerate ... @end enumerate'' +@c %% or ``@itemize @bullet ... @end itemize''). They are created +@c %% with the command ``@mybibitem{REF-NAME}''. To cite a reference +@c %% with a @mybibitem use ``@mybibcite{REF-NAME}''. + +@c %% The beginning of a document must include (using the @include +@c %% command) the file my-bib-macros.texi, which should be made +@c %% available in the current directory of the parent file. A single +@c %% call should be made to choose to use a list or a table. The +@c %% command to chose is called @mybibuselist{NODE}, where NODE is +@c %% the node containing the location where the references are listed. + +@c % + +@c %%% Example + +@c %% \input texinfo @c -*-texinfo-*- +@c %% @comment %**start of header +@c %% @setfilename my-file-with-bib.info +@c %% @settitle Texinfo with a Bibliography and References +@c %% +@c %% @include my-bib-macros.texi +@c %% @mybibuselist{References} +@c %% +@c %% @comment %**end of header +@c %% +@c %% @node Top +@c %% @top Top +@c %% +@c %% @menu +@c %% * Introduction:: +@c %% * @mybibnode{}:: +@c %% +@c %% @end menu +@c %% +@c %% @node Introduction +@c %% @chapter Introduction +@c %% +@c %% The ability of a documentation format to make cross references to a +@c %% bibliography, a feature of LaTeX @mybibcite{LaTeX2e}, isn't +@c %% currently supported in Texinfo. +@c %% +@c %% @node @mybibnode{} +@c %% @chapter References +@c %% +@c %% @itemize @asis +@c %% +@c %% @mybibitem{LaTeX2e} Leslie Lamport, LaTeX User's Guide and +@c %% Reference Manual, 2nd edition, Addison-Wesley, Reading, +@c %% Massachusetts, 1994. +@c %% +@c %% @end itemize +@c %% +@c %% @bye + +@c %% + +@c %% This example produces (in Info): + +@c %% 1 Introduction +@c %% ************** +@c %% +@c %% The ability of a documentation format to make cross +@c %% references to a bibliography, a feature of LaTeX (See item +@c %% [LaTeX2e] in *Note LaTeX2e: References.), is not currently +@c %% supported in Texinfo. +@c %% +@c %% +@c %% 2 References +@c %% ************ +@c %% +@c %% [LaTeX2e] Leslie Lamport, LaTeX User's Guide and Reference +@c %% Manual, 2nd edition, Addison-Wesley, Reading, +@c %% Massachusetts, 1994. + +@c %% and (in printed output): + +@c %% 1 Introduction +@c %% ************** +@c %% +@c %% The ability of a documentation format to make cross +@c %% references to a bibliography, a feature of LaTeX (See item +@c %% [LaTeX2e] in Chapter 2 [References], page 3.), is not +@c %% currently supported in Texinfo. +@c %% +@c %% +@c %% 2 References +@c %% ************ +@c %% +@c %% [LaTeX2e] Leslie Lamport, LaTeX User's Guide and Reference +@c %% Manual, 2nd edition, Addison-Wesley, Reading, +@c %% Massachusetts, 1994. + +@c % + +@c %%% Notes + +@c %% The pointers to references will be functional in hypertext +@c %% documentation (info, HTML, XML and others) and properly rendered +@c %% in print documents, because they are implemented with Texinfo's +@c %% cross referencing capabilities (using @anchor and @ref). Failures +@c %% by an author to make proper references with ``my-bib-macros'' in +@c %% their document will give cross referencing errors by Texinfo +@c %% conversion tools. + +@c %% Only one ``Reference'' section is allowed per document. + +@c %% An improvement of this system would create cross references +@c %% (with @xref) at each cited work to all the originating cross +@c %% refererences. + +@c % + +@c %% Code: + +@c % Configuration Options + +@c %% @mybibsetrefnode : Defines the name of the node to contain +@c %% references. + +@macro mybibsetrefnode{node} +@set mybibrefnode \node\ +@end macro + +@c %% @mybibnode{} : Macro to be placed at node containing references +@c %% and calls to @mybibcite{} + +@macro mybibnode{} +@value{mybibrefnode} +@end macro + +@c %% @mybibusetable : Whether each @mybibitem will be put in a +@c %% table. + +@macro mybibusetable{node} +@set mybibtable true +@ifset mybiblist +@clear mybiblist +@end ifset +@mybibsetrefnode{\node\} +@end macro + +@c %% @mybibuselist : Whether each @mybibitem will be put in a +@c %% list. + +@macro mybibuselist{node} +@set mybiblist true +@ifset mybibtable +@clear mybibtable +@end ifset +@mybibsetrefnode{\node\} +@end macro + + +@c %% @mybibcite{REF} : Cites the cross reference REF. + +@macro mybibcite{ref} +@ifclear mybibrefnode +@mybibmakeref{mybibsetrefnode was not used, \ref\} +@end ifclear +@c %**else if +@ifset mybibrefnode +@mybibmakeref{@mybibnode{}, \ref\} +@end ifset + +@end macro + +@macro mybibmakeref{node, ref} +[\ref\] (See @ref{\ref\}.) +@end macro + +@c %% @mybibcite{REF} : Creates a cross referenced citation REF. + +@macro mybibitem{ref} +@ifclear mybiblist +@ifclear mybibtable +@set mybiblist true +@end ifclear +@end ifclear +@ifset mybiblist +@item +@anchor{\ref\}[\ref\] +@end ifset +@c %**else if +@ifset mybibtable +@item +@anchor{\ref\}[\ref\] +@end ifset + +@end macro + +@c %% my-bib-macros.texi ends here \ No newline at end of file