Skip to content

Fix incorrect handling for the summary key in documentation metadata #703

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Conversation

kuanchihwang
Copy link
Contributor

When the summary key is used in documentation metadata, FORD generates garbled contents for the summary field of the documented program unit.

For example, with the documentation metadata below,

!> summary: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
!>          Fusce ultrices tortor et felis tempus vehicula.
!>          Nulla gravida, magna ut pharetra.

FORD generates the following HTML source code, which is obviously incorrect:

<p>L\no\nr\ne\nm</p>\n<p>i\np\ns\nu\nm</p>\n<p>d\no\nl\no\nr</p>\n<p>s\ni\nt</p>\n<p>a\nm\ne\nt\n,</p>\n<p>c\no\nn\ns\ne\nc\nt\ne\nt\nu\nr</p>\n<p>a\nd\ni\np\ni\ns\nc\ni\nn\ng</p>\n<p>e\nl\ni\nt\n.</p>\n<p>F\nu\ns\nc\ne</p>\n<p>u\nl\nt\nr\ni\nc\ne\ns</p>\n<p>t\no\nr\nt\no\nr</p>\n<p>e\nt</p>\n<p>f\ne\nl\ni\ns</p>\n<p>t\ne\nm\np\nu\ns</p>\n<p>v\ne\nh\ni\nc\nu\nl\na\n.</p>\n<p>N\nu\nl\nl\na</p>\n<p>g\nr\na\nv\ni\nd\na\n,</p>\n<p>m\na\ng\nn\na</p>\n<p>u\nt</p>\n<p>p\nh\na\nr\ne\nt\nr\na\n.</p>

The expected output should be:

<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Fusce ultrices tortor et felis tempus vehicula. Nulla gravida, magna ut pharetra.</p>

This PR ensures that the summary field correctly contains a single paragraph of text.


To reproduce this issue, consider the minimal reproducible example below.

  1. test_summary_key.md
---
project: Test Summary Key
summary: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
         Fusce ultrices tortor et felis tempus vehicula.
         Nulla gravida, magna ut pharetra.
author: Tester
---

Test the `summary` key in project and documentation metadata.
  1. src/test_summary_key.f90
!> summary: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
!>          Fusce ultrices tortor et felis tempus vehicula.
!>          Nulla gravida, magna ut pharetra.
!>
!> Descriptions for module `m`.
module m
    implicit none
contains
    !> summary: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
    !>          Fusce ultrices tortor et felis tempus vehicula.
    !>          Nulla gravida, magna ut pharetra.
    !>
    !> Descriptions for function `f`.
    function f(a, b)
        integer, intent(in) :: a, b
        integer :: f

        f = 0
    end function f

    !> summary: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
    !>          Fusce ultrices tortor et felis tempus vehicula.
    !>          Nulla gravida, magna ut pharetra.
    !>
    !> Descriptions for subroutine `s`.
    subroutine s(a, b)
        integer, intent(in) :: a, b
    end subroutine s
end module m
  1. Run FORD to generate the documentation. Inspect the "Modules" and "Procedures" pages.

@ZedThree
Copy link
Member

Thanks @kuanchihwang! Please could you add a test in test_sourceform.py? You can copy test_markdown_codeblocks_bug286 and test_markdown_header_bug286 for how to write this.

Copy link
Member

@ZedThree ZedThree left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @kuanchihwang!

@ZedThree ZedThree merged commit d9daaca into Fortran-FOSS-Programmers:master May 9, 2025
6 checks passed
@kuanchihwang kuanchihwang deleted the staging/fix-summary-key-handling branch June 4, 2025 20:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants