diff --git a/content/courses/ada-idioms/chapters/abstract_data_machines.rst b/content/courses/ada-idioms/chapters/abstract_data_machines.rst index 4f7afd130..1438fe505 100644 --- a/content/courses/ada-idioms/chapters/abstract_data_machines.rst +++ b/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:: diff --git a/content/courses/ada-idioms/chapters/abstract_data_types.rst b/content/courses/ada-idioms/chapters/abstract_data_types.rst index 7735bd43b..32e2a2c93 100644 --- a/content/courses/ada-idioms/chapters/abstract_data_types.rst +++ b/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:: diff --git a/content/courses/ada-idioms/chapters/essential_idioms_for_packages.rst b/content/courses/ada-idioms/chapters/essential_idioms_for_packages.rst index c464638ef..4da9eff96 100644 --- a/content/courses/ada-idioms/chapters/essential_idioms_for_packages.rst +++ b/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:: diff --git a/content/courses/ada-idioms/chapters/inheritance_idioms.rst b/content/courses/ada-idioms/chapters/inheritance_idioms.rst index b7753efef..c94b8d1b2 100644 --- a/content/courses/ada-idioms/chapters/inheritance_idioms.rst +++ b/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 ` and :wikipedia:`Implementation Inheritance `. @@ -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:: diff --git a/content/courses/ada-idioms/chapters/interrupt_handling.rst b/content/courses/ada-idioms/chapters/interrupt_handling.rst index 7559cfac3..c92cd445c 100644 --- a/content/courses/ada-idioms/chapters/interrupt_handling.rst +++ b/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 diff --git a/content/courses/ada-idioms/chapters/introduction.rst b/content/courses/ada-idioms/chapters/introduction.rst index c636d33ce..a3a15ea8b 100644 --- a/content/courses/ada-idioms/chapters/introduction.rst +++ b/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 `. +.. 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:: diff --git a/content/courses/ada-idioms/chapters/programming_by_extension.rst b/content/courses/ada-idioms/chapters/programming_by_extension.rst index 5972c4033..675c16b12 100644 --- a/content/courses/ada-idioms/chapters/programming_by_extension.rst +++ b/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. diff --git a/content/courses/ada-idioms/chapters/type_punning.rst b/content/courses/ada-idioms/chapters/type_punning.rst index 9356d686a..12485150d 100644 --- a/content/courses/ada-idioms/chapters/type_punning.rst +++ b/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:: diff --git a/content/courses/ada-idioms/conf.ini b/content/courses/ada-idioms/conf.ini index 14474dbc3..91b4c8fb7 100644 --- a/content/courses/ada-idioms/conf.ini +++ b/content/courses/ada-idioms/conf.ini @@ -1,4 +1,5 @@ [DEFAULT] title=Ada Idioms author=Patrick Rogers +bibtex_file=references.bib diff --git a/content/courses/ada-idioms/references.bib b/content/courses/ada-idioms/references.bib new file mode 100644 index 000000000..0b8987391 --- /dev/null +++ b/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} +}