Documentation style

[nicolaslesquoy]

The current API for the Oberon programming language is hard to read, especially if there are optional arguments.

For instance, the MODULE rule:

module = MODULE ident ";" [ImportList] DeclarationSequence [BEGIN StatementSequence] END ident "."

The use of brackets and curly braces for optional arguments and to denote an arbitrary number of args make the reading difficult.

The documentation style used in this project is based on the Oberon-07 report written by Niklaus Wirth.

I would personally advocate for the use of a numpy-style documentation. For instance the numpy.ndarray constructor is documented as follow:

class numpy.ndarray(shape, dtype=float, buffer=None, offset=0, strides=None, order=None)

An array object represents a multidimensional, homogeneous array of fixed-size items. An associated data-type object describes the format of each element in the array (its byte-order, how many bytes it occupies in memory, whether it is an integer, a floating point number, or something else, etc.)

[...]

For more information, refer to the numpy module and examine the methods and attributes of an array.

Parameters

(for the __new__ method; see Notes below)
shapetuple of ints

    Shape of created array.
dtypedata-type, optional

    Any object that can be interpreted as a numpy data type.
bufferobject exposing buffer interface, optional

    Used to fill the array with data.
offsetint, optional

    Offset of array data in buffer.
stridestuple of ints, optional

    Strides of data in memory.
order{‘C’, ‘F’}, optional

    Row-major (C-style) or column-major (Fortran-style) order.

Also the various elements in the documentation lacks links between them and examples.

[amtoine]

The current API for the Oberon programming language is hard to read, especially if there are optional arguments.

oberonproject.github.io/syntax is not an API, it is the syntax itself, a 1 to 1 translation of the eBNF introduced in the Oberon-07 report, extended with the built-in procedures :+1: the purpose of these pages is to make the understanding and the exploration of the syntax easier :yum:

For instance, the MODULE rule:

module = MODULE ident ";" [ImportList] DeclarationSequence [BEGIN StatementSequence] END ident "."

The use of brackets and curly braces for optional arguments and to denote an arbitrary number of args make the reading difficult.

definitely something to be worked on :+1:

The documentation style used in this project is based on the Oberon-07 report written by Niklaus Wirth.

I would personally advocate for the use of a numpy-style documentation. For instance the numpy.ndarray constructor is documented as follow:

class numpy.ndarray(shape, dtype=float, buffer=None, offset=0, strides=None, order=None)

...

could you try to show how you imagine the MODULE rule above written in this new format? :yum: in the end, i think it would be great to stick to the eBNF :thinking: again, oberonproject.github.io/syntax is not an API about some library written in the language, but is designed as an interactive, static-HTML-based equivalent to the eBNF introduced by Wirth et al. in the Oberon-07 report

however, making the pages easier to read and understand is definitely something to be addressed! :+1:

Also the various elements in the documentation lacks links between them and examples.

yup :wink: i've written some ideas in that direction in pages/examples and pages/examples-foo this is regarding examples, but what do you mean by "documentation lacks links between them"?

[nicolaslesquoy]

For a concrete example of the transition to numpy-style documentation, I am not proficient enough in Oberon to write it.

It would be better to write a proper API since the language itself is not very well known. It lacks a full explanation of the syntax.

Also the various elements in the documentation lacks links between them and examples.

The current website does not provide an overview of the syntax, and the meaning of rules, control structures.

[amtoine]

For a concrete example of the transition to numpy-style documentation, I am not proficient enough in Oberon to write it.

in the end, this is not an API, so i do not know if using a numpy-like documentation makes sense here :thinking: i can not know what you have in mind... however, we could imagine how to make the pages themselves easier to read!!

some ideas about the pages

right now the page of the module production rule looks like:

                                                                           back to syntax homepage

module:
module = MODULE ident ";"  [ImportList] DeclarationSequence [BEGIN  StatementSequence] END ident "."

                                                    Places in the syntax where you might come from:

with the appropriate colors and links, of course :+1:

if we set aside the fact that examples have been partially implemented in pages/examples and pages/examples-foo, the question is: how can we make the information easier to read for the user, assuming they know the basis of the eBNF syntax?

at some point i imagined breaking the line of the production line as follows:

                                                                           back to syntax homepage

module:
module =
    MODULE ident ";" 
        [ImportList]
        DeclarationSequence
    [
    BEGIN
        StatementSequence
    ]
    END ident "."

                                                    Places in the syntax where you might come from:

in order to show a bit more the structure of the a module :thinking:

introducing eBNF

It would be better to write a proper API since the language itself is not very well known. It lacks a full explanation of the syntax.

Also the various elements in the documentation lacks links between them and examples.

The current website does not provide an overview of the syntax, and the meaning of rules, control structures.

again this is NOT an API for some library, this is exactly the syntax of the oberon language :yum:

however, adding a reminder about what the eBNF format is and how to read it and the pages is a great idea, for sure :+1: 'cause, knowing what a rule and control structures are is a requirement to read the syntax of a language... making it clearer is a good idea :ok_hand:

proposition

what do you think about the following two points?

• making the pages clearer but keeping the eBNF format
• adding information about the eBNF format itself, documentation links, etc, ..., explicitely on the syntax page for instance

[Oric4ever]

Nicolas, I think you refer to the fact that the syntax of Python is so big that usually people give up writing the syntax and instead prefer to show examples... But the grammar actually exists in Python documentation, it's chapter 10 here: https://docs.python.org/3/reference/grammar.html

So I agree it's not readable, the fact is that Oberon's syntax is simpler and allows to give the syntax in BNF as a non-ambiguous reference.

But you are right: if we want to promote Oberon as a simple language, we shouldn't force the learners to first understand what is a grammar and what is this other language (Backus Naur Form) that you have to learn before being able to read the specification of Oberon... So that's a good point: in order to spread the word of a simple language, we need to write the specification in a simpler way, the BNF specification is for language specialists...

[amtoine]

then it's a whole new issue here i feel :thinking: and it's a really good one !

it's not that the current pages are not well constructed, even though they could be improved with some of the comments above: it's that the friendly documentation, tutorials and introduction are simply missing from https://oberonproject.github.io/ :yum:

then, i'll say we should keep the syntax pages as the BNF specification is for language specialists, maybe improve it of course, and add other pages with tutorials and examples, and finally refactor the main page to make all of this as clear as possible :+1: