Compiling markdown

One feature lacking from Fortran is blocks of free-format comments. I have personally addressed this over time by using makefiles with rules to compile HTML files by extracting only lines in an <XMP> (which is now deprecated) section of the file, and by using preprocessors (like GitHub - urbanjost/prep: Fortran pre-processor) that add the feature in an even more general way; but I am wondering if Fortran added such a feature or if an extension was made to prep(1) what people would think of adapting the markdown file format with the ```fortran extension for fortran? That is, you could keep Fortran source in a *.md file and prep(1) or fpm(1) would ignore lines not between ```\fortran and a matching ```. The same file, as a result, could also include associated C or other materials and be easily documented, posted as-is in Fortran Discourse, … just a thought, mostly just wondering how many others find something like that or the less disruptive idea of fortran ignoring a ... region actually be proposed as standard Fortran worth discussing.


It’s an interesting idea. I’d want to see some more concrete examples before forming an opinion one way or the other. I suspect this would be a non-starter for the committee to entertain though.

1 Like

I like the idea and can see lots of potential use. Even more so if you make it able to compile to HTML or similar, like R Markdown. It’s a great way to add thorough, rich documentation to your code.

So a very preliminary example is

So if that file is run through “prep -type md …” it extracts the Fortran code obeying its pre-processing directives if present, and then if it was setup in an fpm package with M_graph as a dependency you can build and run it and generate the image; and using something like pandoc(1) create an HTML or PDF version (I made one in the same directory) . All from one flat text file you could edit on any system; albeit you need the infrastructure to display it properly (which github obviously has, if you click on the sample file you see the image and text and syntax-highlighted Fortran) so it works quite well with github even if you have no infrastructure on your own platform; and the CD/CI interface could be used to generate the plot and Adobe PDF file. It would obviously take more work but if fpm(1) allowed you to specify a rule for pre-processing that let you select your preprocessor, perhaps by file suffix it would be pretty well transparent. I wrote the text so it works with pandoc for making a man-page, which I did not automate but it could be done. Not the prettiest example, but I think it makes a reasonable use case.

1 Like

Never heard of Rmarkdown before. Interesting ideas for how it could work.

RMarkdown can integrate R, Python, Julia, and C++ codes and outputs within an HTML or PDF file.

Nothing stopping using markdown for that, just multiple types to write out at ```TYPE lines. Biggest difference in what I am doing with Fortran would be to allow a single pass to write out multiple files; otherwise you would have to do a call for each file type. Have just browsed the RMarkdown pages so far, but looks like it is worth looking more at; of course there are other things going on that should allow Fortran to be used in notebooks too. Just do not want to get tied up too much in requiring a lot of infrastructure.

1 Like

Where can one get ‘prep’ utility? It is a rather ungoogleable name :wink:

slightly OT - strange coloring for Fortran code, use left black, colored strings inside comments (arguably a bad idea), including to, in - are these two Fortran keywords (to as an orphaned go to`, maybe)?

The color-coding of a few words is odd, but that is the markdown filter on github generating that view; there are a variety of markdown viewers (as well as a good number of markdown variants too).

I used the pandoc(1) utility to generate the Adobe PDF in the same directory. It has four or five (at least) alternative ways to render the markdown, including to HTML5, latex, man-pages, … put I primarily picked it because it is on the machine I created the demo on. Note it does a different highlighting; and that many other alternatives are available.

Regarding gettting prep(1) – the link to the demo page is on the prep page! If you do not use fpm(1) or make(1) there is a standalone/ directory that has a single-file Fortran file that should build with most any non-legacy compiler.

prep(1) is not required to try the concept if you have sed(1) or other tools availble to extract text ranges; even csplit(1) could be used. A simple filter could be used in a makefile to get the same effect, but by placing it in prep(1) that also gives you a basic pre-processor. There were separate discussions on prep(1) previously concerning its primary function as a portable Fortran preprocessor. Hopefully the github repository and the help text for the program explains the use of prep(1) well enough to try it.

I like the effect of using the markdown files for code as well as documentation myself, and already modified my own “generic compiler” script ccall(1) to compile files with a .md suffix and am getting rather fond of the method. It is simple flat text (the whole idea behind markdown existing, basically) that works as-is in Fortran Discourse, github, andother places; much easier to edit than Fortran comments and looks much nicer when rendered, allows for links to other documents and keeps everything (well, for the most part) in a single file.

Either extending the markdown processing a bit or using the prep directives also allows for including test data and system commands in the file as well. Works just as well for other languages as for Fortran, even allows keeping Fortran and related C interfaces and code in the same file, etc. At least personally, I find the idea appealing.

Since the format is just simple flat text even if markdown went the way of ASA carriage control it would still be quite readable; and I think doxygen and/or ford might work well with it in the reverse mode there instead of it being a markdown file with Fortran embedded in it it is a Fortran file with regions of markdown comments in it.

1 Like

PS; Good point about using English-like names for things you want to browse for. At least I did not call it S or R. I think that name (“S”) did a lot to hurt that in the age of search engines; and I usually have to throw in a few extra keywords when looking for R resources so I do get the point.

At least for fpm-compatible github resources @Beliavsky recommends adding the topic “fortran-package-manager”; we still need a few others for generic Fortran materials


I did not add the option to the prep documentation; as it is still just a concept and might be changed to act on file suffixes or use some other method, but as a first cut
you use prep with the “-type md” option to have it extract just the Fortran code.

This must be a joke, isn’t it?


No, you were there if you looked at the example. I just added a few lines to prep to conditionally extract lines between ```fortran and ``` to try out the approach. The
example page is just a file in the demos directory for prep(1). Did not intend the link to be so extravagant, put to look more like the above. The default for a URL now seems to insert a minipage automatically.