From 09f7eccd96ec74d3ca1aa578e42ba0279dbc2a32 Mon Sep 17 00:00:00 2001 From: gusthoff Date: Sat, 25 Jan 2025 01:47:36 +0100 Subject: [PATCH 1/4] Editorial change: only show bibliography section in case of HTML output Bibliography entries are footnotes. For PDF/EPUB output, they are displayed on the same page where their corresponding references show up. --- .../courses/ada-idioms/chapters/abstract_data_machines.rst | 5 +++-- content/courses/ada-idioms/chapters/abstract_data_types.rst | 4 ++-- .../ada-idioms/chapters/essential_idioms_for_packages.rst | 5 +++-- content/courses/ada-idioms/chapters/inheritance_idioms.rst | 4 ++-- content/courses/ada-idioms/chapters/introduction.rst | 4 ++-- .../courses/ada-idioms/chapters/programming_by_extension.rst | 5 +++-- content/courses/ada-idioms/chapters/type_punning.rst | 5 +++-- 7 files changed, 18 insertions(+), 14 deletions(-) diff --git a/content/courses/ada-idioms/chapters/abstract_data_machines.rst b/content/courses/ada-idioms/chapters/abstract_data_machines.rst index 4f7afd130..6d716cfb3 100644 --- a/content/courses/ada-idioms/chapters/abstract_data_machines.rst +++ b/content/courses/ada-idioms/chapters/abstract_data_machines.rst @@ -360,8 +360,9 @@ 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 + + .. rubric:: Bibliography .. [1] Booch, G. (1983). Software Engineering with Ada, Benjamin/Cummings Publishing Company. diff --git a/content/courses/ada-idioms/chapters/abstract_data_types.rst b/content/courses/ada-idioms/chapters/abstract_data_types.rst index 7735bd43b..a50138782 100644 --- a/content/courses/ada-idioms/chapters/abstract_data_types.rst +++ b/content/courses/ada-idioms/chapters/abstract_data_types.rst @@ -402,9 +402,9 @@ Notes 3. The ADT is the conceptual foundation for the *class* construct's visibility control in some class-oriented languages. +.. only:: builder_html -Bibliography ------------- + .. rubric:: Bibliography .. [1] Booch, G. (1983). Software Engineering with Ada, Benjamin/Cummings Publishing Company. 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..8b406d44f 100644 --- a/content/courses/ada-idioms/chapters/essential_idioms_for_packages.rst +++ b/content/courses/ada-idioms/chapters/essential_idioms_for_packages.rst @@ -222,8 +222,9 @@ Notes iron-clad; hybrids are possible but should be considered initially suspect and reviewed accordingly. -Bibliography ------------- +.. only:: builder_html + + .. rubric:: Bibliography .. [1] Yourdon, E. and L. L. Constantine (1979). Structured Design: Fundamentals of a Discipline of Computer Program and System Design, diff --git a/content/courses/ada-idioms/chapters/inheritance_idioms.rst b/content/courses/ada-idioms/chapters/inheritance_idioms.rst index b7753efef..7089b1a9d 100644 --- a/content/courses/ada-idioms/chapters/inheritance_idioms.rst +++ b/content/courses/ada-idioms/chapters/inheritance_idioms.rst @@ -575,8 +575,8 @@ Notes ----- +.. only:: builder_html -Bibliography ------------- + .. rubric:: Bibliography .. [1] Meyer, B. (1997). Object-Oriented Software Construction, Prentice-Hall. diff --git a/content/courses/ada-idioms/chapters/introduction.rst b/content/courses/ada-idioms/chapters/introduction.rst index c636d33ce..662cfeecb 100644 --- a/content/courses/ada-idioms/chapters/introduction.rst +++ b/content/courses/ada-idioms/chapters/introduction.rst @@ -238,9 +238,9 @@ 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 diff --git a/content/courses/ada-idioms/chapters/programming_by_extension.rst b/content/courses/ada-idioms/chapters/programming_by_extension.rst index 5972c4033..952581293 100644 --- a/content/courses/ada-idioms/chapters/programming_by_extension.rst +++ b/content/courses/ada-idioms/chapters/programming_by_extension.rst @@ -241,7 +241,8 @@ library units, some declarations in existing package bodies tended to "percolate up" to the package declarations' private parts. -Bibliography ------------- +.. only:: builder_html + + .. rubric:: Bibliography .. [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..68171f5a1 100644 --- a/content/courses/ada-idioms/chapters/type_punning.rst +++ b/content/courses/ada-idioms/chapters/type_punning.rst @@ -474,8 +474,9 @@ potential problem. For that reason, the GNAT implementation issues a warning in such cases. -Bibliography ------------- +.. only:: builder_html + + .. rubric:: Bibliography .. [1] S. Tucker Taft, 1993, post in Comp.Lang.Ada, https://groups.google.com/g/comp.lang.ada/c/9WXgvv8Xjuw/m/JMyo9_P7nxAJ From ed5fcf7c51af2ecb14f032e62c75c00993830af6 Mon Sep 17 00:00:00 2001 From: gusthoff Date: Sat, 25 Jan 2025 01:51:36 +0100 Subject: [PATCH 2/4] Editorial change: replace plain footnotes by references using bibtex --- .../chapters/abstract_data_machines.rst | 6 +- .../chapters/abstract_data_types.rst | 21 +++---- .../essential_idioms_for_packages.rst | 19 +++--- .../chapters/inheritance_idioms.rst | 8 ++- .../ada-idioms/chapters/introduction.rst | 15 ++--- .../chapters/programming_by_extension.rst | 6 +- .../ada-idioms/chapters/type_punning.rst | 6 +- content/courses/ada-idioms/references.bib | 62 +++++++++++++++++++ 8 files changed, 99 insertions(+), 44 deletions(-) create mode 100644 content/courses/ada-idioms/references.bib diff --git a/content/courses/ada-idioms/chapters/abstract_data_machines.rst b/content/courses/ada-idioms/chapters/abstract_data_machines.rst index 6d716cfb3..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. @@ -364,5 +365,4 @@ irrelevant. .. rubric:: Bibliography -.. [1] Booch, G. (1983). Software Engineering with Ada, Benjamin/Cummings - Publishing Company. +.. footbibliography:: diff --git a/content/courses/ada-idioms/chapters/abstract_data_types.rst b/content/courses/ada-idioms/chapters/abstract_data_types.rst index a50138782..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 @@ -406,11 +410,4 @@ Notes .. rubric:: 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. - -.. [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 8b406d44f..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 @@ -226,12 +229,4 @@ Notes .. rubric:: Bibliography -.. [1] Yourdon, E. and L. L. Constantine (1979). Structured Design: - Fundamentals of a Discipline of Computer Program and System Design, - Prentice-Hall. - -.. [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 7089b1a9d..0a2567e57 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. @@ -579,4 +581,4 @@ Notes .. rubric:: Bibliography -.. [1] Meyer, B. (1997). Object-Oriented Software Construction, Prentice-Hall. +.. footbibliography:: diff --git a/content/courses/ada-idioms/chapters/introduction.rst b/content/courses/ada-idioms/chapters/introduction.rst index 662cfeecb..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. @@ -242,9 +244,4 @@ For further details about type views, please refer to that .. 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 952581293..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. @@ -245,4 +246,5 @@ library units, some declarations in existing package bodies tended to .. rubric:: Bibliography -.. [1] Barnes, J. (1998). Programming In Ada 95, Addison-Wesley. +.. footbibliography:: + diff --git a/content/courses/ada-idioms/chapters/type_punning.rst b/content/courses/ada-idioms/chapters/type_punning.rst index 68171f5a1..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 @@ -478,5 +479,4 @@ such cases. .. rubric:: Bibliography -.. [1] S. Tucker Taft, 1993, post in Comp.Lang.Ada, - https://groups.google.com/g/comp.lang.ada/c/9WXgvv8Xjuw/m/JMyo9_P7nxAJ +.. footbibliography:: 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} +} From 5113a29f9dcb5d37c1d21511c077bbff83c41465 Mon Sep 17 00:00:00 2001 From: gusthoff Date: Sat, 25 Jan 2025 01:52:32 +0100 Subject: [PATCH 3/4] Sphinx: add entry for bibtex file --- content/courses/ada-idioms/conf.ini | 1 + 1 file changed, 1 insertion(+) 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 From 5732f4d3e57db15cbaa37e00431aa3b07868fc67 Mon Sep 17 00:00:00 2001 From: gusthoff Date: Sat, 25 Jan 2025 01:52:56 +0100 Subject: [PATCH 4/4] Editorial change: remove empty sections --- content/courses/ada-idioms/chapters/inheritance_idioms.rst | 2 -- content/courses/ada-idioms/chapters/interrupt_handling.rst | 3 --- 2 files changed, 5 deletions(-) diff --git a/content/courses/ada-idioms/chapters/inheritance_idioms.rst b/content/courses/ada-idioms/chapters/inheritance_idioms.rst index 0a2567e57..c94b8d1b2 100644 --- a/content/courses/ada-idioms/chapters/inheritance_idioms.rst +++ b/content/courses/ada-idioms/chapters/inheritance_idioms.rst @@ -573,8 +573,6 @@ 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 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