Pascal Lexical Diagrams

classic Classic list List threaded Threaded
33 messages Options
12
Reply | Threaded
Open this post in threaded view
|

Pascal Lexical Diagrams

Anthony Walter-3
I've been working on writing Javascript to generate lexical language diagrams for the getlazarus.org learning center portal. 

With my script I'm able to render these diagrams which will be appear under the Free Pascal language Lexical topic:

http://cache.getlazarus.org/images/lexical-diagrams.png

Hopefully they are clear enough in their schematic design such they're understandable. I'll be adding code examples and brief summaries to each diagram which will likely be of aide.

Also, I am considering rendering hover over tooltips with popup lexical diagrams on pages similar to the Language overview page.


_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Pascal Lexical Diagrams

Jürgen Hestermann
Am 2016-01-30 um 10:45 schrieb Anthony Walter:
 > I've been working on writing Javascript to generate lexical language diagrams for the getlazarus.org learning center portal.
 > With my script I'm able to render these diagrams which will be appear under the Free Pascal language Lexical topic:
 > http://cache.getlazarus.org/images/lexical-diagrams.png
 > Hopefully they are clear enough in their schematic design such they're understandable. I'll be adding code examples and brief summaries to each diagram which will likely be of aide.

The look of the diagrams is very good.

Some things that I think can be improved:

1.) Direction of lines:
The lines should have arrows to denote the direction in which a diagram has to be followed. This would allow recursive definitions.
Example: http://i.stack.imgur.com/SOq3x.gif
It would also avoid the somewhat irritating use of words like [repeat] and [open symbol] which are only needed because of the missing arrows.

2.) \n
I think \n is not used in Pascal (it's more a C convention). Instead it should be named "line ending" or something like that. Also, especially new users may not know what \n means (unless they come from C).

3.) String literal:
Why does (char literal) appear twice? There can be any number of (char literals) so I think it would be clearer to have a simple recursive loop:

   />-'[any character other than "line ending"]'->-|
->->-------------(char literal)----------------->-|->-
   \----------------------<------------------------/

4.) Comment:
There should only be simply 3 kinds of comments:
    /->-(//)----[line ending]->-\
->--->-({)---------------(})->-|->-
    \->-((*)--------------(*))--/

5.) Identifier:
Same here, instead of the [repeat] word arrows should be used.


_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Pascal Lexical Diagrams

Anthony Walter-3
I'll consider arrow heads, though I'm unlikely to add them. My layout design is based on the JSON http://json.org/ style with which I believe plenty of people are familiar.

Here's an updated diagram with some of the changes you've noted including some new additions and thinner lines and fonts.




_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Pascal Lexical Diagrams

silvioprog
In reply to this post by Anthony Walter-3
On Sat, Jan 30, 2016 at 6:45 AM, Anthony Walter <[hidden email]> wrote:
I've been working on writing Javascript to generate lexical language diagrams for the getlazarus.org learning center portal. 

With my script I'm able to render these diagrams which will be appear under the Free Pascal language Lexical topic:

http://cache.getlazarus.org/images/lexical-diagrams.png

Nice.

Which tool do you use to make these charts? :-)

--
Silvio Clécio

_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Pascal Lexical Diagrams

Mattias Gaertner
In reply to this post by Anthony Walter-3
On Sat, 30 Jan 2016 04:45:27 -0500
Anthony Walter <[hidden email]> wrote:

> I've been working on writing Javascript to generate lexical language
> diagrams for the getlazarus.org learning center portal.
>
> With my script I'm able to render these diagrams which will be appear under
> the Free Pascal language Lexical topic:
>
> http://cache.getlazarus.org/images/lexical-diagrams.png

A finalization section can exist without initialization.

Mattias
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Pascal Lexical Diagrams

Ewald-2
In reply to this post by Anthony Walter-3
On 01/30/2016 10:45 AM, Anthony Walter wrote:
I've been working on writing Javascript to generate lexical language diagrams for the getlazarus.org learning center portal. 

With my script I'm able to render these diagrams which will be appear under the Free Pascal language Lexical topic:

http://cache.getlazarus.org/images/lexical-diagrams.png

What's wrong with those found in the documentation? (for example: http://www.freepascal.org/docs-html/ref/refse105.html ) IMO those provide more clarity.

-- 
Ewald

_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Pascal Lexical Diagrams

Anthony Walter-3
Mattias, 

Noted. Thank you.

Ewald, 

There was/is a big discussion on the forums about the terrible state of the documentation. I already am hosting easy to setup bundles (for example my OSX bundle installed CodeTools and offers you the choice between Homebrew and Macports) which include Free Pascal terminal shortcuts (perfect for following along with the language guide examples). I also host a much improved documentation portal, a few instructional videos (more to come in the tutorials section), and in my opinion aesthetically pleasing page layouts with breadcrumb navigation (perfect for navigating nested topics). 

With this in mind, given my penchant for design, I believe hosting new hyperlinked language and IDE guides is a natural progression. When I add in brief summaries to go along with each diagram as well as syntax highlighted examples I think there will be even more clarity. And I neglected to mentioned that diagram lexical sub paths can hyperlink link to other diagrams or page anchors. That is, on the actual pages users receive visual feedback for certain diagram elements (hover over effects) to indicate they hyperlink to other diagrams.

