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.