Merge pull request #1178 from gusthoff/content/ada_idioms/review/editorial/structure/20250125

Editorial change: replace plain footnotes by references using bibtex

Author: gusthoff

content/courses/ada-idioms/chapters/abstract_data_machines.rst

@@ -49,7 +49,8 @@ Singletons can be expressed easily in Ada
 but there is an alternative in this specific situation.
 
 This idiom entry describes the alternative, known as the Abstract Data
-Machine (ADM). The Abstract Data Machine was introduced by Grady Booch [1]_
+Machine (ADM). The Abstract Data Machine was introduced by
+Grady Booch :footcite:p:`1983:booch`
 as the Abstract State Machine, but that name, though appropriate,
 encompasses more in computer science than we intend to evoke.
 
@@ -360,8 +361,8 @@ But if one can know with certainty that only one thing is ever going to be
 represented, as in the hardware rotary switch example, the ADM limitations are
 irrelevant.
 
-Bibliography
-------------
+.. only:: builder_html
 
-.. [1] Booch, G. (1983). Software Engineering with Ada, Benjamin/Cummings
-       Publishing Company.
+    .. rubric:: Bibliography
+
+.. footbibliography::

content/courses/ada-idioms/chapters/abstract_data_types.rst

@@ -66,7 +66,9 @@ potentially very expensive, perhaps prohibitively so. Worse, our *fixes* will
 likely introduce new bugs.
 
 These disadvantages argue for an alternative. That is the purpose of this next
-idiom, known as the Abstract Data Type (ADT) [1]_, [2]_.
+idiom, known as the Abstract Data Type (ADT)
+:footcite:p:`1983:booch`, :footcite:p:`1974:liskov`.
+
 
 Implementation(s)
 -----------------
@@ -96,7 +98,7 @@ to manage complexity because at any given layer we can focus on *what* is being
 done, rather than how.
 
 Therefore, an abstract data type is a type that is abstract in the sense that
-[2]_:
+:footcite:p:`1974:liskov`:
 
     - It is a higher level of abstraction than the built-in programming
       language types.
@@ -391,8 +393,10 @@ Notes
 
     2. The Ada Rationale document did not introduce the concept of Abstract Data
        Types. The ADT concept had already been introduced and recognized as
-       effective when the first version of Ada was being designed [2]_. The Ada
-       language requirements document, *Steelman* [3]_, uses the term
+       effective when the first version of Ada was being designed
+       :footcite:p:`1974:liskov`.
+       The Ada language requirements document, *Steelman*
+       :footcite:p:`1978:HOLWG`, uses the term
        "Encapsulated Definitions" and describes the information hiding to be
        provided. Steelman does not specify the implementation syntax because
        requirements documents do not include such directives. The language
@@ -402,15 +406,8 @@ Notes
     3. The ADT is the conceptual foundation for the *class* construct's
        visibility control in some class-oriented languages.
 
+.. only:: builder_html
 
-Bibliography
-------------
-
-.. [1] Booch, G. (1983). Software Engineering with Ada, Benjamin/Cummings
-       Publishing Company.
-
-.. [2] Liskov, B. and S. Zilles (1974). Programming with Abstract Data Types.
-       ACM SIGPLAN symposium on Very high level languages.
+    .. rubric:: Bibliography
 
-.. [3] HOLWG (1978). Department of Defense Requirements for High Order Computer
-       Programming Language "STEELMAN".
+.. footbibliography::

content/courses/ada-idioms/chapters/essential_idioms_for_packages.rst

@@ -15,7 +15,8 @@ way to use packages when designing an application, the language just specifies
 what is legal. However, some legal approaches are more advisable than others.
 
 Specifically, packages should exhibit high cohesion and loose coupling
-[1]_. Cohesion is the degree to which the declarations within a module are
+:footcite:p:`1979:yourdon`.
+Cohesion is the degree to which the declarations within a module are
 related to one another, in the context of the problem being solved.
 Unrelated entities should not be declared in the same module.  This allows
 the reader to focus on one primary concept, which should be the subject of
@@ -31,8 +32,10 @@ Implementation(s)
 
 Three idioms for packages were envisioned when the language was first designed.
 They were introduced and described in detail in the Rationale document for the
-initial language design [2]_ and were further developed in Grady Booch's
-book *Software Engineering with Ada* [3]_, a foundational work on design with
+initial language design :footcite:p:`1986:ichbiah`
+and were further developed in Grady Booch's
+book *Software Engineering with Ada* :footcite:p:`1983:booch`,
+a foundational work on design with
 the (sequential part of the) language. Booch added a fourth idiom, the Abstract
 Data Machine, to the three described by the Rationale. These four idioms have
 proven themselves capable of producing packages that exhibit high cohesion and
@@ -222,15 +225,8 @@ Notes
        iron-clad; hybrids are possible but should be considered initially
        suspect and reviewed accordingly.
 
-Bibliography
-------------
+.. only:: builder_html
 
-.. [1] Yourdon, E. and L. L. Constantine (1979). Structured Design:
-       Fundamentals of a Discipline of Computer Program and System Design,
-       Prentice-Hall.
+    .. rubric:: Bibliography
 
-.. [2] Ichbiah, J., J. Barnes, et al. (1986). Rationale for the Design of the
-       Ada Programming Language.
-
-.. [3] Booch, G. (1983). Software Engineering with Ada, Benjamin/Cummings
-       Publishing Company.
+.. footbibliography::

content/courses/ada-idioms/chapters/inheritance_idioms.rst

@@ -8,7 +8,8 @@ Using Building Blocks to Express Inheritance Idioms
 Motivation
 ----------
 
-Betrand Meyer's magisterial book on OOP [1]_ includes a taxonomy of inheritance
+Betrand Meyer's magisterial book on OOP :footcite:p:`1997:meyer`
+includes a taxonomy of inheritance
 idioms. Two especially well-known entries in that taxonomy are
 :wikipedia:`Subtype Inheritance <Subtyping>` and
 :wikipedia:`Implementation Inheritance <Inheritance_(object-oriented_programming)>`.
@@ -50,7 +51,8 @@ entities.
 
 Although the derived child type is distinct from the parent type, the child is
 the same *kind* as the parent type. Some authors use *kind of* as the name for the
-relationship between the child and parent. Meyer uses the term *is-a* [1]_, a
+relationship between the child and parent. Meyer uses the term *is-a*
+:footcite:p:`1997:meyer`, a
 popular term that we will use too. For example, a cat *is a* mammal, and also is
 an animal.
 
@@ -571,12 +573,10 @@ so we are using private types throughout. That includes the child type, and, as
 we saw, allows us to control the compile-time visibility to the parent type.
 
 
-Notes
------
 
 
+.. only:: builder_html
 
-Bibliography
-------------
+    .. rubric:: Bibliography
 
-.. [1] Meyer, B. (1997). Object-Oriented Software Construction, Prentice-Hall.
+.. footbibliography::

content/courses/ada-idioms/chapters/interrupt_handling.rst

@@ -856,9 +856,6 @@ Notes
        urgent priorities.
 
 
-Bibliography
-------------
-
 .. todo::
 
     Ravenscar Guide??? Surely there is some document that first introduced

content/courses/ada-idioms/chapters/introduction.rst

@@ -16,7 +16,8 @@ what is the most elegant implementation approach?". Elegant software is
 comprehensible, efficient, concise, reliable, and, as a result,
 maintainable, so elegance is an economically and technically desirable characteristic.
 
-Design patterns [1]_ are intended to answer that question, and indeed
+Design patterns :footcite:p:`1995:gamma`
+are intended to answer that question, and indeed
 some would equate idioms with design patterns. But what we have in mind
 is more general in scope.
 
@@ -36,7 +37,7 @@ Those are the kinds of situations and solutions we focus upon.
 That said, we may refer to a design pattern to illustrate an idiom's
 purpose and/or implementation. For example, in the idiom for controlling
 object creation and initialization, the implementation approach happens
-to be the same as for expressing a Singleton [1]_.
+to be the same as for expressing a Singleton :footcite:p:`1995:gamma`.
 
 In addition to language-independent situations, we also include
 solutions for situations specific to the Ada language. These idioms are
@@ -99,7 +100,8 @@ supplier to the client that instantiates it, but instantiation is the only
 possibility in that narrow case. Only the routines in the instances can be
 called.)
 
-Betrand Meyer's book on OOP [2]_ limits these terms specifically to the case of
+Betrand Meyer's book on OOP :footcite:p:`1997:meyer`
+limits these terms specifically to the case of
 a type used in an object declaration. Our definitions cover that case but
 others as well.
 
@@ -238,13 +240,8 @@ default.)
 For further details about type views, please refer to that
 :ref:`specific section of the Advanced Ada course <Adv_Ada_Type_View>`.
 
+.. only:: builder_html
 
-Bibliography
-------------
+    .. rubric:: Bibliography
 