I summary, what I am producing will be an improvement, again in my opinion, over other disparate resources.

_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Pascal Lexical Diagrams

Ewald-2
On 01/30/2016 07:21 PM, Anthony Walter wrote:
>
> There was/is a big discussion on the forums about the terrible state
> of the documentation.

Two things:
    - I don't think the state of the documentation is terrible. It has
in fact improved vastly over the years.
    - By creating a secondary set of documentation the "terrible" state
won't improve, now will it?

--
Ewald


_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Pascal Lexical Diagrams

Anthony Walter-3
Ewald,

If you read the threads on the Lazarus forums you'll see the points people are making while complaining about the documentation, tutorials, and application developer guides, including complaints from some of the top contributors. In a nutshell it has been said that the wikimedia engine is bad for these things. One complaint is that due to it's everyone can edit/create pages there is a general lack of cohesion. Many people have vastly different writing skills, topics are not ell organized, contributors and moderators spend time fighting vandalism or bickering rather than on creating quality content, there are not enough people in out community interested in taking on their work of maintain a decent wiki. Many examples were given, and I personally prefer a nested structure with folders which the wikimedia engine does not provide. 

If you are okay with the state of everything then move along.

However if you feel like addressing the issues people are raising, then I believe the points brought up in my last post bring forth one possible balanced solution. And yes, if treated comprehensively the terrible state will be improved.

_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Pascal Lexical Diagrams

Michael Van Canneyt
In reply to this post by Ewald-2


On Sat, 30 Jan 2016, Ewald wrote:

> On 01/30/2016 07:21 PM, Anthony Walter wrote:
>>
>> There was/is a big discussion on the forums about the terrible state
>> of the documentation.
>
> Two things:
>    - I don't think the state of the documentation is terrible. It has
> in fact improved vastly over the years.
>    - By creating a secondary set of documentation the "terrible" state
> won't improve, now will it?

Contributions to the documentation have been scarce.
It is basically a 1-man job for the last 20(!) years.

Writing coherent and comprehensive documentation is a huge effort.

Making it look nice is simply beside the point.
So the proposal of Walter (with all due respect for the efforts made)
is just a waste of Walter's time. It is again a scattering of information.

Although well-meant, the current effort is not factually helping.
The effort would be better spent giving feedback on the current
documentation, so it can be improved where it is lacking. I have never
refused critique or ignored remarks.

I realize it may come over as not very nice on my part, or even vindictive,
seeing that I am the author, but after more than 20 years I have become
very sceptical.

Michael.
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Pascal Lexical Diagrams

Michael Van Canneyt
In reply to this post by Anthony Walter-3


On Sat, 30 Jan 2016, Anthony Walter wrote:

> Mattias,
>
> Noted. Thank you.
>
> Ewald,
>
> There was/is a big discussion on the forums about the terrible state of the
> documentation.

Instead of discussing, the time would be better spent on reporting issues
about the documentation. I always respond very quickly to documentation
issues.

Michael.
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Pascal Lexical Diagrams

Michael Van Canneyt
In reply to this post by Anthony Walter-3


On Sat, 30 Jan 2016, Anthony Walter wrote:

> Ewald,
>
> If you read the threads on the Lazarus forums you'll see the points people
> are making while complaining about the documentation, tutorials, and
> application developer guides, including complaints from some of the top
> contributors. In a nutshell it has been said that the wikimedia engine is
> bad for these things.

Wikimedia is NOT documentation. It is a knowledgebase.

Michael.
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Pascal Lexical Diagrams

Ewald-2
In reply to this post by Anthony Walter-3
On 01/30/2016 08:09 PM, Anthony Walter wrote:
> Ewald,
>
> If you read the threads on the Lazarus forums
I'm not subscribed to that forum as I do not use lazarus. I use
freepascal without an IDE. So by all means: enlighten me :-)


> you'll see the points people are making while complaining about the
> documentation, tutorials, and application developer guides, including
> complaints from some of the top contributors. In a nutshell it has
> been said that the wikimedia engine is bad for these things. One
> complaint is that due to it's everyone can edit/create pages there is
> a general lack of cohesion. Many people have vastly different writing
> skills, topics are not ell organized, contributors and moderators
> spend time fighting vandalism or bickering rather than on creating
> quality content, there are not enough people in out community
> interested in taking on their work of maintain a decent wiki. Many
> examples were given, and I personally prefer a nested structure with
> folders which the wikimedia engine does not provide.
You are talking about the wiki here. I was talking about the programmers
guide and language reference. The names may be off, but if you would
have clicked that link I sent in my previous message, you would have
noticed that that page is no wiki at all.



>
> If you are okay with the state of everything then move along.
Read the pages. What is wrong with them? If something is wrong, then
file a bug!

Now, since something terrible has gone wrong in pointing you to the two
documents I am talking about, I'll walk through the procedure with thee:
    - Go to www.freepascal.org
    - Click documentation (6th entry under general)
    - Select one of the docuemts, humour me and pick the language reference.
    - You are now here:
