ogma-cli: Rendering of description of Cabal file displays quotes incorrectly

[ivanperez-keera]

Description

The description in the cabal file contains two entries with double quotes in the tiles of links. Those double quotes are not displayed correctly on hackage: instead of appearing as ", they are shown as ".

Type

• Bug: information is rendered incorrectly in package documentation.

Additional context

None.

Requester

• Ivan Perez

Method to check presence of bug

The following command shows that there are " present in the documentation:

$ cd ogma-cli
$ cabal v1-sandbox init
$ cabal v1-install --only-dependencies
$ cabal v1-haddock
$ grep -oe '"' dist/doc/html/ogma-cli/ogma/index.html

Visualizing the file using a browser displays:

"Copilot 3", Perez, Dedden and Goodloe. 2020.
"From Requirements to Autonomous Flight", Dutle et al. 2020.

when it should display:

"Copilot 3", Perez, Dedden and Goodloe. 2020.
"From Requirements to Autonomous Flight", Dutle et al. 2020.

Expected result

The grep command above should show no results, indicating that the symbol " is not produced in the HTML output.

Desired result

The grep command above should show no results, indicating that the symbol " is not produced in the HTML output.

Proposed solution

Modify the links to use the correct haddock syntax for double quotes inside links.

Further notes

None.

[ivanperez-keera]

Change Manager: Confirmed that the issue exists.

[ivanperez-keera]

Technical Lead: Confirmed that the issue should be addressed.

[ivanperez-keera]

Technical Lead: Issue scheduled for Ogma 1.(0+X).(8+Y).

Fix assigned to: @ivanperez-keera.

[ivanperez-keera]

Implementor: Solution implemented, review requested.

[ivanperez-keera]

Change Manager: Verified that:

• Solution is implemented:

  • The code proposed compiles passes the tests. Details:
    Docker image:

    FROM ubuntu:trusty
    
    RUN apt-get update
    
    RUN apt-get install --yes software-properties-common
    RUN add-apt-repository ppa:hvr/ghc
    RUN apt-get update
    
    RUN apt-get install --yes ghc-8.6.5 cabal-install-2.4
    RUN apt-get install --yes libz-dev
    
    ENV PATH=/opt/ghc/8.6.5/bin:/opt/cabal/2.4/bin:$PWD/.cabal-sandbox/bin:$PATH
    
    RUN cabal update
    RUN cabal v1-sandbox init
    RUN cabal v1-install alex happy
    RUN apt-get install --yes git
    
    # We install the application first and then test it, in case any tests need to
    # run the tool.
    CMD git clone $REPO && \
        cd $NAME && \
        git checkout $COMMIT && \
        cd .. && \
        cabal v1-install $NAME/$PAT**/ --enable-tests && \
        cabal v1-install $NAME/$PAT**/ --enable-tests --run-tests -j1

    Command:

    $ docker run -e "REPO=https://github.com/NASA/ogma" -e "NAME=ogma" -e PAT="ogma-" -e "COMMIT=194710ef46b5fbe176e23ea9397409f007e0b987" -it ogma-test

  • The solution proposed fixes the issues described. Details:
    The issue is with the documentation and cannot be replicated locally with haddock. Verification is performed by visual inspection, by uploading a package candidate to hackage and checking that the solution makes the quotes be rendered correctly.

• Implementation is documented. Details:
  The change is to the documentation. No further changes to documentation are needed.
• Change history is clear.
• Commit messages are clear.
• Changelogs are updated.
• Examples are updated. Details:
  No examples affected.
• Required version bumps are evaluated. Details:
  No bump needed (change to documentation).

[ivanperez-keera]

Change Manager: Implementation ready to be merged.