The ada-lang-io from ada-lang-io

Limit "Table of content" to level 1-2

I would appreciate to have a more compact heading table (say level 1 to 2) some-where.

«Table of content» is far too long and boring to scroll (I know it’s the official one ... but Ada-Auth’s is visually more compact, and scrollable)
Could you insert a specific «Table of content» for the Standard libraries at https://ada-lang.io/docs/arm/AA-0.3 ?

Thanks
William

Syntax highlighting theme

Themes from prism-react-renderer are kinda ugly.

Investigate using using Shiki through docusaurus-preset-shiki-twoslash, which uses vscode grammers. Shiki themes.

Write content for pages in Getting Started section

I've added some stubs to Getting Started section (visible in development build):

Content should be added to these pages (they currently just have some headers and "TODO"s) by people who want to help.

Reference Manual Integration

Top Ticket for tracking Reference Manual Integration work:

Updates don’t appear on web page

Of these PRs, which were merged yesterday (17 Feb), only the first is visible.

#76 Getting Started/Editors
#77 Getting Started/Installation
#78 MacOS/Issues

Important keywords for search engines

When searching for Ada sites one usually has to add "programming", "development" or "language", otherwise we know the usual suspects that the engine retrieves. I know the current content is only a stub, but currently there are no instances of those words (unless search engines consider the abbreviations "lang" and "dev" as synonym). In any case, I think these are important keywords to include in the final main page.

Add license

The repo misses a license file.

Add Site Search

Tracker ticket to show I've applied for Algolia search support, as recommended in the Docusaurus.io docs.

Slack application

Could you enable Slack support for this repo(/organization)?

Previous / Next buttons on top of page

I would appreciate to have «Previous» / «Next» buttons (also) on top of each page.

I (we ?) go from pages to pages essentially when you are searching/reading through a Standard Library

Thanks
William

SVGs look bad in dark mode

The main page SVGs are black on transparent background, so they don't show up well in dark mode.

Logo improvements

Hey guys,

Looking at the logo for some time now, I did a revision I think is better. Here it is in case you would like to change:
https://github.com/ohenley/files/blob/master/ada_logo_orbitron.svg

Thx!

Environment setup page

Add a page to describe setting up an environment for development:

Using VS Code + Ada language server
User GNAT Studio
How to do debugging

Verify autodeploy/push

When I run npm run deploy it seems like it overwrites Github's targeting of ada-lang.io. I'm not sure if I missed a setting somewhere. Also, the site should autodeploy without us needing to use docusaurus script.

Alignment issues in code blocks

This is especially apparent in https://ada-lang.io/docs/arm/AA-A/AA-A.10/

Style guide shows up in `yarn start` but not `yarn build` and `yarn serve`.

Code blocks on landing page

Add some code blocks with syntax highlighting in a few tabs showcasing some features of the language:

Basic example
Embedded (RP2040?)
SPARK

Interactive (user can edit code and hit 'Compile and run' button) would be even nicer.

Convert Programming-with-Ada language comparison table

I'm not sure the best way to do this, which is why I'm opening an issue here.

The table of language comparisons on Programming-with-Ada is awesome. The question is about the appropriate way to port it over to markdown and maybe make it easier to read.

Should it have toggles to enable/disable the C++ and/or Rust columns?

Should this table be generated by data instead of being hardcoded?

Automatically fetch latest Alire version using GitHub's API

Currently, alireVersion is hardcoded in src/pages/index.js. Instead, fetch https://api.github.com/repos/alire-project/alire/releases/latest somehow before yarn build and yarn start.

Use a custom plugin with loadContent() (docusaurus-plugin-remote-content accepts only .md files)

Upgrade to Docusaurus v3

Docusaurus v3.0 was released a few months ago. It brings a few breaking changes and major updated to its dependencies, specially MDX. They have an [upgrade guide] available that details the tasks that would need to be carried out in order to upgrade a v2 project to a v3 one.

I am opening this issue since I believe it would be best to upgrade major project dependencies, specially when there are breaking changes, in order to not fall behind and accumulate technical debt.

