Transfer fortran90.org content

[LKedward]

See #69

[certik]

Yes, we should transfer it and then put a banner at fortran90.org to come here.

[vmagnin]

Following that discussion https://fortran-lang.discourse.group/t/fortran-lang-is-now-second-in-google/931/14 , I can help working on translating the ReStructuredText format to Markdown, using Pandoc.

[certik]

@vmagnin thank you! That would be super helpful.

[jvdp1]

I would be happy to help too! I guess that the file conversion is the easiest step ;) A nice integration in fortran-lang (by considering the current content of fortran-lang to avoid overlap) would require more work.

[certik]

Go ahead, take one page and submit a PR against this repository. Then let's figure out how to best integrate.

[vmagnin]

@jvdp1

I would be happy to help too! I guess that the file conversion is the easiest step ;) A nice integration in fortran-lang (by considering the current content of fortran-lang to avoid overlap) would require more work.

Yes, a quick try today showed me that Pandoc was doing a very good job, except some characters like quotes, and some links. So the translation with Pandoc will be very fast, the longest work will be to verify that every thing is OK. Perhaps a simple copy/paste of the texts of both versions, and a diff on the two resulting files could accelerate that validation.

Then will begin the integration to the website.

I propose beginning working myself on the Pandoc and validation step. In the meantime, @jvdp1 you can have a look at the text of fortran90.org and the content of Fortran-lang.org to identify potential problems.

[vmagnin]

@certik

Go ahead, take one page and submit a PR against this repository. Then let's figure out how to best integrate.

I guess I should put the Markdown files into a directory in https://fortran-lang.org/learn/
Perhaps https://fortran-lang.org/learn/tutorials/ ? Or any other name you think more adequate.

Then probably we will need Sebastian @awvwgk to integrate those .md files into the code of the site.

[awvwgk]

The documentation regarding the learn subsection is located here.

[vmagnin]

@awvwgk

The documentation regarding the learn subsection is located here.

Wow! I will look at it.
I will work in my fork from awvwgk/fortran-lang.org
Should I create a new branch?

[awvwgk]

Right, you forked from my fork, just branch from my default branch, it is kept in sync with the @fortran-lang default branch automatically. You can direct your PR against the @fortran-lang version of the homepage, but if you make a PR against my fork by accident, I'll watch out and advice how to get to the real upstream.

[vmagnin]

I report my progress translating fortran90.org files. The following command gives good results:

$ pandoc --standalone --toc --resource-path=../images --to markdown_strict --shift-heading-level-by=1 best-practices.rst -o best-practices.md

I have added the --to markdown_strict to fix some problems: some characters were escaped like \" or \', and there was problems with rst labels. At first glance, it looks now fine, except for the escaped \$ in the OpenMP directives (only three occurrences).

In the rosetta.rst page, there is a mandelbrot.png image. Curiously, despite the --resource-path=../images option, I had to modify the path ![image](/images/mandelbrot.png) to ![image](../images/mandelbrot.png).

The --shift-heading-level-by=1 is for starting headings at <h2>, like specified in the style guide.

Now my objective is to first work on a PR for best-practices.md. There is two possibilities:

• a single-page mini-book: although that page is quite long, we could put it quickly online and later, as the text is revised, slice it into a multi-page mini-book.
• working directly on a multi-page mini-book.

Remarks concerning code indentation:
it is generally 4 spaces. As far as I understand, the discussions #60 and https://fortran-lang.discourse.group/t/should-tutorials-on-fortran-lang-org-follow-a-consistent-style-for-code-listings/134/18 seem OK with that although other tutorials seem to be rather 2 spaces. But we can also notice that there is generally no indentation for the code inside functions and subroutines, which could be discussed if the content is later revised.

Useful links:

• https://fortran-lang.org/learn/
• https://www.fortran90.org/
• https://github.com/certik/fortran90.org/
• https://pandoc.org/MANUAL.html
• https://www.markdownguide.org/tools/jekyll/

[jvdp1]

Thank you @vmagnin for this wok. I would be in favor of working directly on a multi-page mini-book. IMO it will be easier to review and identify possible overlaps with existing contents.

[certik]

Thank you @vmagnin for this work!

Yes, we can do multi page mini book and review page by page. Yes, let's start with the best practices. (The rosetta has an issue that it has side by side code comparisons which we have to figure out how to do in Markdown. We don't need to include the Mandelbrot image, I only included it to show that both Python and Fortran generate exactly the same image.)

