Jump to content

Wikibooks:WikiProject Ada

From Wikibooks, open books for an open world
Ada Lovelace

This is the place for learning or remembering all the conventions we are using for writing the Ada wikibooks:

Hint: Keep this page open for cut/copy/paste.

Attribution

[edit source]

Consider creating an account in Wikibooks, it's easy and convenient. You are only requested for a user name and a password. After logging in your contributions are assigned to a name instead of your IP address. It has other benefits see the page Why create an account? from Wikipedia.

Demo Sources

[edit source]

Unlike most other books from the Programming series we aim to provide not only code snippets but also and foremost fully working demos.

In order to ease handling of the demonstration programs a connected SourceForge project called wikibook-ada has been registered.

As a contributer you can take advantage of the svn repository to store your sources. You can also create links from Programming:Ada to your sources using viewscvs. You can use the Template:Ada/Sourceforge to create the links

SourceForge also allows us to offer downloads of all demo sources.

Last but not least, SourceForge provides us download statistics, so we can see if our offer is accepted.

Heading

[edit source]

All pages should have a heading like this:

<noinclude>
 {{Ada/Navigation}}
 __TOC__
 </noinclude>

Formerly there were "Ada/Navigation 1" to "Ada/Navigation 3" (for one to tree level deep navigation), but they are obsolete now, since the navigation inside the book is provided by the subpage features.

An online documentation like Ada Programming lives from "clickable" text - a click and you get more detail on anything you are interested. So do make links!

Keywords et al.

[edit source]

Language features like Keywords, Pragmas etc. should be written like this:

 Keywords:         {{Ada/kw|abort}} or {{Ada/keyword|new}}
 Operators:        {{Ada/op|&}} or {{Ada/operator|+}}
                   {{Ada/op|1 = <=}} or {{Ada/op|1 = =}}
 Delimiters:       {{Ada/dl|:}} or {{Ada/delimiter|:}}
                   {{Ada/dl|1 = :=}} or {{Ada/dl|1 = =>}}
 Types:            '''[[Ada Programming/Types/range|range]]'''
 Attributes:       X'{{Ada/at|Access}} or X'{{Ada/attribute|Access}}
 Pragmas:          {{Ada/pragma|No_Return}} or {{Ada/pragma name|No_Return}}
 Packages:         {{Ada/package|Standard}}
 Child Packages:   {{Ada/package|Ada|Text_IO}}, {{Ada/package|Ada|Containers|Vectors}}, ...
 Restrictions:     {{Ada/restriction|No_Obsolescent_Features}} or {{Ada/restriction name|No_Obsolescent_Features}}
 Comments:         {{Ada/--|This is a comment}} or {{Ada/comment|This is a comment}}
 Sourceforge link: {{Ada/Sourceforge|numeric_1.adb}}
 

which will then look like:

Keywords:         abort or new
Operators:        & or +
                  <= or =
Delimiters:       : or :
                  := or =>
Types:            range
Attributes:       X'Access or X'Access
Pragmas:          pragma No_Return or No_Return
Packages:         Standard
Child Packages:   Ada.Text_IO, Ada.Containers.Vectors, ...
Restrictions:     pragma Restrictions (No_Obsolescent_Features) or No_Obsolescent_Features
Comments:         -- This is a comment or -- This is a comment

Sourceforge link:

File: numeric_1.adb (view, plain text, download page, browse all)

ASnip, written by User:GorgeUbuasha, can help in the addition of the templates to Ada source code.

Note for Operators
All operators are either a keyword or a delimiter. Hence, all operator pages are only redirects to the appropriate keyword or delimiter. However, in demo sources the rendering of operators, keyword and special character are different.

See also

[edit source]

Any page should have a "See also" section, which should look like this:


== See also ==

=== Wikibook === 

* [[Ada Programming]]
* [[Ada Programming/Operators]]

=== Ada 95 Reference Manual ===

* {{Ada/95/RM2|4|4|Expressions}}
* {{Ada/95/RM3|4|5|5|Multiplying Operators}}
* {{Ada/95/RMA3|A|4|3|Fixed-Length String Handling}}
* {{Ada/95/RMA3|A|4|4|Bounded-Length String Handling}}
* {{Ada/95/RMA3|A|4|5|Unbounded-Length String Handling}}
* {{Ada/95/RMA3|A|18|2|The Package Containers.Vectors}}