I personally do not have the time nor knowledge to carry out this task, but I think it would be benefitial to the project overall. The latests Docusaurus version is currently v3.1, which fixes some bugs from v3.0.

Best regards,
Fer

Use docusaurus' versioning for the revisions of the language for the Reference Manual pages

Generate versioned files for [83/95/]2005/2012/2022

Handle tables

Integrate Reference Manual

Just one reference manual (no completely distinct ARM and AARM)
Provide a simple way (an on/off switch) to show/hide the annotations of the AARM
Current ARM has some code snippets, these could get syntax highlighting

Some problems in Syntax Cheat Sheet

https://ada-lang.io/docs/learn/cheat-sheet

Repeated rows:

ada-lang-io/docs/learn/cheat-sheet.mdx

Lines 24 to 31 in 36c5ff1

    
           <tr> 
        
             <td> Pointer </td> 
        
             <td> Access All </td> 
        
           </tr> 
        
           <tr> 
        
             <td> Pointer </td> 
        
             <td> Access All </td> 
        
           </tr>

What is N/A?:

ada-lang-io/docs/learn/cheat-sheet.mdx

Lines 135 to 137 in 36c5ff1

    
           <td></td> 
        
           <td> 
        
             <strong>N/A</strong>

Repetition procedure Foo procedure Foo:

ada-lang-io/docs/learn/cheat-sheet.mdx

Line 675 in 36c5ff1

<CodeBlock>overriding procedure Foo procedure Foo(obj : in Object)</CodeBlock>

What is this row?:

ada-lang-io/docs/learn/cheat-sheet.mdx

Lines 235 to 237 in 36c5ff1

    
           <td></td> 
        
           <td> 
        
             <CodeBlock>pragma Restrictions(No_Dependencies =&gt; Other_Package)</CodeBlock>

And other things that could be improved.

Integrate other personal tools available in the Ada community

It would be nice to have these "community" tools in the site. What do you think? I ping the authors so they are aware of the discussion and can express their permissions or turndowns.

Ada/SPARK custom search engine https://thindil.github.io/adasearch/ by @thindil
News aggregator https://www.laeran.pl/adaplanet/i/ by @thindil
Search code in Alire crates https://search.synack.me/ (makes even more sense to be integrated in alire.ada.dev, but meanwhile it's not there, it would be a nice addition) by @JeremyGrosser
awesome-ada https://github.com/ohenley/awesome-ada by @ohenley
anything else?

I'm not sure about the technical side. I suppose the dynamic pages would need their own subdomain and hosting, but could follow the same site style and backlinks. Awesome-ada, in turn, could be copied on change and directly included in docsaurus inserting a link to the original for edition and attribution.

When there are MarginText components inside a CodeBlock, the Ada syntax highlighting is not applied. Example: https://ada-lang.io/docs/arm/AA-A/AA-A.18#p147.1

Add page "Building Blocks" to "The Big Five Structural Elements"?

Page "The Big Five Structural Elements" reads like an introduction. The content of page "Building Blocks" could be modified and then appended to the former.

"The Core Tenet of Ada" section in "Building Blocks" also has a quite a big code block.

Mixing subprogram keywords in documentation

While the documentation does elaborate that procedures and functions can be referred to as subprograms, there are few spots where the verbiage is unclear. That is, referring to procedures as functions.

subprogram visibility in the building blocks section
nested subprograms in the being more terse section
overriding subprograms in the advanced techniques section

The fix can be as simple as replacing the use of function with subprogram or procedure.

Very nice job with the site! I love Ada. Looking forward to using Alire more in my Ada projects!

Add analytics

There's a Docusaurus plugin plugin-google-gtag for Google Analytics 4 (free?) if we want people to sell their soul to Google.

OSS options are Matomo (€ 19/m, cloud in Germany, see here for comparison with GA4) and PostHog (cloud (in the US?), free first 1 million events). Both can be self-hosted.

Animated sequence of background photos on landing page

In branch topic/hero-animated-bg I have implemented the CSS to perform an animation of multiple background photos. It takes about 20s to transition to the next photo.

