Keep the structure of Description

[gildor478]

This feature request has been migrated from artifact #1446 on forge.ocamlcore.org. It was assigned to user100.

user144 posted on 2014-12-31 11:58:54:

A description field may use \n to structure the text. For example:

Description: CoHTTP is an OCaml library for creating HTTP clients and daemons. It has a portable HTTP parser. Optional dependencies activate functionality:

• Lwt: opam install lwt cohttp
• Lwt and SSL: opam install lwt ssl cohttp
• Async: opam install async cohttp
• Async and SSL: opam install async_ssl cohttp

All newlines are lost when the field is parsed. I do not understand why this was done. I think the original layout should be kept — and maybe at printing one may want to reformat it.

user144 replied on 2014-12-31 12:01:57:

OASISText has Para and BlankLine already so this could be used to partially parse the description (newlines however should be retained).

user102 replied on 2015-01-01 10:36:13:

That is actually a missing part of the documentation.

The "canonical" format of the description field is described here: https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Description

And is defined in: https://github.com/ocaml/oasis/blob/master/src/oasis/OASISText.ml

Basically, if you want to keep the itemized list, you just have to put 1 blank at the beginning of the line (if you are usually indented 2 spaces, indent this line 3 spaces).

If you want to keep the separation betwee "functionality:" and the "* Lwt", you have to replace the blank line by a single ".".

In this case the first paragraph will be a Para, then a BlankLine and then itemized list will be translated to Verbatim list.

I think everything to close the bug is already in place, but we are missing a good documention. I keep the bug open until the documention is written.