=== Ada 2005 Reference Manual ===

* {{Ada/2005/RM|4|4|title=Expressions}}
* {{Ada/2005/RM|4|5|5|title=Multiplying Operators}}
* {{Ada/2005/RMA|A|4|3|title=Fixed-Length String Handling}}
* {{Ada/2005/RMA|A|4|4|title=Bounded-Length String Handling}}
* {{Ada/2005/RMA|A|4|5|title=Unbounded-Length String Handling}}
* {{Ada/2005/RMA|A|18|2|title=The Package Containers.Vectors}}

=== Ada Quality and Style Guide ===

* {{Ada/SG1|1|Introduction}}
* {{Ada/SG2|4|1|High-Level Structure}}
* {{Ada/SG3|5|5|5|Short Circuit Forms of the Logical Operators}}
* {{Ada/SG3|10|5|2|Short-Circuit Operators}}

{{BookCat}}

Wikibook
Always add a link to the Ada Programming main page.
Ada Reference Manual
Look up relevant pages in the index of the RM.
Ada Quality and Style Guide
Look up relevant guidelines in the index of this guide.
Category
All pages should be added to the "Ada Programming" Category using the template {{BookCat}}).

Normalized sections

[edit source]

The wikibook readability is enhanced if we follow some conventions, like a standard number of sections.

Attributes and pragmas

[edit source]

