ChangeLog

Version 6.0.0

Long overdue, this release contains numerous bug fixes and new features contributed by users.

The exclude_dir project file option is now recursive (e.g., all subdirectories are excluded). This was always the intended behaviour, but a bug prevented it from working. It has the potential to break some people's builds if they relied on it being non-recursive. (Issue #177, PR #194)

New Features:

• Ability to read fixed-form source files with unlimited line length (Issue #208)
• Experimental ability to explicitly specify a lexer for syntax highlighting of non-Fortran source files (Issue #203, PR #217)
• Introduction of controls on graph sizes and depth to improve performance generating graphs of large projects (Issue #176, PR #197, #216, #218)
• Option not to include copies of source files in documentation (Issue #172, PR #241)
• New option to set custom MathJax configurations (PR #195)
• Option to specify which revision of your code the documentation is for (PR #197)
• Multithreading of some parts of the processing (PR #197)
• Progress bars for generating graphs and search index

Bug fixes:

• Fixed crashing when variable names begin with common (Issue #173)
• Improved stability of parsing module procedures (Issues #185, #199)
• Include directories specified using a ~ are now properly evaluated (Issue #134)
• Computed go to no longer mistaken for function call (Issue #207, PR #214)
• Made graphs case-insensitive (Issue #193, PR #201)
• Fixed error in displaying calls to interfaces in certain graphs (Issue #193, PR #201)
• No longer crashes parsing character variables declared with the * notation (Issue #212)
• Various issues generating relative links in documentation (Issue #204, PR #209)
• Interfaces of type-bound-procedures with private implementations are now displayed (Issue #215)
• Fixed recursion errors when making graphs for large projects (Issues #174, #183)
• Now considers explicit interfaces within generic interfaces as callable procedures in their own right (Issue #202)
• Graph project file option now case-insensitive (Issue #219, PR #220)
• Sorting variables now works properly within common blocks
• No longer crashes trying to evaluate the permission of a finalisation procedure (Issue #229)
• Added new checks to ensure arrays aren't mistaken for function calls (Issue #190)
• Comments in an interface defining a constructor will now be displayed (Issue #233)
• Change dict method call to be compatible with Python 3.5 (PR #170)
• Fixed position of hidden anchors so intra-page links up properly
• Explicit imports with the use statement are now case insensitive (PR #178)
• Fixed typo when generating search index (PR #196)
• Fixed name-mangling routines (PR #192)
• Fixed broken links for intrinsic module documentation (PR #197)
• Filter for empty preprocessor flags (PR #214)

Miscellaneous:

• LaTeX symbols inside of bug, note, warning, and to-do environments are now coloured consistently (Issue #184)
• Search results page can now be styled by user-supplied CSS (Issue #184)
• Switched to a new MathJax Markdown extension which provides better rendering and works with newer versions of Markdown (Issues #196, #221, #222, #236)
• Improved display of links to hidden documentation so they no longer look out of place (Issue #182)
• Removed the "all procedures", "all modules", etc. listings from the side of documentation. These were too large to be useful and meant HTML files took up too much disk space (Issue #205)
• Massive reduction in memory use by not storing generated HTML in memory (PR #191)
• Switch from list concatenation to use of iterators to save processing and memory (PR #191)
• Better example project file (PR #169)
• Improved page rendering time by moving import of search information to bottom (PR #175)
• Improved performance of search index generation by filtering which HTML is analysed (PR #178)

Version 5.0.6

Bug fix:

• Fixed regression introduced in v5.0.5 causing FORD to crash when using Python 3 (PR #170)

Version 5.0.5

Bug fixes:

• Fixed exclude_dir settings being ignored (Issue #155)
• Fixed FORD counting zero total lines of files and producing a ZeroDivisionError for libraries with no program (Issue #160)
• Fixed regression caused from improving classification of used entities as public or private (Issue #165)
• Fixed NameError arising in the graphs module when graphviz is not installed (Issue #166)
• Updated dependencies to require version of beautifulsoup4 which won't encounter an error when using LXML in projects with graphs (Issue #154)

Version 5.0.4

Bug fixes:

• favicon path now evaluated relative to project file, as intended
• custom CSS path now evaluated relative to project file, as intended

Version 5.0.3

Bug fixes:

• Paths specified as command line arguments now evaluated relative to PWD, as intended
• Processing of permission attributes for variables (specified after declaration) no longer causes error

Version 5.0.2

Bug fixes:

• Fixed issue where all of the @note, @todo, @warning, and @bug environments were labelled as "Note" (Issue #152)
• Fixed incompatibilities with Python 3 introduced in Version 5.0.0 (Issue #153)

Version 5.0.1

Bug fixes:

• Extensions .F and .FOR now indicate preprocessed fixed-form files, as intended
• Public inherited derived type components now shown, as intended

Version 5.0.0

This is a major release and thus has some non-backwards compatible changes, although every effort has been made to keep them minor.

• The project_dir option in the project file is now src_dir
• By default, internally declared variables, types, etc. within procedures are now hidden. This can be changed to the old behaviour by specifying proc_internals: true in the project file.
• Directories specified in the project file using a relative path are now evaluated relative to the location of that file. Previously they were evaluated relative to the location where FORD is run from. Note that relative directories specified via a command-line flag are still evaluated relative to the current working directory.
• Documentation below a line declaring multiple variables now applies to all of those variables, whereas it previously only applied to the last one on the line.
• Extensions for preprocessing must now be explicitly specified in the project file using fpp_extensions. This allows extensions to be used which are not necessarily upper-case (Issue #137). Defaults were selected so as to give the same result as the old default behaviour.

New Features:

• File dependency graphs are now produced, indicating the order in which files must be compiled (Issue #99)
• Fixed-form code, in files with an extension in fixed_extensions can now be processed (using the fixed2free tool by ylikx)
• The legacy block data (Issue #147) and common features are now supported
• Information is now provided on the number of source lines of code (Issue #98)
• Output now has better support for smaller windows and screens (Issue #103)
• Inherited public components and type-bound procedures (if they are not overridden) of derived types are now shown
• A public type's inheritance from a private type is now shown in graphs
• Environment variables can now be used in Markdown with the syntax ${ENVIRONMENT_VAR_NAME}. If that environment variable exists the text will be replaced by its contents. Otherwise, it will be replaced by an empty string. (Issue #149)
• the @note, @bug, @warning, and @todo environments are no longer limited to a single paragraph. If an @endnote, @endbug, @endwarning, or @endtodo statement is found (before the start of another such environment) then the environment will end there. Otherwise, it will end with the paragraph it opens in, as before. (Issue #135)
• Include directories can now be specified with an --include (or -I) flag at the command line (Issue #143)
• Call-graphs can now identify external procedures located in other files (Issue #140)

Bug Fixes and Miscellaneous:

• Keys for graphs are now specific to the type of graph being used
• Improved handling of attributes for types
• Better handling of permissions for entities used in modules
• Improved layouts when summarizing procedures
• Improved descriptions of where time is spent while making documents

Version 4.6.2

Bug fixes:

• Will no longer crash on FORTRAN77 block data construct, although these will not be documented yet, either (Issue #147)
• Links to source files will now work (Issues #124, #145)
• Derived types whose names start with is will no longer cause FORD to crash (Issue #148)
• Preprocessor (cpp) now sees the __GFORTRAN__ macro as being defined, consistent with its behaviour using traditional mode (Issue #139)

Version 4.6.1

Bug fixes:

• Regression causing MathJax not to work when viewing files locally now fixed (Issue #141)
• Modules now analyzed in proper order even when containing procedures using other modules (Issue #138)

Version 4.6.0

New features:

• Arbitrary preprocessor can now be specified (Issue #117, PR #129)
• CPP now used as default preprocessor instead of gfortran, as former is more widespread (note that this should not change results of preprocessing)
• Pages now ordered according to file-name (Issue #121, PR #122)
• Integration of Gitter sidecar
• Optionally print date documentation created in the page footer (PR #115)
• Can export graphs as SVG images and graphviz source (Issue #97)
• Single global switch now available to hide local variables, derived types, etc. within procedures (Issue #100)
• Support for coloured edges in graphs, which can make it easier to read large graphs (Issue #113)

Bug fixes:

• \g in character literal no longer causes crash (Issue #136)
• No longer interprets concurrent in do concurrent as function call (Issue #131)
• Header doesn't cover links to particular lines of source code in source file pages (Issue #132)
• Copying file trees now works on network file systems (Issue #128)
• :: now accepted in all use statements (Issue #120, PR #123)
• deferred now included in lists of type-bound procedure attributes
• Correct handling of include paths with user's home directory specified by ~ (Part of issue #134)
• Correctly interprets output from preprocessors when running with Python 3 (PR #129)
• Can now copy file hierarchies deeper than 10 directories (PR #127)
• MathJax now works for both HTTP and HTTPS (PR #126)

Version 4.5.4

Bug fix:

• FORD no longer raises an error if it encounters an empty generic interface

Version 4.5.3

Bug fixes:

• Fixed bug where FORD would not recognise procedure attributes when uppercase (Issue #107)
• Fixed failure to recognise end of interface if interface name contains brackets, for instance because it is an operator (Issue #107)
• "All derived types..." link now generated below alphabetical list on main page
• Prevented crashes when trying to generate graphs with unmatched type/constructor interface pairs
• Checking for deferred attribute in type-bound procedures is now case-insensitive (Issue #107)
• Ensured whitespace trimmed from end of prototype procedures for deferred type-bound procedures (Issue #107)
• Fixed bug causing FORD to crash when checking deferred status of inherited type-bound procedures (Issue #107)
• Will no longer crash when printing documentation for deferred generic type-bound procedures (Issue #107)

Version 4.5.2

Various bugfixes:

• Documentation next to the final statement in a type definition now included with the information on the destructor (Issue #109)
• Fixed bug causing all spaces to be removed from the end of a line if that line is continued. This meant that the last token on one line and the first on the next would be combined, causing errors (part of Issue #107).
• Bullet points no longer show up next to check boxes in checklists, if the markdown-checklist extension is used.
• Fixed crash when procedure has empty argument list with whitespace (Issue #106)
• Fixed regression where FORD no longer matches procedure arguments with interfaces (Issue #110)
• Fixed potential problem that a constructor could be considered private by FORD when the corresponding derived type is public
• Fixed regression causing ancestor types not to be properly recognized and linked to if they are in a different module.

Version 4.5.1

Bugfix: Typo corrected which was causing FORD to crash when analyzing interfaces located within programs. See Issue #101.

Version 4.5.0

New features:

• support for Fortran's include statements, which search in the directory containing the file and in the include-directories (Issue #94)
• limited support for the 2008 standard's block constructs, with variables declared within a block not listed (Issue #96)
• limited support for non-Fortran source files, as described in the wiki (Issue #52 )
• displays line numbers next to the source listings on a source-file's page
• can now specify a license for your documentation, which will be displayed in the page footer (see wiki)
• support for FORTRAN77-style parameter statements

Bug fixes:

• improved handling of exclude_dir, so that it won't fail for certain cases (Issue #95) and so that it will now also ignore subdirectories
• can now catch use statements within procedures nested arbitrarily deep within other procedures, programs, and modules

Version 4.4.0

Improvements:

• FORD can now handle custom include-paths for preprocessed files. These are specified in the project file using the include setting. (Issue #90)
• Headings in the sidebar now start out collapsed. They can be uncollapsed by clicking on the title in the heading. This is to prevent the sidebar being longer than the actual documentation on the page. Thanks to Jérémie Burgalat for suggesting and doing the initial work on this.

Bug fixes:

• Fixed bug causing information about generic type-bound procedures to be left blank (Issue #92)
• Long names will no longer overflow the sidebar, but will be truncated and given ellipsis dots

Version 4.3.0

Improvements:

• Added ability to pan and zoom on large graphs (Issue #87)
• Added support for enumerators (Issue #88)
• Added IEEE subroutines to the list of intrinsic procedures (Pull Request #80)
• Faster generation of search database, if lxml is installed

Bug Fixes:

• Ensured case-insensitivity of when identifying function calls (e.g. Issues #86)
• No intent now recognized as different from intent(inout) (Pull Request #80)
• Removed from spaces from recorded names of intrinsic procedures (70e3d1e5)
• FORD no longer crashes if the Graphviz binaries are not installed

Version 4.2.3

Added graphviz package as a dependency.

Version 4.2.2

Various bugfixes:

• Fixed attribute statements not being correctly parsed and could be misidentified as function calls (Issue 76)
• Fixed functions not being recognized if result() was placed after bind(c) (Issue 77)
• Fixed FORD crashing if a deferred type-bound procedure was added to a type-bound generic interface (Issue 79)
• More Fortran intrinsic procedures and keywords are now recognized and ignored when searching for function calls (Issue 78, Issue 82, Pull Request 80)
• Broken link to page-tree fixed (Issue 81)
• Dummy arguments with no intent now allowed (Pull Request 80)
• name='...' now being noted in bind(c)

Version 4.2.1

Fixed bugs in graph-generating which occurred if call-graphs had circular dependencies. Also changed the program-flow slightly so as to run faster when graphs are not being generated. Finally, fixed a mistake which meant that backtraces would not be produced during generation of documentation, even if --debug was used.

Version 4.2.0

New features:

• Ability to produce graphs describing:
  • module dependencies
  • derived type inheritance
  • procedure call-trees (except for type-bound procedures)
• Support for only statement and rename-lists within use statement
• Support for volatile and asynchronous statements
• Support for non-ASCII characters in documentation (Issue 73)

Bug Fixes:

• Fixed errors which occurred when using Python 3 (Issue 72)
• Fixed bug causing initial values in a character array to all be displayed as identical (Issue 71)
• Fixed problems which arose with submodules
• Fixed various regressions (e.g. Issue 70) and areas in code which could potentially cause problems

Code refactoring:

• Output module rewritten to be object-oriented
• Moved argument parsing and configuration processing to separate method from main()
• Entry point is now run() which gets configurations and passes them to main()

Version 4.1.0

New features:

• adds support for submodules (a Fortran 2008 feature)
• improved display of abstract derived types (previously there was no indication that they were abstract) and their deferred type-bound procedures (will show the required interface, if one is specified) (Issue 68)
• can now handle multiple entities of the same type with the same name
• a --debug command-line flag which will cause FORD to produce a backtrace if it encounters an error when parsing a file.

Bug fixes:

• now recognizes module procedures inside generic interfaces even if the word "module" is not used (Issue 69)
• fixed broken links to overloaded operators (Issue 67)
• fixed a regression which caused procedure arguments to be listed in an order different from that found in the source code (Issue 64)

Version 4.0.1

Fixed a bug which caused FORD to try to interpret the class default statement in a select type construct as a variable declaration.

Version 4.0.0

Non-backwards compatible changes:

• Removed -v/--verbose and --no-warn from CLI, as they were unnecessary
• Changed the default predocmark_alt from # to |
• Meta-data no longer displayed in procedure, interface, and derived type summaries if those entities have their own page

New features:

• Can now change sort order
• Option to force FORD to read all non-string and non-comment source code as [lower case] (https://github.com/cmacmackin/ford/wiki/Project-File-Options#lower)
• Support for coarrays
• Option to turn off search feature, either in project file or at command line (useful for large projects, as generating the search database can take a long time)
• Recognition of intrinsic and common third-party modules, with links to external documentation (iso_fortran_env, iso_c_binding, ieee_arithmetic, ieee_exceptions, ieee_features, omp_lib, mpi, mpi_f08, openacc)
• Ability to add recognition of third-party modules and links to their documentation

Bug fixes:

• Fixed extraneous text resulting from using the markdown.extras.abbrv plugin with abbreviations in the project summary (Issue 61)
• Fixed links to functions in modules (Issue 60)
• Fixed a warning which was sometimes raised by Beautiful Soup (Issue 59)

Version 3.1.0

Fixed bugs causing certain files (e.g. CSS and JavaScript) to appear to never be updated. This can be problematic with certain build systems. Also fixed an error which caused the pages feature to be unable to copy sub-directories. Finally, fixed an issue which could have potentially broken the command-line -w/--warn option.

Added a -q/--quiet option to the CLI (as well as a quiet setting for project file metadata) which suppresses all output from FORD.

Version 3.0.2

Fixed bug in link to a single source file in the main menu, if the file name contained an uppercase letter.

Version 3.0.1

Fixed errors when documentation followed alternative documentation. Also added checks to ensure that none of the docmarks are the same. This was supposed to be in the previous release, but was overlooked.

Version 3.0.0

• Added option to exclude contents of directories
• Fixed a bug in creating output files in Windows
• Now preprocesses code from files whose extensions indicate that this is necessary, prior to extracting documentation. This can be deactivated. The user can also specify which macros should be provided to the preprocessor.
• Change the meta-data settings "deprecated" and "warn" so that their value now needs to be "true" in order to have any effect.
• predocmark, docmark_alt, and predocmark_alt now have the default values of >, *, and #, respectively.
• Improved support for parsing type-bound procedures.

Version 2.1.0

• Added support for linking to other parts of the documentation.
• Introduced option to include a procedure's, derived type's, or programs's syntax-highlighted source code at the bottom of its documentation page. Can be specified globally and overridden for specific items.
• Added option to change what will be displayed for a particular portion of a project. Also added a 'none' option to display settings, causing all contents of an item to be hidden.
• Created new way of specifying documentation. This allows a special docmark to be designated which indicates that all comments in the following block should be counted as documentation. This can apply for comments before or after whatever item is to be documented.

Version 2.0.0

• Altered the CLI so that the Python argparse help message is more accurate
• Added support for extra variable types (useful when software uses certain libraries)
• Fixed handling of abstract interfaces, so that they are now treated as distinct from normal interfaces
• Added ability to produces links to abstract interfaces when being used to declare a procedure pointer
• Reworked internal treatment of interfaces in general
• Added support for multiple directories containing source files
• Improved checking if project_dir within output_dir
• Added |url| and |media| macros
• Added ability to produce a page hierarchy, not linked to any particular source code
• Added ability to recognize implicitly declared arguments
• Added F90, F95, F03, F08 to list of default extensions to scan

Version 1.1.0

• Added support for Python3 (thanks to Jacob Williams for implementing this)
• Added a -V/--version option to the command line interface, so that you can check which version of FORD is installed.
• Fixed a regression where FORD was looking for any included markdown files relative to where it was being run, rather than relative to the project file.

Version 1.0.1

• Fixed a bug which was causing FORD to crash in some circumstances when handling abstract interfaces. This bug would likely have also been present for the handling of interfaces to non-module procedures.

Version 1.0.0

• Formal adoption of semantic versioning. The API, as described here, should now be considered stable.
• Ability to specify documentation preceding the code which it is documenting (thanks to mrestelli for contributing that improvement).
• Small bug fixes.

Version 0.5

• Fixed a problem in reader.py which caused it to split lines even if semi-colons were within strings.
• Fixed conflicts between including Markdown files in documentation and any other syntax (particularly that found in code fragments). However, this required breaking the API, as the syntax for including a file is now {! filename !}.
• Fixed a bug whereby if documentation lacks meta-data but has a colon in the first line it would cause an error (as Markdown would try to interpret that as meta-data).