The placeholder photos should be replaced with some showing hardware/apps which actually use Ada.

I'm not 100% sure about this feature though; it looks nice, but it also requires fetching of multiple images. It depends on whether people are excited about it or not 🙂

Add Crates page

List of all crates
Top 10 last updated crates
Top 10 newest crates

On a page of a crate:

Display crate's README.md
Published versions
Dependencies and dependent crates

Drop in paragraph number noticed in 3.2 Types and Subtypes

In 3.2 Types and Subtypes The paragraph number 3 has the content of the actual paragraph number 2 in the 22ARM chapter 3.2.
Also in 3.2 Types and Subtypes There is no paragraph number 4.
So, because of these two drops, the actual paragraph number 3 is numbered 5.

Upgrade Mantine to version 7

Docusaurus 3 interactions with Mantine and the required prism-react-renderer 2+ upgrade have disable syntax highlighting on the landing page.

Wrong link in subsection

If I’m on this page: https://ada-lang.io/docs/arm/AA-10/AA-10.1/#1013--subunits-of-compilation-units and I click on the (15) I end up here: https://ada-lang.io/docs/arm/AA-10/AA-10.1/#p15.

Note, the para number in the ARM is 14, http://www.ada-auth.org/standards/rm12_w_tc1/html/RM-10-1-3.html#p14

FAQ page

Is it worth to collect frequent questions on a dedicated page?

Doc: Environment setup

Objectives

Describe how to set up an environment for working in Ada.
Recommended IDE, Editors, and Plugins
Basic Alire usage
Debugging
Setting up unit tests
Enabling and disabling checks during development

This is separate from the tutorial, so people who don't want to go through the tutorial and just jump straight into setup.

Move AI references to outside of main text

So, this is a bit of an unconventional suggestion, and diverges significantly from the AARM/LRM at ada-auth.org, but I think it would definitely make things easier to understand and follow.

As it currently stands, AIs are liberally inserted throughout the text of the AARM, and for me at least this interrupts my reading flow. (AIs are also duplicated heavily in some sections.) Thus, my suggestion is to do what a lot of texts do when they need to cite something, and add something like a "references in text" (or "issues in text" or something along those lines) section that lists all the AIs and their titles in one convenient section. I don't know how feasible this is (it'd require modification of the formatting tool) but it would make comprehending the (annotated) reference manual much easier, I think.

Links from Wikibooks to ada-lang.io ARM

I was experimenting with the Wikibooks template we use for linking to the official ARM. My idea was to add an additional link to the ada-lang.io edition.

The links could be displayed as:

C.3.2: The Package Interrupts (Annotated) (ada-lang.io)

There is a problem with three level sections, though, the URL is a bit complex for the MediaWiki template mechanism (or my current knowledge of it). The issue is with the inclusion of the internal section title in the anchor links. Consequently, without implementing a solution here or in Wikibooks, the links would be only up to the level two section pages.

My trial is currently stored in https://en.wikibooks.org/wiki/User:ManuelGR/Template:Ada/RM

Let me know if you are interested, and when the change should be implemented, considering that the ARM formatting is still work-in-progress.

Line 5 is cut off on Ada code snippet

On the main page, the line is cut off on the Ada code snippet, at least for my computer in Firefox and Chrome. See attached screenshot.

The simplest solution is probably to change line 5 from:

     with Dynamic_Predicate => (for all C of GUID => C in '0' .. '9' | 'a' .. 'f');

To:

     with Dynamic_Predicate =>
       (for all C of GUID => C in '0' .. '9' | 'a' .. 'f');

macOS quarantines the Alire executable

On the Ada tab, in 'Set-up Environment', it would be good if - on macOS - this additional note could be added after downloading (and unpacking) (see alire/doc/getting_started.md):

If you try to run it on recent versions of macOS, you will get a popup saying “alr” cannot be opened because the developer cannot be verified. and inviting you to move it to the bin. The way round this is to remove the quarantine attribute,

