Update Quickstart tutorial

[LKedward]

https://github.com/fortran-lang/webpage/issues/69

We can discuss what needs to be done here.

[Irvise]

I have a proposal that I want to explain here to get some feedback before making any pull request.

In the control flow section only if-else, do and do-while are discussed.

I propose to add a small footnote to indicate the existence of cycle, exit, where, forall? and do concurrent. Just like in derived types with the comment of pointer, codimension, etc. This will make the reader aware that fortran supports more than just the "common" flow instructions

PS: it is great idea to have a "modern" place to get into/discuss fortran. Tank you!

[certik]

@Irvise I think that's a great idea. Go ahead and submit a PR.

[LKedward]

Hi @Irvise, you're absolutely right; there should definitely be a mention and explanation of those control flow statements. The control flow page is a little sparse currently and I think there could probably be a bit more explanative text there (#99 is a good example of the writing style for these tutorials). The Quickstart tutorial is by no means a finished product so any more suggestions and contributions are certainly welcome!

[Irvise]

@certik @LKedward would you like it to be a very short note commenting their existence or would you prefer to have a small sentence explaining what each of them are supposed to do?

I personally think cycle and exit are "basic" control flow key words. Maybe they deserve their own section to be properly discussed?

And regarding the more "advance" features. Are there any plans to make an "Intermediate fortran" page? I have seen that you are discussing a Rust-style book, will it be a complete language introduction?

[LKedward]

I think we should actually explain what cycle and exit do since they are quite fundamental to loop operations; if you think they need their own section (on the same page) then I have no objection to that.

There could probably be another section on the Loops page about implied do loops and the where statement. I'm not sure about including the forall statement since this is now an obsolescent feature. Do concurrent could be be mentioned perhaps, but detail deferred to a future tutorial?

We've moved away from the idea of a single monolithic Rust-style book in favour of many smaller books on different topics - as part of this, I think an "Intermediate Fortran" book makes sense as a next step after the Quickstart guide. Do you have any thoughts on what could go in this? Perhaps we should open an issue to discuss that.

[Irvise]

Okay, I will start to write in a week or two (a bit too much work now).

Has the proposal to have something similar to Ada's learn page been discussed? I think it solves most of the points mentioned (plus it is interactive). However, I know this is not the issue to discuss this point. In order to keep the issue on point, could you point me to where the current discussion taking place?

[milancurcic]

Hi @Irvise, that would be a great addition.

@certik @LKedward would you like it to be a very short note commenting their existence or would you prefer to have a small sentence explaining what each of them are supposed to do?

We should have at least a complete small example showing how they work and a paragraph describing each feature. So, considerably more than a note or a sentence. While you're at it, if you can help expand the existing https://fortran-lang.org/learn/quickstart/operators_control_flow#loop-constructs-do section, that would be great.

I personally think cycle and exit are "basic" control flow key words. Maybe they deserve their own section to be properly discussed?

I think they should be in this section, and each should probably have its own subsection. Something like this (and separated from logical operators which don't belong with control flow):

# Control flow (chapter)
## if-branches (section)
...
## do-loops (section)
### regular do (subsection)
### do while() (subsection)
### do concurrent() (subsection)
### cycle, exit (subsection)

I agree that we shouldn't include forall for the reason that Laurence mentioned. We should include where, but not in control flow, as it's an array assignment construct. So it belongs in the Arrays chapter, which should be separated from strings.

[milancurcic]

We've moved away from the idea of a single monolithic Rust-style book in favour of many smaller books on different topics - as part of this, I think an "Intermediate Fortran" book makes sense as a next step after the Quickstart guide. Do you have any thoughts on what could go in this? Perhaps we should open an issue to discuss that.

@LKedward I think you refer to this. I apologize that I didn't provide feedback back in that thread. I didn't in part because I haven't gotten clear my self with the best way forward, and this in a difficult problem to solve.

I like the approach of mini-books over one large monolithic book. However, we're currently unclear what the specific mini-books are and what separates them. When you separate a subject matter into multiple parts (mini-books) you need to decide how to separate them. You can do it in different ways:

• By topic (compiling and linking, arrays, control flow, OOP, etc.)
• By reader skill level (intro, advanced, expert)
• By teaching method (tutorial, reference, cookbook, FAQ, best practices)

Different teaching methods serve different purposes, so I think we all agree we need separation by teaching method (e.g. we'll have best practices from fortran90.org etc.). There are kind of a neutral ground mini-books, because they will tend to touch on all of the topics, and be useful to programmers of all skill levels.

However, please, please be cautious of separating mini-books by both topic and skill level at the same time. By doing that you have to assume which topics are basic or advanced. And by assuming that you're assuming about what the reader needs. Which I don't think we can or should assume.

Another problem is overlap in content. Inevitably, both the intro and advanced mini-books will cover I/O, arrays, derived types etc. There will be a lot of repetition and cross-referencing. An average reader won't know ahead of time where the specific feature they're looking for is described.

I urge everybody here to discuss and decide whether to separate by topic or by skill level, but please don't do both. We'll end up with many messy and complicated books.

My preference is to separate by topic (e.g. mini-book on arrays, I/O, OOP, parallelism, interop etc.), and each successive section of a mini-book builds gradually in depth and skill level. Of course, some topics will depend on others, and we'll end up with a natural sequence of mini-books that form a nice, coherent, large book, just like the Rust book. Which is what we wanted in the first place. :)

[LKedward]

However, we're currently unclear what the specific mini-books are and what separates them.

We briefly discussed this (in the first tutorial PR I think) and I recall that we agreed to avoid separation by skill level, due to the issues you discuss, and primarily go for separation by topic + other formats (FAQ etc.). Based off this previous conversation, this is also my preferred method of separation.

@milancurcic, my mention of an "Intermediate Fortran" book may have caused confusion - by this I meant that it would be good to have a follow-on book from the Quickstart tutorial that covers more advanced topics that are not already contained within the Quickstart tutorial. i.e. they are split by topic where multiple topics are grouped within a book. This would be more of a "Further Fortran" book.

I realise that it may be preferable to have more topic granularity at the book level (one topic per book), however I also don't think we should have ~10 books each consisting of ~3 paragraphs to start off with.

this in a difficult problem to solve.

Absolutely, the idea behind the mini-books is to give us as much flexibility in structuring the content while also enabling us to publish content incrementally instead of in large tranches. My idea was that topics can start off as sections and be expanded to pages and then broken-out into stand-alone books, as more content is added.

[LKedward]

Okay, I will start to write in a week or two (a bit too much work now).

Thanks @Irvise ! Any help with the tutorials would be greatly appreciated!

Has the proposal to have something similar to Ada's learn page been discussed? I think it solves most of the points mentioned (plus it is interactive). However, I know this is not the issue to discuss this point. In order to keep the issue on point, could you point me to where the current discussion taking place?

We have a general discussion for the Learn section in fortran-lang/webpage#69 - I'll take a look at the Ada page.

I had considered including interactivity using compiler explorer: you can essentially store code snippets on it using the short urls; it can be configured to just show compilation and execution output without the assembly dump and it can be embedded via an iframe (see the 'share' menu).

[LKedward]

it would be good to have a follow-on book from the Quickstart tutorial that covers more advanced topics that are not already contained within the Quickstart tutorial. i.e. they are split by topic where multiple topics are grouped within a book. This would be more of a "Further Fortran" book.

Follow-up: I realise the idea of grouping topics into books still suffers from the underlying issue of making an assumption about the skill level of the topics and so isn't really a good idea. Best to keep to one topic per book.