-.. [1] Gamma, E., R. Helm, et al. (1995), pp. 127. Design Patterns: Elements of
-       Reusable Object-Oriented Software. Reading, MA, Addison-Wesley
-       Publishing Company.
-
-.. [2] Meyer, B. (1997), pp. 182. Object-Oriented Software Construction,
-       Prentice-Hall.
+.. footbibliography::

content/courses/ada-idioms/chapters/programming_by_extension.rst

@@ -101,7 +101,8 @@ private part or the package body is reasonable, but only one of the two is
 amenable to future requirements.
 
 Specifically, placement in the private part of the package allows
-*programming by extension* [1]_ via hierarchical *child* packages. Child
+*programming by extension* :footcite:p:`1998:barnes`
+via hierarchical *child* packages. Child
 packages can be written immediately after the *parent* package but can also be
 written years later, thus accommodating changes due to new requirements.
 
@@ -241,7 +242,9 @@ library units, some declarations in existing package bodies tended to
 "percolate up" to the package declarations' private parts.
 
 
-Bibliography
-------------
+.. only:: builder_html
+
+    .. rubric:: Bibliography
+
+.. footbibliography::
 
-.. [1] Barnes, J. (1998). Programming In Ada 95, Addison-Wesley.

content/courses/ada-idioms/chapters/type_punning.rst

@@ -46,7 +46,8 @@ spoken.
 
 Ada is accurately described as "a language with inherently reliable features,
 only compromised via explicit escape hatches having well-defined and portable
-semantics when used appropriately." [1]_ The foundation for this reliability is
+semantics when used appropriately." :footcite:p:`1993:taft`
+The foundation for this reliability is
 static named typing with rigorous enforcement by the compiler.
 
 Specifically, the Ada compiler checks that the operations and values applied to
@@ -474,8 +475,8 @@ potential problem. For that reason, the GNAT implementation issues a warning in
 such cases.
 
 
-Bibliography
-------------
+.. only:: builder_html
 
-.. [1] S. Tucker Taft, 1993, post in Comp.Lang.Ada,
-       https://groups.google.com/g/comp.lang.ada/c/9WXgvv8Xjuw/m/JMyo9_P7nxAJ
+    .. rubric:: Bibliography
+
+.. footbibliography::

content/courses/ada-idioms/conf.ini

@@ -1,4 +1,5 @@
 [DEFAULT]
 title=Ada Idioms
 author=Patrick Rogers
+bibtex_file=references.bib
 

content/courses/ada-idioms/references.bib

@@ -0,0 +1,62 @@
+@Book{1983:booch,
+  author = {Booch, G.},
+  title = {Software Engineering with Ada},
+  publisher = {Benjamin/Cummings Publishing Company},
+  year = {1983}
+}
+
+@Book{1974:liskov,
+  author = {Liskov, B. and Zilles, S.},
+  title = {Programming with Abstract Data Types},
+  publisher = {ACM SIGPLAN symposium on Very high level languages},
+  year = {1974}
+}
+
+@Book{1978:HOLWG,
+  author = {HOLWG},
+  title = {Department of Defense Requirements for High Order Computer Programming Language "STEELMAN"},
+  publisher = {Department of Defense},
+  year = {1978}
+}
+
+@Book{1979:yourdon,
+  author = {Yourdon, E. and Constantine, L. L.},
+  title = {Structured Design: Fundamentals of a Discipline of Computer Program and System Design},
+  publisher = {Prentice-Hall},
+  year = {1979}
+}
+
+@Book{1986:ichbiah,
+  author = {Ichbiah, J. and Barnes, J. and others},
+  title = {Rationale for the Design of the Ada Programming Language},
+  publisher = {},
+  year = {1986}
+}
+
+@Book{1997:meyer,
+  author = {Meyer, B.},
+  title = {Object-Oriented Software Construction},
+  publisher = {Prentice-Hall},
+  year = {1997}
+}
+
+@Book{1995:gamma,
+  author = {Gamma, E. and Helm, R. and others},
+  title = {Design Patterns: Elements of Reusable Object-Oriented Software},
+  publisher = {Reading, MA, Addison-Wesley Publishing Company},
+  year = {1995}
+}
+
+@Book{1998:barnes,
+  author = {Barnes, J.},
+  title = {Programming In Ada 95},
+  publisher = {Addison-Wesley},
+  year = {1998}
+}
+
+@Book{1993:taft,
+  author = {Taft, S. Tucker},
+  title = {Post in Internet Relay Chat on Comp.Lang.Ada channel},
+  publisher = {https://groups.google.com/g/comp.lang.ada/c/9WXgvv8Xjuw/m/JMyo9_P7nxAJ},
+  year = {1993}
+}