`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:

  • [X] 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:
  ```sh
  $ docker run -e "REPO=https://github.com/NASA/ogma" -e "NAME=ogma" -e PAT="ogma-" -e "COMMIT=194710ef46b5fbe176e23ea9397409f007e0b987" -it ogma-test

  • [X] 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.
• [X] Implementation is documented. Details: The change is to the documentation. No further changes to documentation are needed.
• [X] Change history is clear.
• [X] Commit messages are clear.
• [X] Changelogs are updated.
• [X] Examples are updated. Details: No examples affected.
• [X] Required version bumps are evaluated. Details: No bump needed (change to documentation).

[ivanperez-keera]

Change Manager: Implementation ready to be merged.