search

macports / macports-webapp

Web application to display information about ports, build history and installation statistics
https://ports.macports.org/
BSD 2-Clause "Simplified" License
53 stars 25 forks source link

Multi-paragraph long descriptions (or could be: Long description formatting) #322

Closed jasonliu-- closed 3 months ago

jasonliu-- commented 2 years ago

In the long_description of Portfiles, it's possible to create long descriptions with multiple paragraphs by using two newlines, i.e. \n\n. Would it be possible to also display them on the website as separate paragraphs?

Also, some long_descriptions may include bulleted lists, typically using * as the bullet point character. This happens to also be the typical character used by many markup formatting systems (e.g. Markdown, Wikiformatting, etc.) to signal a bulleted list, which gets displayed as actual bullet point "dots". It might be overkill to include a full-blown Markdown parser, but maybe it would be possible to manually include a small subset to automatically convert to "pretty-printed" HTML? I'm thinking maybe just converting * into a <ul>, and converting words/phrases surrounded by backticks into monospaced <tt>, <var>, <code>, or <samp> (even that might be too much of a hassle, since you would need to parse pairs of backticks for it to work).

Discussing the bulleted lists brings me back to the newlines in long_descriptions. A single \n is interpreted as a line break in port info, so maybe that should get displayed as a <br> in the website. At a minimum, converting single newlines to <br> and double newlines to separate paragraphs would allow the long descriptions of ports such as keystroke-explorer, micronaut, mongo-tools, etc. to be displayed properly on the website.

jasonliu-- commented 2 years ago

I just noticed Issue #133, so I supposed this Issue would be counted as a duplicate. My post proposes possible solutions though, so it might still be useful to whoever decides to tackle the issue.

ryandesign commented 3 months ago

Changing newlines into the HTML equivalent is obviously required and is #133. Changing asterisks at the beginning of lines into a bulleted list is reasonable. But I wouldn't try to do more than that. The port description has always been intended to be text, not markup.

Using backticks in descriptions has never been recommended or suggested, as far as I know, and is uncommon. I only count 14 portfiles doing this. I suggest they stop doing that.