I think there is in general no agreement on the number of spaces. I suggest to keep the formatting as is, and see how it looks when rendered and if there are objections.

[vmagnin]

Yes, we can do multi page mini book and review page by page. Yes, let's start with the best practices. (The rosetta has an issue that it has side by side code comparisons

So let's go with multi-page! I will slice best-practices.md in as many files as needed, following the MINIBOOKS guide. And when ready, I will post here the directory tree to be sure we agree with the directory and filenames before I commit them in my fork and create a PR.

Concerning rosetta.md, Pandoc has converted the tables containing the Fortran and Python codes in HTML tables. It looks quite good in a Markdown visualizer, although when the two codes have very different lengths, the shorter one is vertically aligned centered, contrarily to the original in fortran90.org. I imagine it can be fixed by modifying the HTML parameters.

Note that for the moment, I have not yet included those files in my Fortran-lang.org fork, so I don't know yet how they will look in a browser.

[vmagnin]

For rosetta.md there is also an extension grid_tables to avoid HTML:

$ pandoc --standalone --toc --resource-path=../images/ --to markdown_strict+grid_tables --shift-heading-level-by=1 rosetta.rst -o rosetta.md

The tables look good in a text editor, but my Markdown viewers don't manage them. But I will test it in the website fork.

[vmagnin]

Beginning visualizing the result with Jekyll, I have updated my Pandoc command:

$ pandoc --standalone --toc --resource-path=../images --to markdown_strict+pipe_tables+backtick_code_blocks best-practices.rst -o best-practices.md

• The pipe_tables extension yields tables in markdown format instead of HTML.
• The backtick_code_blocks extension is for having code in blocks ```fortran... ``` which allows syntactic coloration. By default the code was in blocks indented with 4 spaces.
• I have removed --shift-heading-level-by=1 because the <h1> title of each file will be transferred into the header of the md file. And so others will already begin at level 2.

[vmagnin]

I will continue tomorrow, but it looks quite good:

[certik]

Nice, thank you @vmagnin! I can help proof read once you are ready.

[vmagnin]

I have committed the new mini-book to my fork in a new fortran90org branch:
https://github.com/vmagnin/fortran-lang.org/tree/fortran90org

$ tree best_practices
best_practices
├── allocatable_arrays.md
├── arrays.md
├── callbacks.md
├── c_interfacing.md
├── element_operations.md
├── file_io.md
├── floating_point.md
├── index.md
├── integer_division.md
├── modules_programs.md
├── multidim_arrays.md
├── parallel_programming.md
├── python_interfacing.md
├── style_guide.md
└── type_casting.md

0 directories, 15 files

Let me know if you agree with those directory and filenames. I am waiting for your signal to make a PR.

Some remarks:

• I have not changed anything in the content except a word in the introduction ("This page" => "This mini-book"), and I have added the authors (https://www.fortran90.org/src/contributors.html) in the header of the index.md file.
• The markdown looks good, but perhaps the markdown tables look could be improved.
• In the learn/ directory, there is still a file best_practices.md (Draft structure for fortran tutorials) created by @LKedward one year ago.

[LKedward]

Great stuff! (Feel free to delete the vestigial best_practices.md in your pull request.)

[vmagnin]

Thanks @LKedward, I have committed a git rm best_practices.md in my fork.

Concerning the Python Fortran Rosetta Stone page, it's more difficult with the Python / Fortran code comparisons in two columns. I have found no Pandoc extension to obtain a correct Markdown table. Pandoc can generate HTML tables, but we lose the syntax highlighting. No idea for the moment...

The vertical alignment problem can be fixed by adding an attribute: <td style="vertical-align:top">:

[certik]

I'll review later today, thank you so much @vmagnin!

Regarding the rosetta, one option is to use Myst: https://myst-nb.readthedocs.io/en/latest/use/markdown.html, it is markdown and it can do anything that ReST could do. I believe it can do side by side tables.

[jvdp1]

Let me know if you agree with those directory and filenames. I am waiting for your signal to make a PR.

Sounds good to me. I guess a PR could be opened for review. Should we already introduce cross-references with the current content of fortran-lang.org (especially from the Quickstart tutorial in whcih tips are mentioned to this mi-book) (during the review)?

[vmagnin]

Concerning the FAQ and Gotchas pages of fortran90.org, the Pandoc command used for Fortran Best Practices also makes a perfect job.