Sections for pages describing each pragma and attribute (see for example the pages about pragma Atomic and the 'Bit_Order attribute.):

  • syntax summary
  • description, specifying the pragma/attribute category (representation, configuration...) and if it is obsolescent or implementation defined.
  • illustrative example
  • portability:
    • between Ada versions
    • between compilers
    • between platforms (architecture, operating system, embedded/self-hosted, uniprocessor/multiprocessor...)
  • equivalent feature in other languages for interfacing (for pragmas)

Coding rules

[edit source]

Description about how to check good programming practices (e.g. no goto statement) with static analysis tools:

List of templates for the wikibook

[edit source]

This is the list of templates available for the Ada Programming wikibook. See also Category:Book:Ada Programming/Templates.

Language elements

[edit source]

Ada code

[edit source]
Ada language elements
Template Short Notes
{{Ada/keyword}} {{Ada/kw}} Usage:
  • {{Ada/kw|elsif}} gives elsif
{{Ada/operator}} {{Ada/op}}

Normal usage:

  • {{Ada/op|&}} gives &
  • {{Ada/operator|rem}} gives rem (only within paragraphs, use {{Ada/kw}} for code snippets)

When the delimiter contains an equal sign ('=') the explicit named parameter ('1=') is required:

  • {{Ada/op|1==}} gives =
  • {{Ada/op|1=>=}} gives >=
{{Ada/delimiter}} {{Ada/dl}}

Normal usage:

  • {{Ada/dl|'}} gives '

When the delimiter contains an equal sign ('=') the explicit named parameter ('1=') is required:

  • {{Ada/dl|1=:=}} gives :=
  • {{Ada/dl|1==>}} gives =>

For technical limitations the pipe '|' is not allowed as a template parameter, so the ASCII number must be used instead:

  • {{Ada/delimiter|&#124;}} gives |
{{Ada/attribute}} {{Ada/at}}

Usage:

  • {{Ada/attribute|Range}} gives Range

the tick (') is not included by default, but you can add it optionally:

  • {{Ada/at|'|Range}} gives 'Range
{{Ada/package}} {{Ada/pk}} for child packages the template accepts multiple parameters:
{{Ada/aspect}} {{Ada/as}}

Usage:

or Template:Ada/aspect name which does not insert the => delimiter:

{{Ada/pragma}}

Usage:

or Template:Ada/pragma name which does not insert the pragma keyword:

  • {{Ada/pragma name|Pure}} gives Pure
{{Ada/restriction}}

Usage:

or Template:Ada/restriction name which does not insert "pragma Restrictions":

{{Ada/comment}} {{Ada/--}} Usage:
  • {{Ada/--|Line comment}} gives -- Line comment
{{Ada/string}} {{Ada/"}} Usage:
  • {{Ada/"|String literal}} gives "String literal"
{{Ada/character}} {{Ada/ch}} Usage:
  • {{Ada/ch|A}} gives 'A'
{{Ada/integer}} {{Ada/in}}

Normal usage:

  • {{Ada/in|1_024_000}} gives 1_024_000

The base can also be specified (and optionally the exponent):

  • {{Ada/in|16|FFFF_0000}} gives 16#FFFF_0000#
  • {{Ada/in|16|FFFF|4}} gives 16#FFFF#4
{{Ada/real}} {{Ada/re}}

Normal usage:

  • {{Ada/re|3.14159_26535}} gives 3.14159_26535

The base can also be specified (and optionally the exponent):

  • {{Ada/re|16|AB.01}} gives 16#AB.01#
  • {{Ada/re|16|1.F|-2}} gives 16#1.F#-2

Full example:

 {{Ada/restriction|No_Obsolescent_Features}};
 
 {{Ada/kw|with}} {{Ada/package|Ada|Text_IO}};
 {{Ada/kw|with}} {{Ada/package|Ada|Characters|Latin_1}};
 
 {{Ada/kw|procedure}} Print_Constants {{Ada/kw|is}}
 
    {{Ada/kw|package}} T_IO    {{Ada/kw|renames}} {{Ada/package|Ada|Text_IO}};
    {{Ada/kw|package}} Latin_1 {{Ada/kw|renames}} {{Ada/package|Ada|Characters|Latin_1}};
 
 {{Ada/kw|begin}}
 
    T_IO.Put_Line (Item {{Ada/dl|1==>}} {{Ada/"|Hello!}});        {{Ada/--|String literal}}
    T_IO.Put_Line (Latin_1.Not_Sign {{Ada/op|&}} {{Ada/ch|P}});  {{Ada/--|Character literal (¬P)}}
    T_IO.Put_Line (Integer{{Ada/at|'|Image}} ({{Ada/in|42}}));      {{Ada/--|Integer literal}}
    T_IO.Put_Line (Float{{Ada/at|'|Image}} ({{Ada/re|3.1416}}));    {{Ada/--|Real literal}}
 
 {{Ada/kw|end}} Print_Constants;

gives:

pragma Restrictions (No_Obsolescent_Features);

with Ada.Text_IO;
with Ada.Characters.Latin_1;

procedure Print_Constants is

   package T_IO    renames Ada.Text_IO;
   package Latin_1 renames Ada.Characters.Latin_1;

begin

   T_IO.Put_Line (Item => "Hello!");        -- String literal
   T_IO.Put_Line (Latin_1.Not_Sign & 'P');  -- Character literal (¬P)
   T_IO.Put_Line (Integer'Image (42));      -- Integer literal
   T_IO.Put_Line (Float'Image (3.1416));    -- Real literal

end Print_Constants;

C code

[edit source]
C language elements
Template Short Notes
{{Ada/C/keyword}} {{Ada/C/kw}} Usage:
  • {{Ada/C/kw|void}} gives void
{{Ada/C/comment}} {{Ada/C/*}} Usage:
  • {{Ada/C/*|This is a block comment}} gives /* This is a block comment */
{{Ada/C/preprocessor}} {{Ada/C/pre}} Usage:
  • {{Ada/C/pre|#include <stdio.h>}} gives #include <stdio.h>
[edit source]

Ada Reference Manual

[edit source]

Except when required, the preferred option is to put a link to the last official version.

Ada Quality and Style Guide

[edit source]

Ada Rationale

[edit source]

Note: there are not templates redirections to the last version of the rationale because every version of the language has its own rationale, completely different from the others.

Ada Issues

[edit source]

Source code repositories

[edit source]
Name Notes
{{Ada/Sourceforge}}

External link to source code in wikibook-ada project

{{Sourceforge links}}

External links to homepage, source code and download page for a Sourceforge library project.

Single parameter is project name. (Possibly useful for other books)

{{GitHub links}}

External links to homepage, source code and download page for a GitHub library project.

First parameter is user or organization name, second is the repository name. (Possibly useful for other books)

[edit source]
Name Notes
{{Ada/Standard libraries}} Search for examples and posts about a standard unit. Search term is got from page name.
{{Ada/GNAT}} Link to the implementation of a standard library unit in GNAT.

Single parameter is filename.

{{Ada/drake}} Link to the implementation of a standard library unit in drake.

Single parameter is filename.

References

[edit source]

Ada specific

[edit source]
Ada-specific citation templates
Name Notes
{{Ada/83/Cite RM}}
{{Ada/95/Cite RM}}
{{Ada/2005/Cite RM}}
{{Ada/2012/Cite RM}}

All parameters are optional, except title and the first one (section number):

{{Ada/2005/Cite RM|(section)|(subsection)|(sub-subsection)
 |      title = (required)
 |        par = 
 |         id = 
 |      quote = 
}}

For example:

*{{Ada/2005/Cite RM|13|5|3
 |      title = Bit Ordering
 |        par = 2
 |         id = I4589
 |      quote = A bit ordering is a method of interpreting the meaning of the storage place attributes.
}}

gives:

  • ISO/IEC 8652:2007. "13.5.3 Bit Ordering (2)". Ada 2005 Reference Manual. A bit ordering is a method of interpreting the meaning of the storage place attributes. {{cite book}}: Unknown parameter |chapterurl= ignored (|chapter-url= suggested) (help)
{{Ada/83/Cite AARM}}
{{Ada/95/Cite AARM}}
{{Ada/2005/Cite AARM}}
{{Ada/2012/Cite AARM}}

All parameters are optional, except title and the first one (section number):

{{Ada/2005/Cite AARM|(section)|(subsection)|(sub-subsection)
 |      title = (required)
 |        par = 
 |         id = 
 |      quote = 
}}

For example:

*{{Ada/2005/Cite AARM|13|5|3
 |      title = Bit Ordering
 |        par = 2
 |         id = I5077
 |      quote = A bit ordering is a method of interpreting the meaning of the storage place attributes.
}}

gives:

  • Ada Rapporteur Group. "13.5.3 Bit Ordering (2)". Annotated Ada 2005 Reference Manual. A bit ordering is a method of interpreting the meaning of the storage place attributes. {{cite book}}: Unknown parameter |chapterurl= ignored (|chapter-url= suggested) (help)

Note that it links to the same paragraph as above, but the 'id' parameter has a different value in the AARM than in the LRM.

{{Ada/95/Cite AI}}
{{Ada/2005/Cite AI}}

All parameters are optional, except title and id:

{{Ada/95/Cite AI
 |      title = (required)
 |         id = (required)
 |        alt = 
 |      class = 
 |       date = 
 |        rev = 
 |      quote = 
 | accessdate = 2024-12-22
}}

For example, the following instantiation:

*{{Ada/95/Cite AI
 |      title = Limited With Clauses
 |         id = 217
 |        alt = 6
 |      class = Amendment
 |       date = 2005-10-11
 |        rev = 1.21
 |      quote = 
 | accessdate = 2009-01-01
}}

gives:

  • AI95-00217-06 (2005-10-11). "Limited With Clauses". Class: Amendment. Ada Rapporteur Group. Retrieved 2009-01-01.
{{Ada/Cite ACM}}

Citation to the ACM SIGAda Ada Letters.

All parameters are optional, except title:

{{Ada/Cite ACM
 |     author = 
 |      title = (required)
 |       year = 
 |      month = 
 |     volume = 
 |      issue = 
 |      pages = 
 |        doi = 
 |        url = 
 |      quote = 
 | accessdate = 2024-12-22
}}

The following instantiation:

*{{Ada/Cite ACM
 |     author = Alan Burns, Brian Dobbing, Tullio Vardanega
 |      title = Guide for the use of the Ada Ravenscar Profile in high integrity systems
 |       year = 2004
 |      month = June
 |     volume = XXIV
 |      issue = 2
 |      pages = 1&ndash;74
 |        doi = 10.1145/997119.997120
 |        url = http://www.sigada.org/ada_letters/jun2004/ravenscar_article.pdf
}}

gives:

{{Ada/Cite AUJ}}

Citation to the Ada User Journal, published by Ada-Europe. Tagline: "The journal for the international Ada community"

All parameters are optional, except title:

{{Ada/Cite AUJ
 |     author = 
 |      title = (required)
 |       year = 
 |      month = 
 |     volume = 
 |     number = 
 |      pages = 
 |        url = 
 |      quote = 
 | accessdate = 2024-12-22
}}

The following instantiation:

*{{Ada/Cite AUJ
 |     author = Alan Marriott, Urs Maurer
 |      title = Ada Bug Finder
 |       year = 2005
 |      month = September
 |     volume = 26
 |     number = 3
 |      pages = 214&ndash;219
 |        url = http://www.ada-europe.org/archive/auj/auj-26-3.pdf
}}

gives:

{{Ada/Cite cla}}

Citation to 'comp.lang.ada' newsgroup:

{{Ada/Cite cla 
 |     author = 
 |      title = (required)
 |       date = 
 |        url = 
 |      quote = 
 | accessdate = 2024-12-22
}}

The following instantiation:

*{{Ada/Cite cla 
 |     author = Robert Dewar
 |      title = pragma Shared (was Ada is almost ....)
 |       date = 1996-02-17
 |        url = http://groups.google.es/group/comp.lang.ada/msg/eeee3a7515837ea2
 |      quote = pragma Atomic is QUITE different from pragma Volatile.
 | accessdate = 2008-05-28
}}

gives:

  • Robert Dewar (1996-02-17). "pragma Shared (was Ada is almost ....)". comp.lang.ada. (Web link). Retrieved on 2008-05-28. "pragma Atomic is QUITE different from pragma Volatile."
{{Ada/83/Cite R}}
{{Ada/95/Cite R}}
{{Ada/2005/Cite R}}
{{Ada/2012/Cite R}}
{{Ada/83/Cite SG}}
{{Ada/95/Cite SG}}
{{Ada/Ref RM}}
{{Ada/83/Ref RM}}
{{Ada/95/Ref RM}}
{{Ada/2005/Ref RM}}
{{Ada/2012/Ref RM}}

All parameters are optional, except the first one (section number):

{{Ada/Ref RM|(section)|(subsection)|(sub-subsection)|par=|id=}}

For example:

{{Ada/Ref AARM}}
{{Ada/83/Ref AARM}}
{{Ada/95/Ref AARM}}
{{Ada/2005/Ref AARM}}
{{Ada/2012/Ref AARM}}

All parameters are optional, except the first one (section number):

{{Ada/Ref AARM|(section)|(subsection)|(sub-subsection)|par=|id=}}

For example:

General

[edit source]
General citation templates
Name Notes
{{cite book}}

All parameters are optional, except title:

{{cite book
 |     author = 
 |     editor = 
 |     others = 
 |      title = (required)
 |        url = 
 |    chapter = 
 | chapterurl = 
 |      pages = 
 |   origdate = 
 |   origyear = 
 |  origmonth = 
 |     format = 
 |    edition = 
 |       date = 
 |       year = 
 |      month = 
 |  publisher = 
 |   location = 
 |   language = 
 |         id = 
 |        doi = 
 |      quote = 
 | accessdate = 2024-12-22
}}

For example, the instantiation:

*{{cite book
 |     author = [[w:John Barnes (computer scientist)|]]
 |      title = High-Integrity Software: The SPARK Approach to Safety and Security
 |       date = 2003-03-25
 |  publisher = Addison-Wesley
 |       isbn = 0-321-13616-0
 |        url = http://dl.acm.org/citation.cfm?id=829555
 | accessdate = 2008-06-06
 |      quote = Representation clauses are now strictly known as aspect clauses
 |      pages = 212
}}

gives:

{{cite journal}}

(NOTE: Use templates {{Ada/Cite ACM}} or {{Ada/Cite AUJ}} above for citations to 'ACM SIGAda Ada Letters' or 'Ada User Journal')

All parameters are optional, except title:

{{cite journal
 |     author = 
 |      title = (required)
 |    journal = 
 |      pages = 
 |     volume = 
 |      issue = 
 |       date = 
 |       year = 
 |      month = 
 |  publisher = 
 |       issn = 
 |        url = 
 |      quote = 
 | accessdate = 2024-12-22
}}

For example, the instantiation:

*{{cite journal
 |     author = Daniel Ramirez
 |      title = Robotics with Ada 95
 |    journal = Circuit Cellar
 |      issue = 212
 |       year = 2008
 |      month = March
 |        url = http://www.circuitcellar.com/archives/viewable/212-Ramirez/
 | accessdate = 2009-01-01
}}

gives:

{{cite conference}}

All parameters are optional, except title and booktitle:

{{cite conference
 |       author = 
 |        title = (required)
 |   conference = 
 |conferenceurl = 
 |    booktitle = (required)
 |         date = 
 |         year = 
 |        month = 
 |       editor = 
 |       others = 
 |       volume = 
 |      edition = 
 |    publisher = 
 |     location = 
 |        pages = 
 |          doi = 
 |           id = 
 |         oclc = 
 |          url = 
 |       format = 
 |        quote = 
 |   accessdate = 2024-12-22
}}

For example, the instantiation:

*{{cite conference
 |       author = Gaetan Allaert, Dirk Craeynest, Philippe Waroquiers
 |        title = European air traffic flow management: porting a large application to GNU/linux
 |   conference = SIGAda'03
 |conferenceurl = http://www.sigada.org/conf/sigada2003/SIGAda2003-CDROM/SIGAda2003-Proceedings/00-proceedings.html
 |    booktitle = Proceedings of the 2003 annual ACM SIGAda international conference on Ada
 |         year = 2003
 |        pages = 29&ndash;37
 |          doi = 10.1145/958420.958426
 |         isbn = 1-58113-476-2
 |          url = http://www.sigada.org/conf/sigada2003/SIGAda2003-CDROM/SIGAda2003-Proceedings/p29-allaert.pdf
 |   accessdate = 2009-01-02
}}

gives:

{{cite paper}}

All parameters are optional, except title:

{{cite paper
 |     author = 
 |      title = (required)
 |    version = 
 |      pages = 
 |  publisher = 
 |       date = 
 |        url = 
 |     format = 
 |         id = 
 |      quote = 
 | accessdate = 2024-12-22
}}

For example, the instantiation:

*{{cite paper
 |     author = Stephen F. Zeigler
 |      title = Comparing Development Costs of C and Ada
 |       date = 1995-03-30
 |        url = http://archive.adaic.com/intro/ada-vs-c/cada_art.html
 |      quote = Our data indicates that Ada has saved us millions of development dollars.
 | accessdate = 2009-01-02
}}

gives:

{{cite web}}

All parameters are optional, except url, title, and accessdate:

{{cite web
 |        url = (required)
 |      title = (required)
 | accessdate = 2024-12-22
 |     author =
 |       date = 
 |       year = 
 |      month = 
 |     format = 
 |       work = 
 |  publisher = 
 |      pages = 
 |   language = 
 | archiveurl = 
 |archivedate =
 |      quote = 
}}

For example, the instantiation:

*{{cite web
 |        url = http://archive.adaic.com/news/pressrelease/Ada05-final.html
 |      title = Ada 2005 Becomes Official ISO Standard
 | accessdate = 2009-01-02
 |       date = 2007-03-09
 |  publisher = Ada Resource Association
 | archiveurl = http://web.archive.org/web/20071208105755/http://www.adaic.com/news/Ada05-final.html
 |archivedate = 2007-12-08
}}

gives:

{{cite newsgroup}}

(NOTE: Use the template {{Ada/Cite cla}} above for citations to 'comp.lang.ada')

All parameters are optional, except title:

{{cite newsgroup 
 |     author = 
 |      title = (required)
 |       date = 
 |  newsgroup = 
 |        url = 
 |      quote = 
 | accessdate = 2024-12-22
}}

For example, the instantiation:

*{{cite newsgroup 
 |     author = Pat Rogers
 |      title = Ada as a real time language
 |       date = 2002-08-28
 |  newsgroup = comp.realtime
 |        url = http://groups.google.es/group/comp.realtime/msg/355d3c9ab43fcb77
 |      quote = you don't need an RTOS to write real-time systems with Ada
 | accessdate = 2009-01-05
}}

gives:

  • Pat Rogers (2002-08-28). "Ada as a real time language". comp.realtime. (Web link). Retrieved on 2009-01-05. "you don't need an RTOS to write real-time systems with Ada"
[edit source]


Software

[edit source]

Emacs users might find this Emacs Lisp file helpful when editing Ada programs for inclusion in Wiki pages. ada-to-wiki.el

A similar pure Ada program, ASnip, will do the same using standard input/output. Useful with vi and other editors.

Tracking changes

[edit source]

Contributors are encouraged to track recent changes to the book in order to fix bad editions, improve new content, discuss changes with other contributors and keep work coherence. The watchlist feature is also useful for that after manually adding the pages that you want to track.