$ xattr -d com.apple.quarantine bin/alr

Broken notes in many pages of the Style Guide

For example, the indentation in this line breaks the note box:

ada-lang-io/docs/style-guide/Portability.mdx

Line 2048 in 637c3ca

:::note

See https://ada-lang.io/docs/style-guide/Portability#inputoutput-1

It happens after all the lists.

I run the import-style-guide expecting to find an easy-to-fix bug, but in my output all lines have correct indentation.

So, what happens? Differing pandoc versions (mine is 2.5)? Already fixed, but output not synchronized?

Paragraph 1.1.4(14) needs an alternative for assistive technology

This may not be the best place to report this, but this seemed like the best forum for it. Paragraph 1.1.4(14) (which states that "[I]f the name of any syntactic category starts with an italicized part, it is equivalent to the category name without the italicized part," and that "[T]he italicized part is intended to convey some semantic information") makes the manual difficult to comprehend (particularly in text form) via assistive technology. Though assistive technology can identify differences in font and style, it is usually a global setting, and not something that can be set at the process or document level. This makes the grammar more difficult to read because it raises questions that the document answers to individuals who can see these differences. I see a few options to resolve this problem:

When generating the content of the RM and ARM, replace the nonterminals with what they represent. Using the example provided in 1.1.4(14) as an example, we would replace task_name and subtype_name with name.
Provide an alternative view of the manual that performs option 1.
Indicate, via extra BNF productions, what each italicized reference refers to. For example, the definition which specifies subtype_name (3.2.2(4)) would have an extra production, changing it from its current form to:

2/3     {AI05-0183-1} subtype_declaration ::= 
           subtype defining_identifier is subtype_indication
                [aspect_specification];

3/2     {AI95-00231-01} subtype_indication ::=  [null_exclusion
        ] subtype_mark [constraint]

4       subtype_mark ::= subtype_name

5       subtype_name ::= name

5.a         Ramification: Note that name includes attribute_reference; thus,
            S'Base can be used as a subtype_mark.

5.b         Reason: We considered changing subtype_mark to subtype_name.
            However, existing users are used to the word "mark," so we're
            keeping it.

6       constraint ::= scalar_constraint | composite_constraint

7       scalar_constraint ::= 
             range_constraint | digits_constraint | delta_constraint

8       composite_constraint ::= 
             index_constraint | discriminant_constraint

And so on and so forth throughout the entirety of the grammar. It might also be wise to add any other missing BNF constructs; that is, convert narrative rules into BNF, at least in the syntax summary, since that is (supposed) to be a complete description of the language, and one should be able to build a minimal parser using that summary alone, excluding all the checks and extra implementation-specific details. If this is something that is more suited to the Ada RM mailing list, or the Ada RM RFC repository that AdaCore has open, I can submit this there too, but I'm wondering if anything can be done about the manual in its current incarnation without needing to potentially publish and ratify an entirely new version.

Create night colorscheme matching versions of https://search.ada-lang.io/ and

Both search and usenet sites are light background with dark text. It'd be great if there was a way we could somewhat closely match the colorscheme of the main site with a dark theme with matching contrast. @JeremyGrosser

Make button "Download Alire" dependent on detected OS

Detect OS and immediately serve the correct version of Alire (https://github.com/alire-project/alire/releases)
Provide links for downloading for other OS's or different types (source, AppImage, etc.)

Main website: https://arg.adaic.org/home
Community input: https://arg.adaic.org/community-input

	<tr>
	<td> Pointer </td>
	<td> Access All </td>
	</tr>
	<tr>
	<td> Pointer </td>
	<td> Access All </td>
	</tr>

	<td></td>
	<td>
	<CodeBlock>pragma Restrictions(No_Dependencies => Other_Package)</CodeBlock>

ada-lang-io / ada-lang-io Goto Github PK

ada-lang-io's Introduction

ada-lang.io

Contribute

ada-lang-io's People

Contributors

Stargazers

Watchers

Forkers

ada-lang-io's Issues

Objectives

Recommend Projects

Recommend Topics

Recommend Org