http://www.freepascal.org/docs-html/current/ref/ref.html

Now tell me (or file a report), what is so "terrible" about this?


--
Ewald


_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Pascal Lexical Diagrams

Anthony Walter-3
In reply to this post by Michael Van Canneyt
Michael,

My portal is titled 'Learning Center'.

Regarding the label Documenation, I am following along with this topic:

Documentation / tutorials need improvement (was: Object Pascal decline?)

Where most people are referencing the wiki, as that's the place where they feel tutorials and guides should be, but in the ends it seems quite disparate. This entry was given as an example in the prior topic:


_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Pascal Lexical Diagrams

Anthony Walter-3
In reply to this post by Ewald-2
Ewald,

Maybe you should go to the forums and enlighten everyone. I provided the link in my last reply.

_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Pascal Lexical Diagrams

Ewald-2
On 01/30/2016 08:22 PM, Anthony Walter wrote:
> Ewald,
>
> Maybe you should go to the forums and enlighten everyone. I provided
> the link in my last reply.

You missed the point. It is not my intention to shove my opinion down
anyone's throat.

I do however think that reinventing documentation (with all the bugs
related to new projects) is a waste of time. Especially if the only
thing that changes is the form factor. It is the content that matters.
That content already exists, but needs some work here and there. So I am
trying to convince you to collaborate to the existing documentation
instead of writing your own. Because your own documentation will also be
a one-man project, will also have its flaws and then in about five years
a similar thread on some forum I'll probably not be subscribed to will
state that the getlazarus documentation is in a terrible state. And
voila, same discussion all over again.

All that effort down the drain. And what for?

--
Ewald


_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Pascal Lexical Diagrams

Michael Van Canneyt


On Sat, 30 Jan 2016, Ewald wrote:

> On 01/30/2016 08:22 PM, Anthony Walter wrote:
>> Ewald,
>>
>> Maybe you should go to the forums and enlighten everyone. I provided
>> the link in my last reply.
>
> You missed the point. It is not my intention to shove my opinion down
> anyone's throat.
>
> I do however think that reinventing documentation (with all the bugs
> related to new projects) is a waste of time. Especially if the only
> thing that changes is the form factor. It is the content that matters.
> That content already exists, but needs some work here and there. So I am
> trying to convince you to collaborate to the existing documentation
> instead of writing your own. Because your own documentation will also be
> a one-man project, will also have its flaws and then in about five years
> a similar thread on some forum I'll probably not be subscribed to will
> state that the getlazarus documentation is in a terrible state. And
> voila, same discussion all over again.
>
> All that effort down the drain. And what for?

I can only concur with what Ewald writes.

Michael.
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Pascal Lexical Diagrams

silvioprog
In reply to this post by Anthony Walter-3
On Sat, Anthony Walter <sysrpl@...com> wrote:
[...]
> With my script I'm able to render these diagrams which will be appear
> under the Free Pascal language Lexical topic:
>
> http://cache.getlazarus.org/images/lexical-diagrams.png
>
>> On Sat, silvioprog <silvioprog@...com> wrote:
>> Which tool do you use to make these charts? :-)
[...]

Found.

Sorry for ask! ^^'

--
Silvio Clécio

_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Pascal Lexical Diagrams

Michael Van Canneyt


On Sat, 30 Jan 2016, silvioprog wrote:

> On Sat, Anthony Walter <sysrpl@...com> wrote:
> [...]
>> With my script I'm able to render these diagrams which will be appear
>> under the Free Pascal language Lexical topic:
>>
>> http://cache.getlazarus.org/images/lexical-diagrams.png
>>
>>> On Sat, silvioprog <silvioprog@...com> wrote:
>>> Which tool do you use to make these charts? :-)
> [...]
>
> Found <https://github.com/tabatkins/railroad-diagrams>.
>
> Sorry for ask! ^^'

Nice. Added to my bookmarks :-)
I may actually use this to redo the official ones as PNG images.

Michael.
_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal
Reply | Threaded
Open this post in threaded view
|

Re: Pascal Lexical Diagrams

silvioprog
On Sat, Jan 30, 2016 at 5:23 PM, Michael Van Canneyt <[hidden email]> wrote:
On Sat, 30 Jan 2016, silvioprog wrote:
On Sat, Anthony Walter <sysrpl@...com> wrote:
[...]
With my script I'm able to render these diagrams which will be appear
under the Free Pascal language Lexical topic:

http://cache.getlazarus.org/images/lexical-diagrams.png

On Sat, silvioprog <silvioprog@...com> wrote:
Which tool do you use to make these charts? :-)
[...]

Found <https://github.com/tabatkins/railroad-diagrams>.

Sorry for ask! ^^'

Nice. Added to my bookmarks :-)
I may actually use this to redo the official ones as PNG images.

Me too. :-)

I didn't know that this tool existed. I'll use this one to generate a graph of my basic properties lexer.

Thanks Anthony for share that picture. :-)

--
Silvio Clécio

_______________________________________________
fpc-pascal maillist  -  [hidden email]
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal
12