The Fortran Wiki and several on-line compiler documents and the standard provide descriptions of the Fortran intrinsics but none that I know of provide them as manpages;
which I strongly prefer for ease of access and integration into the programming environment on *nix systems. And I personally find the example programs in particular to be overly lacking in details (if they exist at all). So I just started a github site to create a set of manpages for the intrinsics.
I set it up to only require flat text files as input using the txt2man(1) markdown language
so anyone that would like to help does not need to learn *roff.
I threw in some bells and whistles so (assuming you are on a GNU/Linux, Unix, or CygWin environment) it automatically generates HTML versions from the manpages using groff(1) and an HTML index.
But if anyone thinks this is useful and wants to help it seems like using the txt2man(1) utility makes it easy for anyone to contribute (if I figure out how to allow contributes – still reading github documents :>).
I think I at least started one for each intrinsic. See
for release 0.0. If you have an urge to rewrite any of them please do so! Good code examples are needed in particular. If the bells and whistles do not work on your platform just change the text files in the doc/ directory and I’ll periodically build the *roff and html output files.
Once they seem complete and stable, maybe the *roff files could be distributed in other venues such as the Fortran stdlib project?
Seems like a simple and short community-driven project?
Great work @urbanjost! I too find man pages much more convenient since I don’t have to leave the terminal.
I think once stable, it would be good to host the HTML output under the fortran-lang top-level domain, like man.fortran-lang.org, and have a download link for an easy installer script for the man pages.
The advantage here is we would have a compiler-independent intrinsics reference which we can link to from the tutorials.
I would be interested in contributing to this project!
@urbanjost great idea! I think we should have that both as nice html documentation online, as well as man pages for easy access from a command line.
My only suggestion would be to change the license from GFDL to MIT or BSD, so that people can copy & paste the examples from the man pages into their projects and so that we can more tightly integrate the text with our other documentation if desired in the future.
Great feedback. That’s really encouraging. After looking everthing over I think an MIT license is appropriate even though I heavily based the initial drafts of several pages on the reference materials found listed in the github repository. There are a lot of things that need worked on from the underlying build environment on up; but producing quality contents for the manpages themselves is the primary goal, of course. Your feedback and any collaboration anyone can provide are truly valued.
If you relicense to MIT, why don’t we develop this as a fortran-lang community project? We need high quality documentation for Fortran. This is part of what we need.
Btw, down the road, I would like to ship such documentation with LFortran also, so that when people are offline with the compiler they can easily access documentation. Perhaps hook it somehow to VSCode, so that you can quickly lookup high quality documentation with examples for any intrinsic function. I can imagine other compilers such as gfortran or Flang to ship such documentation also. This can all be done later, but it starts with having the documentation itself maintained by the community.
@urbanjost if you’d be interested in leading such an effort, this would be invaluable to the whole Fortran community, and this will become extremely useful in the future as we develop it more.
That sounds enticing; but I wanted to take this as far as I could first using tools I am familar with, and where everyone interested is free to experiment with how this can be done with a Keep-it-simple method; and initially it was easier (for me anyway) to try it as a github site (which I am learning as I go). So it might be a bit self-serving but I am not quite in a position to tear this down and start over yet. If there is interest and feedback and contributions from others I will try to spearhead something grander; otherwise if it is just me I prefer to “do it myway”. If someone knows what to do with a tarball of manpages on their own I think it has gotten quite a ways already.
Has anyone actually looked at or used any pages yet? Comments welcome; the earlier the better (before I get to set in my ways!)
Keep the comments coming. I just do not want to get ahead of myself when I specifically was trying to contribute something small-scale with quick results; and this could easily creep into something very large-scale. So I think the suggestions sound good, but I’ll consider that “phase II” for now.
Got over 100 downloads but not a single comment, good or bad. If anyone has ideas on how this can become a collaborative part of fortran-lang I am not sure what the process would be – how to find out what the process would even be to turn it over, etc. I plan on continuing to rewrite these and add other parts of Fortran like statements that fit the manpage format (CONTINUE, STOP, EXIT, …) but time is short for the foreseeable future so if this is appropriate as a seed for the fortran-lang site I am all for it. Not getting the participation I hoped for so it may be better off as part of fortran-lang? I personally use the manpages all the time but I use vim; and it is very easy to customize the K command or even use it as-is to bring up the documents from that editor. The default just brings up the manpage; but it is relatively easy to make it bring up the file in split screen with context highlighting, which makes it a lot easier to cut and paste sections from.
Curious if anyone that downloaded it found it useful but no feedback.
It is very hard to build a community. Given the positive feedback you got on this thread, if you are willing to make this part of fortran-lang, I think it can increase the chances of more people participating. I provided suggestions above how to do that (relicence to MIT and make the repository part of github.com/fortran-lang), however, it does require some commitment from you to maintain it, at least in the near future. The other alternative is that you maintain it yourself separately, and try to build a community around it. Do you want to have a quick phone call about it? We can brainstorm the various ways how to move forward.
@urbanjost Sorry I didn’t get to install the manpages yet, although I browsed the repository as well as the html version.
This seems quite mature to me. The webpages are functional, I assume the local manpages are as well, and the content seems mostly complete on first look. Granted, I only browsed a dozen or so intrinsics. If anything needs work, it’d be polishing the content and styling such as syntax highlighting in code examples.
Yes, I think this is great as is to be part of fortran-lang. I suggest this procedure:
We create a new repo fortran-lang/manpages.
You archive your repo and add a note at the top of the README that the development has moved to fortran-lang/manpages
If you agree, you lead the project. This doesn’t need to mean a lot of development and time commitment, but you guiding contributors and steering the long-term vision of the project. If you prefer to not lead the project, we find a volunteer to lead it. However, you leading it would be ideal considering your expertise with it.
Yes, I think so. The archive process means literally editing the original README.md and flipping a switch in the settings. I prefer preserving the original archived @urbanjost repository because it’s more history-preserving than just moving the repo to the org. People who visit @urbanjost’s profile could see clearly (without going through the git log) that he is the original creator of the manpages, and they could also discover fortran-lang through it if they weren’t aware of it.
So, I think the value of archiving far outweighs the minor inconvenience of the process, for both @urbanjost and fortran-lang.
That makes sense, though I’m pretty sure search engines penalize double instances.
In other projects I’ve taken over I normally prominently mention the original author in the README instead, though that does not help the repo become more discoverable from the original author profile.
Only the instance with the lower traffic wouldn’t be shown, and that’s exactly the result that we want. If we transitioned the man pages to fortran-lang, people who search for Fortran man pages should be able to find only that one.
