Running Ford on Windows to document Fortran source files

FORD creates HTML documentation for Fortran source code, but it assumes that

  • A directory has all the source files of a program, and no other source files

  • Comments are marked by !!, as opposed to the single ! mandated by the standard.

I wrote a Windows batch file that copies the source files of a program to a directory, replaces ! with !! in those files, runs FORD on them, and opens the generated HTML. The sed utility needs to be installed. It would be nice if FORD could take as input a text file that lists source files and if FORD could be configured to recognize a single ! as a comment.

@echo off
:: usage: runford.bat foo, where foo_files.txt contains a list of source files
:: a subdirectory temp_foo is created, and the source files are copied to that directory
:: they are modified to replace ! comments with !! to match FORD's convention
setlocal
:: create directory to which source files copied
set outdir=temp_%1
mkdir %outdir%
:: create skeleton .md file
set mdfile=%1.md
echo src_dir: .\%outdir% > %mdfile%
:: listfile is a text file containing names of source files, one on each line
set listfile=%1_files.txt
:: copy source files to directory
call copylist.bat %listfile% %outdir%
:: replace ! comments with !!
cd %outdir%
call ex2list.bat ..\%listfile%
:: run FORD and open a generated HTML file
cd ..
call ford %mdfile%
start doc\index.html

copylist.bat batch file
@echo off
:: usage: copylist list.txt dir to copy the files in list.txt to directory dir
for /f %%x in (%1) do copy %%x %2

ex2list.bat batch file
:: replace "! " with "!! " for files in %1
for /f %%x in (%1) do call ex2.bat %%x

ex2.bat batch file:
:: replace “! " with “!! "
setlocal
set tmpfile=temp_temp.txt
copy %1 %tmpfile%
sed s/”! “/”!! “/g %tmpfile% | sed s/”!!!”/"!!"/g > %1

Have you tried altering one of the docmark settings in the project file?

The settings are explained here:

I believe you can leave docmark: empty, to use a single single exclamation mark. This might lead to some problems, as FORD could have trouble to differentiate between comments which precede or follow modules/subroutines/functions, comments which belong to the interface dummy variables or derived type members, and finally developer comments which are not supposed to be included in the generated HTML documentation.

The double exclamation mark !! is simply a default setting in FORD to allow the parser to differentiate between comments with different purposes. There are no intentions to do things differently than mandated by the standard.

Concerning your first bullet point, there are also settings to specify additional source directories, or exclude certain files. The documentation is here:

That said, I never really liked the additional burden of having to maintain the FORD project file, on top of my project Readme, build system files, etc.

Still, it is one of the rare solutions for site generation available in the Fortran world.

1 Like